agent-md-refactor

# Agent MD Refactor Refactor bloated agent instruction files (AGENTS.md, CLAUDE.md, COPILOT.md, etc.) to follow **progressive disclosure principles** - keeping essentials at root and organizing the rest into linked, categorized files. --- ## Triggers Use this skill when: - "refactor my AGENTS.md" / "refactor my CLAUDE.md" - "split my agent instructions" - "organize my CLAUDE.md file" - "my AGENTS.md is too long" - "progressive disclosure for my instructions" - "clean up my agent config" --- ## Quick Reference | Phase | Action | Output | |-------|--------|--------| | 1. Analyze | Find contradictions | List of conflicts to resolve | | 2. Extract | Identify essentials | Core instructions for root file | | 3. Categorize | Group remaining instructions | Logical categories | | 4. Structure | Create file hierarchy | Root + linked files | | 5. Prune | Flag for deletion | Redundant/vague instructions | --- ## Process ### Phase 1: Find Contradictions Identify any instructions that conflict with each other. **Look for:** - Contradictory style guidelines (e.g., "use semicolons" vs "no semicolons") - Conflicting workflow instructions - Incompatible tool preferences - Mutually exclusive patterns **For each contradiction found:** ```markdown ## Contradiction Found **Instruction A:** [quote] **Instruction B:** [quote] **Question:** Which should take precedence, or should both be conditional? ``` Ask the user to resolve before proceeding. --- ### Phase 2: Identify the Essentials Extract ONLY what belongs in the root agent file. The root should be minimal - information that applies to **every single task**. **Essential content (keep in root):** | Category | Example | |----------|---------| | Project description | One sentence: "A React dashboard for analytics" | | Package manager | Only if not npm (e.g., "Uses pnpm") | | Non-standard commands | Custom build/test/typecheck commands | | Critical overrides | Things that MUST override defaults | | Universal rules | Applies to 100% of tasks | **NOT essential (move to linked files):** - Language-specific conventions - Testing guidelines - Code style details - Framework patterns - Documentation standards - Git workflow details --- ### Phase 3: Group the Rest Organize remaining instructions into logical categories. **Common categories:** | Category | Contents | |----------|----------| | `typescript.md` | TS conventions, type patterns, strict mode rules | | `testing.md` | Test frameworks, coverage, mocking patterns | | `code-style.md` | Formatting, naming, comments, structure | | `git-workflow.md` | Commits, branches, PRs, reviews | | `architecture.md` | Patterns, folder structure, dependencies | | `api-design.md` | REST/GraphQL conventions, error handling | | `security.md` | Auth patterns, input validation, secrets | | `performance.md` | Optimization rules, caching, lazy loading | **Grouping rules:** 1. Each file should be self-contained for its topic 2. Aim for 3-8 files (not too granular, not too broad) 3. Name files clearly: `{topic}.md` 4. Include only actionable instructions --- ### Phase 4: Create the File Structure **Output structure:** ``` project-root/ ├── CLAUDE.md (or AGENTS.md) # Minimal root with links └── .claude/ # Or docs/agent-instructions/ ├── typescript.md ├── testing.md ├── code-style.md ├── git-workflow.md └── architecture.md ``` **Root file template:** ```markdown # Project Name One-sentence description of the project. ## Quick Reference - **Package Manager:** pnpm - **Build:** `pnpm build` - **Test:** `pnpm test` - **Typecheck:** `pnpm typecheck` ## Detailed Instructions For specific guidelines, see: - [TypeScript Conventions](.claude/typescript.md) - [Testing Guidelines](.claude/testing.md) - [Code Style](.claude/code-style.md) - [Git Workflow](.claude/git-workflow.md) - [Architecture Patterns](.claude/architecture.md) ``` **Each linked file template:** ```markdown # {Topic} Guidelines ## Overview Brief context for when these guidelines apply. ## Rules ### Rule Category 1 - Specific, actionable instruction - Another specific instruction ### Rule Category 2 - Specific, actionable instruction ## Examples ### Good \`\`\`typescript // Example of correct pattern \`\`\` ### Avoid \`\`\`typescript // Example of what not to do \`\`\` ``` --- ### Phase 5: Flag for Deletion Identify instructions that should be removed entirely. **Delete if:** | Criterion | Example | Why Delete | |-----------|---------|------------| | Redundant | "Use TypeScript" (in a .ts project) | Agent already knows | | Too vague | "Write clean code" | Not actionable | | Overly obvious | "Don't introduce bugs" | Wastes context | | Default behavior | "Use descriptive variable names" | Standard practice | | Outdated | References deprecated APIs | No longer applies | **Output format:** ```markdown ## Flagged for Deletion | Instruction | Reason | |-------------|--------| | "Write clean, maintainable code" | Too vague to be actionable | | "Use TypeScript" | Redundant - project is already TS | | "Don't commit secrets" | Agent already knows this | | "Follow best practices" | Meaningless without specifics | ``` --- ## Execution Checklist ``` [ ] Phase 1: All contradictions identified and resolved [ ] Phase 2: Root file contains ONLY essentials [ ] Phase 3: All remaining instructions categorized [ ] Phase 4: File structure created with proper links [ ] Phase 5: Redundant/vague instructions removed [ ] Verify: Each linked file is self-contained [ ] Verify: Root file is under 50 lines [ ] Verify: All links work correctly ``` --- ## Anti-Patterns | Avoid | Why | Instead | |-------|-----|---------| | Keeping everything in root | Bloated, hard to maintain | Split into linked files | | Too many categories | Fragmentation | Consolidate related topics | | Vague instructions | Wastes tokens, no value | Be specific or delete | | Duplicating defaults | Agent already knows | Only override when needed | | Deep nesting | Hard to navigate | Flat structure with links | --- ## Examples ### Before (Bloated Root) ```markdown # CLAUDE.md This is a React project. ## Code Style - Use 2 spaces - Use semicolons - Prefer const over let - Use arrow functions ... (200 more lines) ## Testing - Use Jest - Coverage > 80% ... (100 more lines) ## TypeScript - Enable strict mode ... (150 more lines) ``` ### After (Progressive Disclosure) ```markdown # CLAUDE.md React dashboard for real-time analytics visualization. ## Commands - `pnpm dev` - Start development server - `pnpm test` - Run tests with coverage - `pnpm build` - Production build ## Guidelines - [Code Style](.claude/code-style.md) - [Testing](.claude/testing.md) - [TypeScript](.claude/typescript.md) ``` --- ## Verification After refactoring, verify: 1. **Root file is minimal** - Under 50 lines, only universal info 2. **Links work** - All referenced files exist 3. **No contradictions** - Instructions are consistent 4. **Actionable content** - Every instruction is specific 5. **Complete coverage** - No instructions were lost (unless flagged for deletion) 6. **Self-contained files** - Each linked file stands alone ---