maintaining-instruction-files

What this skill does

# 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.

## When to Use

**Use this skill when:**
- Creating new CLAUDE.md or AGENTS.md
- Instruction file exceeds 200 lines (warning) or 300 lines (action required)
- Adding content to instruction files
- Migrating CLAUDE.md to AGENTS.md standard
- Auditing instruction file quality
- Reviewing PRs that modify instruction files

**When NOT to use:**
- General documentation updates (use maintaining-docs-after-changes)
- Creating docs/ content (use organizing-documentation)
- Trivial typo fixes

## Quick Reference

| Size | Status | Action |
|------|--------|--------|
| <200 lines | ✅ Good | Maintain quality |
| 200-300 lines | ⚠️ Warning | Consider extraction |
| >300 lines | ❌ Action required | Run extraction workflow |

| Principle | Implementation |
|-----------|----------------|
| Size discipline | Count lines, extract if >300 |
| Universal relevance | Remove edge cases |
| Tool-first | Reference skills/linters, not rules |
| Reference, don't include | Link to docs/, don't duplicate |
| Multi-agent neutral | No "Claude should...", use AGENTS.md |

## Core Principles

### 0. Context Window is Precious

The AI's context window is limited and valuable - fill it with high-value information, not exhaustive minutiae. Every token spent on instruction files is a token not available for actual work context.

**Research finding:** As instruction count increases, model performance in following them degrades linearly. Even frontier models show this effect. Smaller models are especially prone to instruction overload.

**Claude Code behavior:** Claude's system actively tells the model to skip context files unless they're highly relevant to the current task. If most content appears irrelevant, the model may ignore the entire file. This means bloated instruction files can be worse than no instruction file at all.

### 1. Size Discipline

```bash
# Check current size
wc -l AGENTS.md CLAUDE.md 2>/dev/null || wc -l CLAUDE.md
```

**Thresholds:**
- <200 lines: Ideal, focused and effective
- 200-300 lines: Warning, review for extraction opportunities
- >300 lines: Must extract content to docs/

**Optimization target:** Minimize instruction count, not just line count. Fewer well-chosen instructions outperform many rules. Aim for the minimum guidance that covers essential context.

**What counts as "one instruction"?**

Multiple instructions (counted separately by AI):
```markdown
- Always run tests before committing
- Always run linting before committing
- Always run type checking before committing
```

Single instruction (counted as one):
```markdown
- Run all quality checks before committing: `npm run test && npm run lint && npm run typecheck`
```

**Consolidation strategies:**
- Combine related checks into one command
- Group by workflow stage instead of tool
- Use scripts that run multiple checks
- Reference skills instead of listing steps

### 2. Universal Relevance

Every line must apply to **most tasks**. Test each section:
- "Does this apply when fixing bugs?" → Must be Yes
- "Does this apply when adding features?" → Must be Yes
- "Is this only relevant for [specific scenario]?" → If Yes, extract to docs/

### 3. Tool-First Content

**Wrong:** Listing style rules in instruction file
```markdown
## Code Style
- Use camelCase for variables
- 2-space indentation
- No trailing whitespace
```

**Right:** Reference tools
```markdown
## Code Style

Use project linters and formatters. Run `npm run lint` before commits.
```

### 4. Reference, Don't Include (Progressive Disclosure)

This principle implements **progressive disclosure** - a pattern where detailed information is available but not loaded until needed.

**Why it works:**
- AI assistants can follow links to fetch detailed docs when relevant
- Main instruction file stays light, focused on universal context
- Detailed instructions are available but not consuming context window space in every session
- AI decides what to fetch based on current task

**Pattern:**
1. Keep 2-3 sentence summary in instruction file
2. Link to detailed doc with "See [path] for details"
3. AI fetches detailed doc only when working on related tasks

**Wrong:** Duplicating content
```markdown
## Architecture
[50 lines of architecture details]
```

**Right:** Linking to docs
```markdown
## Architecture

High-level: [2-3 sentences]

See `docs/UNDERSTAND/architecture.md` for detailed architecture.
```

### 5. On-Demand Knowledge via Platform Tools

Extend the tool-first principle beyond linters to full platform capabilities:

**Available platform tools:**
- **Skills:** Reusable workflows invoked when needed (`Skill(skill: "name")`)
- **Hooks:** Automated actions triggered by events (pre-commit, session-start)
- **MCP servers:** External tools and data sources
- **Slash commands:** User-triggered context injection

**Pattern:** Instead of front-loading all possible context, configure tools to provide context on-demand:

**Wrong:** Putting everything in instruction file
```markdown
## API Guidelines
[100 lines of API patterns, error handling, authentication...]
```

**Right:** Reference skill that provides guidance when needed
```markdown
## API Guidelines

Use project API patterns. Skill `cipherpowers:api-patterns` provides detailed guidance.
```

**Benefits:**
- Instruction file stays concise
- Detailed guidance available when actually needed
- Context window used efficiently
- Guidance can be updated in one place (the skill/tool)

**More examples:**

**Wrong:** Putting git workflow in instruction file
```markdown
## Git Workflow
1. Create feature branch from main
2. Make atomic commits with conventional format
3. Run tests before committing
4. Create PR with template
5. Request review from team lead
6. Address feedback and re-request
7. Squash merge after approval
```

**Right:** Reference commit skill
```markdown
## Git Workflow

Use `/cipherpowers:commit` for atomic commits. Skill: `cipherpowers:commit-workflow`
```

**Wrong:** Listing all debugging techniques
```markdown
## Debugging
- Use debugger breakpoints for step-through
- Add logging statements at key points
- Check error messages and stack traces
- Review recent changes in git log
- Test with minimal reproduction case
[... 20 more techniques]
```

**Right:** Reference debugging skill
```markdown
## Debugging

Use `cipherpowers:systematic-debugging` for investigation workflow.
```

### 6. Multi-Agent Neutral

**Wrong:** Claude-specific
```markdown
Claude should always check tests before...
```

**Right:** Agent-neutral
```markdown
Always check tests before...
```

## Validation Checklist

**Run before completing any instruction file work:**

- [