Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

documentation-guidelines

Coordinator-routed specialist for documentation architecture, broad audits, canonical ownership, module/feature docs, contracts, workflows, runbooks, or stale-content consolidation. Use after project-development-mindset makes documentation the primary deliverable, or directly when explicitly invoked or installed standalone. Do not use for routine docs alignment accompanying code or configuration changes.

thienanblog · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add thienanblog/awesome-ai-agent-skills --skill documentation-guidelines

About this skill


name: documentation-guidelines description: Coordinator-routed specialist for documentation architecture, broad audits, canonical ownership, module/feature docs, contracts, workflows, runbooks, or stale-content consolidation. Use after project-development-mindset makes documentation the primary deliverable, or directly when explicitly invoked or installed standalone. Do not use for routine docs alignment accompanying code or configuration changes.

Documentation Guidelines

Goal

Treat documentation as durable semantic context for agents. Capture what code cannot safely explain alone: business intent, ownership, invariants, lifecycle, permissions, side effects, contracts, operational constraints, and decision rationale. Let source and tests own implementation detail and executable evidence.

Prefer compact facts over tutorial prose. Follow repository instructions and existing conventions; do not impose a standard directory tree.

Run this skill in the main conversation. Delegation can increase usage; do not use subagents unless the user explicitly approves the proposed agent count and scope. Ask again before expanding an approved scope.

Read only the relevant reference:

  • references/templates.md for module, feature, workflow, contract, or runbook docs.
  • references/architecture.md for multi-owner routing, registries, and structure.
  • references/audit-cleanup.md for broad audits, consolidation, or stale-doc removal.

Context Protocol

Start with documentation before broad source exploration:

  1. Read repository instructions and the nearest documentation router or index.
  2. Read the owner document for the relevant scope.
  3. Follow its required-context links for parent scope, contracts, dependencies, state models, decisions, and operational constraints.
  4. Use named source and test anchors to verify missing, risky, or plausibly stale facts; do not rediscover the whole system from code by default.
  5. Ask a targeted question only when docs, focused evidence, and history cannot resolve a fact or a product decision is required.

Do not cap reading by file count. Stop when the completeness gate passes, and do not follow merely related links after that point. Mark required context separately from additional context when the distinction prevents over-reading or missed dependencies.

Context Completeness Gate

Before relying on docs, be able to state the applicable:

  • Business outcome, scope, non-goals, and terminology.
  • Actors, permissions, preconditions, and triggers.
  • Rules, invariants, lifecycle or state transitions, and failure paths.
  • Inputs, outputs, persisted facts, public contracts, and compatibility constraints.
  • Side effects, transaction boundaries, retries, and idempotency expectations.
  • Ownership boundaries, upstream dependencies, and downstream consumers.
  • Authoritative source and test anchors, plus unresolved or intentionally unspecified behavior.

Omit inapplicable items. Treat an unknown applicable item as a documentation gap: follow required context, verify focused evidence, and update its canonical owner when the task includes documentation changes.

Documentation Impact Gate

Update docs only when a durable fact would otherwise become wrong or undiscoverable.

ChangeDefault action
Internal refactor, test-only change, formatting, or bug fix restoring documented behaviorNo docs change unless a documented route or evidence anchor changed
User-visible behavior, business rule, workflow, or stable feature scopeUpdate its canonical owner
API, schema, event, permission, validation, compatibility, or cross-boundary contractUpdate the contract owner and only affected consumer or relationship mappings
Setup, migration, deployment, recovery, queue, schedule, or operational behaviorUpdate the owning runbook or reference
Add, rename, move, archive, or remove an owned entityUpdate its owner and minimum discovery routes
Obsolete, duplicated, or contradictory docsPreserve valid facts in owners, fix routes, then remove the stale copy when Git history is sufficient

Do not edit docs merely to record a review. Keep plans, raw commands, screenshots, CI output, and implementation history in the task, pull request, tests, CI, or Git unless they encode a durable operational requirement.

Ownership And Routing

  • Give every durable fact one canonical enforcement owner.
  • Routers resolve ownership and link to context; they do not copy owner content.
  • Consumer docs link to owned contracts and record only local mapping, behavior, error handling, or constraints.
  • Add registries only when repeated discovery across many entities justifies them; generate alternate catalogs when practical.
  • Map only dependencies that cross ownership boundaries and materially affect behavior, compatibility, deployment, data, or operations.
  • Prefer existing names and layout. Stable headings, searchable business terms, and exact links matter more than prescribed filename suffixes.
  • Use frontmatter only when tooling or routing consumes it. Avoid mechanical dates, versions, ownership fields, and status metadata that will rot.
  • Keep historical records only for an active coordination, audit, legal, migration, or operational need, outside the default context path when possible.

Authoring Rules

  • Write facts, rules, boundaries, exceptions, negative rules, and compact examples; omit explanations of concepts a capable agent can infer reliably.
  • Prefer stable headings, short bullets, exact mapping tables, and diagrams only for non-trivial flows or relationships.
  • Provide a small set of stable evidence anchors: symbols, entrypoints, schemas, commands, or test suites rather than line numbers or source inventories.
  • Separate required context, additional context, and evidence anchors when useful.
  • Link another owner's contract instead of paraphrasing it; record only local consequences.
  • Exclude
Read the complete source ↗