| name | agents-md-upgrade |
| description | Create or improve AGENTS.md files so agents know the active product surface, architecture boundaries, validation commands, debug workflows, observability surfaces, isolation rules, and maintenance rules. |
AGENTS.md Upgrade
Use this skill when the user asks to improve agent instructions or when an audit finds weak or missing AGENTS.md coverage.
Required Sections
For most repos, a strong AGENTS.md should cover:
- project identity and active code paths
- inactive or archived paths to avoid
- architecture/source-of-truth boundaries
- run/build/test commands
- narrow validation defaults by touched area
- debug entry points and artifact paths
- observability surfaces
- isolation and reset rules
- credentials and external service caveats
- rules for updating
AGENTS.md
Upgrade Rules
- Preserve existing durable project rules.
- Remove stale one-off debugging notes when they conflict with current behavior.
- Add scoped
AGENTS.md files only when subtrees need different rules.
- Keep instructions short enough to be used under pressure.
- Prefer exact commands over prose.
