Refactor bloated AGENTS.md, CLAUDE.md, or similar agent instruction files to follow progressive disclosure principles. Splits monolithic files into organized, linked documentation.

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: 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: Root file template: Each linked file template: 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: Execution Checklist 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) After (Progressive Disclosure) 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

agent-md-refactor