agents-md-upgrade

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.