Agent skill · writing content · aiskillstore
agent-md-refactor
Refactor bloated AGENTS.md, CLAUDE.md, or similar agent instruction files to follow progressive disclosure principles. Splits monolithic files into organized, linked documentation.
Why this skill is useful
Provides a structured approach to organizing agent documentation, which the AI wouldn't reliably generate on its own.
What it needs
About 4k tokens when loaded. Last updated 2026-08-07. 405 stars on the source repository.
What this skill does
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. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills aiskillstore/agent-md-refactor