Agent Md Refactor
Split an overgrown CLAUDE.md or AGENTS.md into a slim root file plus linked topic docs so every agent task loads less noise.
Overview
Agent MD Refactor is an agent skill most often used in Build (also Operate, Ship) that restructures bloated CLAUDE.md-style files using progressive disclosure and linked topic docs.
Install
npx skills add https://github.com/softaworks/agent-toolkit --skill agent-md-refactorWhat is this skill?
- Applies progressive disclosure: universal rules in root, deep dives in linked files
- Targets bloated agent configs that waste context on every unrelated task
- Surfaces contradictions and buried signal among vague or duplicate guidelines
- Trigger-driven workflow for “refactor my CLAUDE.md” and “my AGENTS.md is too long”
- Good fit when root agent files exceed roughly 50–100 lines mixing unrelated topics
- Good refactor candidates: root agent files exceeding 50–100 lines
Adoption & trust: 3.8k installs on skills.sh; 2k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your root agent instruction file grew past a few screens, so every task loads irrelevant rules, hides what matters, and may contradict itself.
Who is it for?
Solo builders whose CLAUDE.md or AGENTS.md exceeds ~50–100 lines and mixes stacks, style, deploy, and product rules in one dump.
Skip if: Repos with no agent instruction files yet—write a minimal root file first—or when you only need a one-line project blurb with no ongoing agent workflow.
When should I use this skill?
Refactor my AGENTS.md or CLAUDE.md, split agent instructions, organize a too-long agent config, or apply progressive disclosure to instruction files.
What do I get? / Deliverables
You get a short universal root file plus organized linked docs, so agents load only what the current task needs and you can maintain rules without fear of breaking everything.
- Slimmed root agent instruction file
- Linked topic-specific markdown docs with clear navigation
- Removed or reconciled contradictory rules
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
First appears in Build when you wire agent tooling and repo conventions, but the refactor improves every later phase that invokes the same agent instructions. Agent-tooling is the shelf for instruction files (`CLAUDE.md`, `AGENTS.md`, `COPILOT.md`) and progressive-disclosure structure—not application feature code.
Where it fits
Split a 300-line CLAUDE.md into root principles plus linked frontend, API, and testing instruction files.
Turn duplicated style guidance in AGENTS.md into a single linked doc referenced from the root.
After an outage, isolate new runbook rules into a linked ops doc instead of appending to the root agent file.
Move launch-day checklists out of CLAUDE.md so routine coding tasks stop loading release-only steps.
How it compares
A structured refactor workflow for instruction files, not a skill that implements product features or runs CI.
Common Questions / FAQ
Who is agent-md-refactor for?
Developers using Claude Code, Cursor, Copilot, or similar agents who maintain CLAUDE.md, AGENTS.md, or COPILOT.md and want less context waste per task.
When should I use agent-md-refactor?
Use it in Build when configuring the repo agent, again in Operate when instructions drift after incidents, and in Ship when launch checklists bloat the root file—especially after phrases like “refactor my AGENTS.md” or “progressive disclosure for my instructions.”
Is agent-md-refactor safe to install?
It edits documentation and agent config in your repo; confirm diffs before merge and review the Security Audits panel on this Prism page for the package source.
Workflow Chain
Then invoke: skill judge
SKILL.md
READMESKILL.md - Agent Md Refactor
# Agent MD Refactor A Claude Code skill that transforms bloated agent instruction files into clean, organized documentation using progressive disclosure principles. Based on https://x.com/mattpocockuk/status/2012906065856270504 (Matt Pocock's Prompt Idea) ## Purpose Over time, agent instruction files like `CLAUDE.md`, `AGENTS.md`, or `COPILOT.md` tend to grow into unwieldy documents containing hundreds of lines of mixed instructions. This creates several problems: - **Context waste**: Every task loads the entire file, even when most instructions are irrelevant - **Maintenance burden**: Finding and updating specific instructions becomes difficult - **Contradictions**: Conflicting guidelines accumulate without being noticed - **Signal-to-noise ratio**: Important rules get buried among obvious or vague statements This skill solves these problems by applying **progressive disclosure** - keeping only essential, universal instructions in the root file while organizing everything else into focused, linked documentation files. ## When to Use Use this skill when you need to clean up agent instruction files. Common trigger phrases include: - "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" **Good candidates for refactoring:** - Root agent files exceeding 50-100 lines - Files mixing multiple unrelated topics (testing, code style, architecture, etc.) - Documents that have grown organically without structure - Files containing contradictory or redundant instructions ## How It Works The skill follows a systematic 5-phase process: ### Phase 1: Find Contradictions Before restructuring, the skill identifies conflicting instructions that need resolution. Examples include contradictory style guidelines ("use semicolons" vs "no semicolons") or incompatible workflow instructions. Each contradiction is surfaced with a question for the user to resolve. ### Phase 2: Identify the Essentials Extracts only what truly belongs in the root file - information that applies to every single task: | Keep in Root | Move Out | |-------------|----------| | One-sentence project description | Language-specific conventions | | Non-standard package manager | Testing guidelines | | Custom build/test commands | Code style details | | Critical overrides | Framework patterns | | Universal rules (100% of tasks) | Documentation standards | ### Phase 3: Group the Rest Organizes remaining instructions into logical categories like: - `typescript.md` - Type patterns, strict mode rules - `testing.md` - Test frameworks, coverage, mocking - `code-style.md` - Formatting, naming, structure - `git-workflow.md` - Commits, branches, PRs - `architecture.md` - Patterns, folder structure ### Phase 4: Create the File Structure Generates the new file hierarchy with properly linked documentation: ``` project-root/ ├── CLAUDE.md # Minimal root with links └── .claude/ # Categorized instructions ├── typescript.md ├── testing.md ├── code-style.md └── architecture.md ``` ### Phase 5: Flag for Deletion Identifies instructions that should be removed entirely: - **Redundant**: "Use TypeScript" in a TypeScript project - **Too vague**: "Write clean code" without specifics - **Overly obvious**: "Don't introduce bugs" - **Default behavior**: "Use descriptive variable names" - **Outdated**: References to deprecated APIs ## Key Features - **Contradiction detection**: Surfaces conflicting instructions before restructuring - **Intelligent categorization**: Groups related instructions into logical files - **Root file minimization**: Targets under 50 lines for the main file - **Deletion recommendations**: Identifies instructions wasting context tokens - **Template-driven output**: Consistent structure across all generated files - **Link verification**: Ensures all referenc