| name | agents-update |
| description | Update AGENTS.md and agent_docs/ following best practices. Use when modifying agent guidelines, adding new documentation, or restructuring agent instructions. |
AGENTS.md Update
Keep AGENTS.md under 140 LOC. Move detailed content to agent_docs/, don't just delete.
Core Rule
AGENTS.md ≤ 140 LOC: Quick reference + links only
agent_docs/: Complete instructions with examples
Section Mapping
| AGENTS.md Section | Target agent_docs/ File | Status |
|---|
| Quick Reference | scripts/ | ✓ commands |
| Change Workflow | agent_docs/code_conventions.md | ✓ |
| Core Invariants | agent_docs/code_conventions.md | ✓ |
| Common Pitfalls | agent_docs/code_conventions.md | ✓ |
| Tool Selection | agent_docs/code_conventions.md | ✓ |
| Atomic Change Rules | agent_docs/git_workflow.md | ✓ |
| Required Checks | agent_docs/building_the_project.md | ✓ |
| Git Workflow | agent_docs/git_workflow.md | ✓ |
| Feature Flags | agent_docs/building_the_project.md | ✓ |
| Security | agent_docs/code_conventions.md | ✓ |
| Environment Variables | agent_docs/code_conventions.md | ✓ |
| Performance Targets | agent_docs/code_conventions.md | ✓ |
| Disk Space | agent_docs/building_the_project.md | ✓ |
| Planning & Decisions | plans/ROADMAPS/ROADMAP_ACTIVE.md | ✓ |
Workflow
1. Read Current State
- Read AGENTS.md and relevant agent_docs/ files
- Check Section Mapping table
- For complex changes, use
goap-agent skill to decompose
2. Move Content (Not Delete!)
- Find target location from mapping
- Add full content with examples
- Ensure standalone usability
3. Update AGENTS.md
- Replace with brief summary + reference link
- Keep under 140 LOC
4. Validate
wc -l AGENTS.md
ls agent_docs/
Quality Checks
Best Practices
- Follow agentskills.io spec
- Keep SKILL.md under 250 LOC
- agent_docs/ files must be usable as standalone instructions
See references/AGENTS_UPDATE_REFERENCE.md for detailed workflow.
