SKILL.md
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 | agentdocs/codeconventions.md |
✓ |
| Core Invariants | agentdocs/codeconventions.md |
✓ |
| Common Pitfalls | agentdocs/codeconventions.md |
✓ |
| Tool Selection | agentdocs/codeconventions.md |
✓ |
| Atomic Change Rules | agentdocs/gitworkflow.md |
✓ |
| Required Checks | agentdocs/buildingthe_project.md |
✓ |
| Git Workflow | agentdocs/gitworkflow.md |
✓ |
| Feature Flags | agentdocs/buildingthe_project.md |
✓ |
| Security | agentdocs/codeconventions.md |
✓ |
| Environment Variables | agentdocs/codeconventions.md |
✓ |
| Performance Targets | agentdocs/codeconventions.md |
✓ |
| Disk Space | agentdocs/buildingthe_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-agentskill 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 # Must be ≤140
ls agent_docs/ # Verify all files existQuality Checks
-
wc -l AGENTS.md≤ 140 - All sections mapped to agent_docs/
- agent_docs/ files have code examples
- Can follow agent_docs/ instructions independently
- Cross-References table lists all agent_docs/
Best Practices
- Follow agentskills.io spec
- Keep SKILL.md under 250 LOC
- agent_docs/ files must be usable as standalone instructions
See [references/AGENTSUPDATEREFERENCE.md](references/AGENTSUPDATEREFERENCE.md) for detailed workflow.