| name | maintain-agent-docs |
| description | Maintain repository agent guidance. Use for AGENTS.md, CLAUDE.md compatibility, skill drift, duplicated instructions, or context budgets. |
Agent documentation
Keep agent guidance as a routing and correction layer over project sources, not a second documentation system.
Placement
- Put durable, broadly applicable repository facts in the nearest
AGENTS.md.
- Keep each
CLAUDE.md as @AGENTS.md unless Claude-only behavior is genuinely required.
- Put an explicit, repeatable vertical workflow in a skill.
- Keep checked-in skills as direct children of
.agents/skills/; treat .claude/skills/ and .opencode/skills/ as generated directory aliases.
- Put conditional detail in a directly linked skill reference.
- Put rules that can be mechanically checked in code, tests, lint, hooks, or
build/scripts/check-workspace.mjs.
- When the user explicitly requests a durable record, put architecture rationale in
internal/design/, internal/decisions/, or rfc/; never create one as a default by-product of other work.
Process
- Identify the repeated failure or new fact and the executable source that proves it.
- Search existing agent docs and skills for overlap or contradiction.
- Prefer updating a source pointer or validator over copying code, schemas, commands, or examples.
- Remove obsolete guidance in the same change.
- Keep skill frontmatter portable:
name and a precise description only.
- Run
pnpm check:workspace and review the reported context budgets.
Do not add generic software advice the model already knows. Add a rule only when an agent would plausibly get this repository wrong without it.
Example
Input: “Remove duplicated setup instructions from agent guidance.”
Output: Smaller routing docs that point to executable sources, corrected aliases, passing validators, and an updated context-budget report.
