Agent Config Maintenance

Agent Config Maintenance

Scope

• Target files: AGENTS.md, project-doc sections, skills/*/SKILL.md, and any references under skills/*/references/.
• Focus on separation of concerns: global agent rules vs task-specific workflows.

Workflow

1. Inventory instructions
   • Use rg to find duplicate or conflicting rules across AGENTS, project docs, and skills.
   • Note which rules are global constraints vs task-specific procedures.
2. Decide the split
   • Keep only global, always-on constraints in AGENTS.md.
   • Move task-specific procedures into the relevant skill SKILL.md or references/.
   • Remove duplicated bullets after moving.
3. Update skill metadata
   • Fill SKILL.md frontmatter with name and a trigger-ready description.
   • Keep the description explicit about when to use the skill.
4. Write the skill body
   • Use imperative form.
   • Keep core workflow in SKILL.md.
   • Move large checklists or detailed examples into references/ and link them.
5. Validate consistency
   • Ensure AGENTS and skills do not contradict each other.
   • Verify naming conventions (lowercase + hyphen).
   • Confirm only necessary files exist; avoid extra docs.

Quality gates

• Keep SKILL.md under 500 lines.
• Avoid duplication between SKILL.md and any reference files.
• If adding scripts, run them once to validate behavior.