Maintain Agent Docs

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

1. Identify the repeated failure or new fact and the executable source that proves it.
2. Search existing agent docs and skills for overlap or contradiction.
3. Prefer updating a source pointer or validator over copying code, schemas, commands, or examples.
4. Remove obsolete guidance in the same change.
5. Keep skill frontmatter portable: name and a precise description only.
6. 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.