Menu
Decide whether durable documentation is needed, choose the right documentation artifact, and route ADR or project documentation work to the appropriate specialized skill.
| name | documentation-and-adrs |
| description | Decide whether durable documentation is needed, choose the right documentation artifact, and route ADR or project documentation work to the appropriate specialized skill. |
| metadata | {"version":"1.1.0"} |
Use this skill when you need to decide what durable documentation, if any, a change needs. This is a routing and judgment skill. It helps identify the reader, purpose, and best documentation surface, then delegates detailed writing mechanics to narrower skills when they apply.
Good documentation explains intent, constraints, trade-offs, and consequences. It does not restate obvious code or create stale process noise.
Use this skill when:
Do not use this skill for throwaway prototypes, obvious comments, or documentation that has no likely reader or maintenance owner.
Use a specialized skill directly when the needed artifact is already clear:
write-adr when the main task is creating, superseding, numbering, naming,
or indexing an architecture decision record.update-project-docs when the main task is updating README, changelog,
usage, configuration, migration, operational, or troubleshooting documentation.Before writing, state:
Choose the smallest durable format that fits the need.
Common types include:
Prefer the existing canonical documentation surface over creating a duplicate. If no durable reader or maintenance owner exists, skip the documentation change and explain why.
Use the narrowest skill that owns the concrete mechanics:
write-adr.update-project-docs.Do not delete old ADRs. If a decision changes, write a new ADR that supersedes or deprecates the old one.
Some changes need more than one artifact. Check whether the change affects:
When multiple artifacts are needed, keep each one focused. Put rationale in ADRs, usage in project docs, contracts in interface docs, and procedures in runbooks.
For public or cross-boundary interfaces, document:
Use the project’s preferred contract format, such as schema files, reference docs, types, command help, examples, or generated documentation.
Inline comments should explain non-obvious intent, constraints, or hazards.
Good comments answer:
Avoid comments that restate syntax, preserve deleted code, or create TODOs with no owner or timeframe.
Before handoff:
write-adr when neededupdate-project-docs when neededCreate, update, or review Agent Skill directories and SKILL.md files for valid frontmatter, structure, portability, progressive disclosure, and validation readiness.
Extracts what the user actually wants instead of what they think they should want. Achieves this through one-question-at-a-time interview until ~95% confidence about the underlying intent. Use when an ask is underspecified ("build me X" without "for whom" or "why now"), when the user explicitly invokes ("interview me", "grill me", "are we sure?", "stress-test my thinking"), or when you catch yourself silently filling in ambiguous requirements before any plan, spec, or code exists.
Discover and run the project's local formatting, linting, static analysis, test, and build checks before handoff.
Update project-facing documentation after a user-visible behavior, configuration, operation, or workflow change.
Discovers and invokes agent skills. Use when starting a session or when you need to discover which skill applies to the current task. This is the meta-skill that governs how all other skills are discovered and invoked.
Add logs, metrics, traces, profiling, or operational notes for meaningful workflows without unsupported performance claims.
