maintaining-instruction-files
Maintaining Instruction Files
Overview
Specialized workflow for AI instruction files (CLAUDE.md, AGENTS.md). Different from general documentation:
- Size-constrained: <200 lines ideal, <300 max
- AI-audience: Directive style, third-person
- Progressive disclosure: Reference docs/, don't include content
- Multi-agent: AGENTS.md standard works with any AI assistant
Why this matters: Quality instruction files create a virtuous cycle - better context leads to better AI output, which builds trust, which leads to more investment in refined guidance. Poorly maintained instruction files cause the opposite: AI makes mistakes, trust erodes, teams abandon the approach.
Announce at start: "I'm using the maintaining-instruction-files skill to work on this instruction file."
Critical Infrastructure Warning: Instruction files are NOT documentation - they're critical infrastructure that shapes every AI interaction. A single poorly-thought-out line can mislead the AI in every session. Never accept auto-generated instruction files without careful manual review and curation.
Terminology note: These files are sometimes called "memory files" in multi-agent literature (as in agents-md-best-practices.md), but we use "instruction files" to emphasize their directive role in shaping AI behavior rather than storing information.