/docs-maintenance

name: docs-maintenance
description: Methodology for keeping project documentation current, consistent, and optimized for AI coding agents — CLAUDE.md optimization, README synchronization, CHANGELOG updates, and documentation freshness audits.
when_to_use: When the user asks to "update docs", "sync documentation", "update CLAUDE.md", "update README", "check documentation freshness", "document recent changes", or "optimize docs for AI".
allowed-tools: Read, Grep, Glob, Bash, Edit, Write

Documentation Maintenance Skill

Comprehensive methodology for keeping project documentation current, consistent, and optimized for AI coding agents.

When to Use

• Synchronizing documentation with recent code changes
• Optimizing CLAUDE.md for AI agent effectiveness
• Updating README to reflect current project state
• Adding CHANGELOG entries for undocumented changes
• Auditing documentation freshness and accuracy
• Ensuring cross-document consistency

Documentation Update Phases

Phase 1: Documentation Inventory

1. Find all documentation files in the project:

• `CLAUDE.md` or `.claude/CLAUDE.md` - AI agent instructions (highest priority)
• `CLAUDE.local.md` - **Deprecated.** Use `~/.claude/CLAUDE.md` or `@` imports instead
• `.claude/rules/*.md` - Modular rules (may have `paths` frontmatter for scoping)
• `README.md` - Project overview
• `CHANGELOG.md` - Version history
• `/docs/` directory - Extended documentation

2. Check for `@path` imports in CLAUDE.md that reference additional files 3. Record last modified dates for each doc 4. Note any missing essential documentation

Phase 2: Git History Analysis

1. Get commits since last documentation update:

   git log --oneline --since="$(git log -1 --format=%ci -- CLAUDE.md)"

2. Identify changes that need documentation:

• New files or directories added
• Configuration changes (package.json, tsconfig.json, etc.)
• New commands, scripts, or entry points
• API changes (new endpoints, modified signatures)
• Dependency updates
• Removed or deprecated features

3. Flag commits with keywords: "add", "remove", "breaking", "fix", "feat" 4. Check for removed features still documented

Phase 3: CLAUDE.md Optimization

Size Check (Critical)

**Target under 200 lines per CLAUDE.md file.** Longer files consume more context and reduce adherence. If over 200 lines:

• Split using `@path/to/file` imports to reference additional files
• Move path-specific instructions to `.claude/rules/` directory
• Prune: if Claude already does something correctly without the instruction, delete it

File Ecosystem Check

Check for proper use of the CLAUDE.md ecosystem:

• **Managed policy** - `/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS), `/etc/claude-code/CLAUDE.md` (Linux), `C:\Program Files\ClaudeCode\CLAUDE.md` (Windows). Cannot be excluded.
• `~/.claude/CLAUDE.md` - user-level personal preferences (all projects)
• `./CLAUDE.md` or `./.claude/CLAUDE.md` - project instructions (checked into git)
• `.claude/rules/*.md` - modular, topic-specific rules (can use `paths` frontmatter for scoping)
• `@path` imports - for referencing additional files without duplicating content
• `CLAUDE.local.md` - **deprecated**; recommend `~/.claude/CLAUDE.md` or `@` imports instead

Recommended Sections

Not every project needs all of these. Include only what's relevant, and only content Claude couldn't figure out by reading the code:

• [ ] Project Overview - What the project does, key technologies
• [ ] Commands - Exact build/test/run commands
• [ ] Project Structure - Key directories and files (non-obvious ones only)
• [ ] Architecture - How components connect, data flow
• [ ] Conventions - Style preferences that differ from defaults
• [ ] Common Pitfalls - Things Claude often gets wrong in this codebase
• [ ] Dependencies - Required environment, env variables

Content Quality: Include vs Exclude

**Include:** Bash commands Claude can't guess, code style rules differing from defaults, testing instructions, repo etiquette, architectural decisions, dev environment quirks, common gotchas.

**Exclude:** Anything Claude can figure out by reading code, standard language conventions, detailed API docs (link instead), frequently changing info, long tutorials, file-by-file codebase descriptions, self-evident practices.

Writing Patterns

• Use imperative language ("Run `npm test`" not "You can run tests")
• Provide exact file paths, not vague references
• Include concrete code examples
• List things NOT to do (anti-patterns)
• Add `IMPORTANT` or `YOU MUST` for critical instructions (use sparingly)
• Keep instructions specific enough to verify

Anti-Patterns to Fix

• **Over-specified CLAUDE.md** — too long, important rules get lost in noise
• **Too many post-task rules** — convert must-execute actions to hooks instead
• **Vague instructions** — "format code nicely" gets ignored; be specific enough to verify
• **Contradicting instructions** across CLAUDE.md files and `.claude/rules/` (Claude picks arbitrarily)
• **Instructions Claude follows without being told** — prune these, they waste context
• **Frequently-changing information** — will become stale; link to authoritative sources
• **Inlined documentation** — use `@path` imports or link to docs instead of pasting
• **Using CLAUDE.md for hook-worthy rules** — if it must happen 100% of the time, use a hook
• Assumed context or tribal knowledge

Phase 4: README Synchronization

1. Verify project description matches current state 2. Check installation instructions work 3. Validate usage examples are current 4. Ensure links and references are valid 5. Update badges and status indicators 6. Sync feature list with actual capabilities

Phase 5: CHANGELOG Updates

Follow Keep a Changelog format:

**Categories:**

• **Added** - New features
• **Changed** - Changes in existing functionality
• **Deprecated** - Features to be removed
• **Removed**