From cipherpowers
Maintains CLAUDE.md and AGENTS.md instruction files by enforcing size limits (<300 lines), progressive disclosure via docs/ references, multi-agent compatibility, and tool-first content. Use for creation, updates, audits.
npx claudepluginhub cipherstash/cipherpowers --plugin cipherpowersThis skill uses the workspace's default tool permissions.
Specialized workflow for AI instruction files (CLAUDE.md, AGENTS.md). Different from general documentation:
Refactors bloated AGENTS.md, CLAUDE.md, or similar agent instruction files into organized, linked documentation via progressive disclosure. Resolves contradictions, extracts essentials, categorizes and prunes content.
Refactors bloated AGENTS.md, CLAUDE.md, or similar files into progressive disclosure structure: essentials in root, categorized instructions (e.g., testing.md, code-style.md) in linked files.
Optimizes AI-facing instructions for subagents, CLAUDE.md, rules, skills, agents by removing discoverable data, explained knowledge, invented constraints, stale facts. Use for authoring or auditing bloat.
Share bugs, ideas, or general feedback.
Specialized workflow for AI instruction files (CLAUDE.md, AGENTS.md). Different from general documentation:
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.
Use this skill when:
When NOT to use:
| 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 |
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.
# Check current size
wc -l AGENTS.md CLAUDE.md 2>/dev/null || wc -l CLAUDE.md
Thresholds:
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):
- Always run tests before committing
- Always run linting before committing
- Always run type checking before committing
Single instruction (counted as one):
- Run all quality checks before committing: `npm run test && npm run lint && npm run typecheck`
Consolidation strategies:
Every line must apply to most tasks. Test each section:
Wrong: Listing style rules in instruction file
## Code Style
- Use camelCase for variables
- 2-space indentation
- No trailing whitespace
Right: Reference tools
## Code Style
Use project linters and formatters. Run `npm run lint` before commits.
This principle implements progressive disclosure - a pattern where detailed information is available but not loaded until needed.
Why it works:
Pattern:
Wrong: Duplicating content
## Architecture
[50 lines of architecture details]
Right: Linking to docs
## Architecture
High-level: [2-3 sentences]
See `docs/UNDERSTAND/architecture.md` for detailed architecture.
Extend the tool-first principle beyond linters to full platform capabilities:
Available platform tools:
Skill(skill: "name"))Pattern: Instead of front-loading all possible context, configure tools to provide context on-demand:
Wrong: Putting everything in instruction file
## API Guidelines
[100 lines of API patterns, error handling, authentication...]
Right: Reference skill that provides guidance when needed
## API Guidelines
Use project API patterns. Skill `cipherpowers:api-patterns` provides detailed guidance.
Benefits:
More examples:
Wrong: Putting git workflow in instruction file
## 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
## Git Workflow
Use `/cipherpowers:commit` for atomic commits. Skill: `cipherpowers:commit-workflow`
Wrong: Listing all debugging techniques
## 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
## Debugging
Use `cipherpowers:systematic-debugging` for investigation workflow.
Wrong: Claude-specific
Claude should always check tests before...
Right: Agent-neutral
Always check tests before...
Run before completing any instruction file work:
wc -l [file]${CLAUDE_PLUGIN_ROOT} or relative)When instruction file exceeds 300 lines:
Review each section and categorize:
| Category | Target Location | Criteria |
|---|---|---|
| Prerequisites | docs/BUILD/00-START/ | Required before any work |
| Deep dives | docs/UNDERSTAND/ | Detailed explanations |
| Quick refs | docs/LOOKUP/ | < 30 second lookups |
| Edge cases | docs/BUILD/02-IMPLEMENT/ | Specific scenarios |
Move content to appropriate docs/ location:
# Before (in AGENTS.md - 50 lines)
## Database Schema
[Detailed schema documentation...]
# After (in AGENTS.md - 3 lines)
## Database
See `docs/UNDERSTAND/database-schema.md` for schema documentation.
wc -l AGENTS.md
Should now be <300 (ideally <200).
AGENTS.md is the open standard recognized by:
Pattern A: Universal file only
AGENTS.md ← All instructions here
CLAUDE.md (symlink → AGENTS.md)
Pattern B: Universal + extensions
AGENTS.md ← Universal instructions
CLAUDE.md ← Includes @AGENTS.md + Claude-specific
Pattern C: Claude-only (legacy)
CLAUDE.md ← All instructions
Recommend migrating to Pattern A or B.
ln -s AGENTS.md CLAUDE.md@AGENTS.md includeOn Unix/Linux/macOS:
# Create symbolic link (use this for git repos)
ln -s AGENTS.md CLAUDE.md
# Verify it works
ls -l CLAUDE.md # Should show: CLAUDE.md -> AGENTS.md
cat CLAUDE.md # Should show AGENTS.md content
Important:
Verification checklist:
ls -l CLAUDE.md shows symlink arrow (->)cat CLAUDE.md displays AGENTS.md contentDifferent AI systems have different quirks. A Claude-optimized instruction file may not work as effectively with GitHub Copilot directly, and vice versa.
Keep core content the same across platforms, but be prepared to tweak:
When to adapt:
Adaptation strategy:
Instruction files are living documents. Update them as your project evolves and as you learn what helps the AI most.
Review triggers:
Refinement process:
Avoid: Adding instructions preemptively "just in case" - this leads to bloat. Add based on observed need.
| Excuse | Reality |
|---|---|
| "This rule is important" | If not universal, it goes in docs/ |
| "It's only 350 lines" | Models ignore bloated files - attention drops linearly |
| "I'll trim it later" | Size grows, never shrinks without active management |
| "I need it all in one file" | Progressive disclosure via references works better |
| "Users expect comprehensive docs" | Users expect working AI - bloat prevents that |
| "These are all critical rules" | Test: applies to bug fixes AND features? If not, extract |
| Mistake | Fix |
|---|---|
| Adding rules instead of tool references | Point to linters, skills, hooks |
| Including full content from docs | Link with brief summary only |
| Using Claude-specific language | Rewrite agent-neutral |
| Ignoring line count | Check wc -l every edit |
| Creating parallel hierarchy | Reference existing docs/ structure |
| Not verifying commands | Execute each command to test |
${CLAUDE_PLUGIN_ROOT}skills/maintaining-docs-after-changes/SKILL.md - General doc sync${CLAUDE_PLUGIN_ROOT}skills/capturing-learning/SKILL.md - Adding lessons learned${CLAUDE_PLUGIN_ROOT}skills/organizing-documentation/SKILL.md - docs/ structure${CLAUDE_PLUGIN_ROOT}templates/agents-md-template.md${CLAUDE_PLUGIN_ROOT}standards/documentation-structure.mdagents-md-best-practices.md