Skip to content

Commit 63bebde

Browse files
leonardocouyleonardocouy
committed
feat: add agent-md-refactor skill
Refactor bloated AGENTS.md, CLAUDE.md, or similar agent instruction files to follow progressive disclosure principles. Splits monolithic files into organized, linked documentation.
1 parent 1b4c65e commit 63bebde

3 files changed

Lines changed: 513 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ Skills follow the [Agent Skills](https://agentskills.io/) format.
1919
| 🤖 AI Tools | [codex](skills/codex/README.md) | Advanced code analysis with GPT-5.2 |
2020
| 🤖 AI Tools | [gemini](skills/gemini/README.md) | Large-scale review (200k+ context) |
2121
| 🤖 AI Tools | [perplexity](skills/perplexity/README.md) | Web search & research |
22+
| 🔮 Meta | [agent-md-refactor](skills/agent-md-refactor/README.md) | Refactor bloated agent instruction files |
2223
| 🔮 Meta | [command-creator](skills/command-creator/README.md) | Create Claude Code slash commands |
2324
| 🔮 Meta | [plugin-forge](skills/plugin-forge/README.md) | Build Claude Code plugins & manifests |
2425
| 📝 Documentation | [backend-to-frontend-handoff-docs](skills/backend-to-frontend-handoff-docs/README.md) | API handoff docs for frontend |

‎skills/agent-md-refactor/README.md‎

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
# Agent MD Refactor
2+
3+
A Claude Code skill that transforms bloated agent instruction files into clean, organized documentation using progressive disclosure principles.
4+
5+
## Purpose
6+
7+
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:
8+
9+
- **Context waste**: Every task loads the entire file, even when most instructions are irrelevant
10+
- **Maintenance burden**: Finding and updating specific instructions becomes difficult
11+
- **Contradictions**: Conflicting guidelines accumulate without being noticed
12+
- **Signal-to-noise ratio**: Important rules get buried among obvious or vague statements
13+
14+
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.
15+
16+
## When to Use
17+
18+
Use this skill when you need to clean up agent instruction files. Common trigger phrases include:
19+
20+
- "refactor my AGENTS.md" / "refactor my CLAUDE.md"
21+
- "split my agent instructions"
22+
- "organize my CLAUDE.md file"
23+
- "my AGENTS.md is too long"
24+
- "progressive disclosure for my instructions"
25+
- "clean up my agent config"
26+
27+
**Good candidates for refactoring:**
28+
29+
- Root agent files exceeding 50-100 lines
30+
- Files mixing multiple unrelated topics (testing, code style, architecture, etc.)
31+
- Documents that have grown organically without structure
32+
- Files containing contradictory or redundant instructions
33+
34+
## How It Works
35+
36+
The skill follows a systematic 5-phase process:
37+
38+
### Phase 1: Find Contradictions
39+
40+
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.
41+
42+
### Phase 2: Identify the Essentials
43+
44+
Extracts only what truly belongs in the root file - information that applies to every single task:
45+
46+
| Keep in Root | Move Out |
47+
|-------------|----------|
48+
| One-sentence project description | Language-specific conventions |
49+
| Non-standard package manager | Testing guidelines |
50+
| Custom build/test commands | Code style details |
51+
| Critical overrides | Framework patterns |
52+
| Universal rules (100% of tasks) | Documentation standards |
53+
54+
### Phase 3: Group the Rest
55+
56+
Organizes remaining instructions into logical categories like:
57+
58+
- `typescript.md` - Type patterns, strict mode rules
59+
- `testing.md` - Test frameworks, coverage, mocking
60+
- `code-style.md` - Formatting, naming, structure
61+
- `git-workflow.md` - Commits, branches, PRs
62+
- `architecture.md` - Patterns, folder structure
63+
64+
### Phase 4: Create the File Structure
65+
66+
Generates the new file hierarchy with properly linked documentation:
67+
68+
```
69+
project-root/
70+
├── CLAUDE.md # Minimal root with links
71+
└── .claude/ # Categorized instructions
72+
├── typescript.md
73+
├── testing.md
74+
├── code-style.md
75+
└── architecture.md
76+
```
77+
78+
### Phase 5: Flag for Deletion
79+
80+
Identifies instructions that should be removed entirely:
81+
82+
- **Redundant**: "Use TypeScript" in a TypeScript project
83+
- **Too vague**: "Write clean code" without specifics
84+
- **Overly obvious**: "Don't introduce bugs"
85+
- **Default behavior**: "Use descriptive variable names"
86+
- **Outdated**: References to deprecated APIs
87+
88+
## Key Features
89+
90+
- **Contradiction detection**: Surfaces conflicting instructions before restructuring
91+
- **Intelligent categorization**: Groups related instructions into logical files
92+
- **Root file minimization**: Targets under 50 lines for the main file
93+
- **Deletion recommendations**: Identifies instructions wasting context tokens
94+
- **Template-driven output**: Consistent structure across all generated files
95+
- **Link verification**: Ensures all references between files are valid
96+
97+
## Usage Examples
98+
99+
### Basic Refactoring
100+
101+
```
102+
User: refactor my CLAUDE.md
103+
104+
Claude: I'll analyze your CLAUDE.md file and refactor it using progressive
105+
disclosure principles...
106+
```
107+
108+
### Specific File
109+
110+
```
111+
User: my AGENTS.md is too long, can you split it up?
112+
113+
Claude: I'll review your AGENTS.md and organize it into focused, linked files...
114+
```
115+
116+
### After a Project Grows
117+
118+
```
119+
User: organize my agent config - it's gotten out of control
120+
121+
Claude: I'll apply the 5-phase refactoring process to clean up your
122+
agent instructions...
123+
```
124+
125+
## Output
126+
127+
After running the skill, you get:
128+
129+
**Minimal root file (~50 lines or less):**
130+
```markdown
131+
# Project Name
132+
133+
One-sentence description of the project.
134+
135+
## Quick Reference
136+
137+
- **Package Manager:** pnpm
138+
- **Build:** `pnpm build`
139+
- **Test:** `pnpm test`
140+
141+
## Detailed Instructions
142+
143+
- [TypeScript Conventions](.claude/typescript.md)
144+
- [Testing Guidelines](.claude/testing.md)
145+
- [Code Style](.claude/code-style.md)
146+
```
147+
148+
**Organized linked files with consistent structure:**
149+
```markdown
150+
# Testing Guidelines
151+
152+
## Overview
153+
Brief context for when these guidelines apply.
154+
155+
## Rules
156+
157+
### Unit Tests
158+
- Specific, actionable instruction
159+
- Another specific instruction
160+
161+
## Examples
162+
163+
### Good
164+
[code example]
165+
166+
### Avoid
167+
[code example]
168+
```
169+
170+
**Deletion report:**
171+
```markdown
172+
## Flagged for Deletion
173+
174+
| Instruction | Reason |
175+
|-------------|--------|
176+
| "Write clean, maintainable code" | Too vague to be actionable |
177+
| "Use TypeScript" | Redundant - project is already TS |
178+
```
179+
180+
## Best Practices
181+
182+
### Before Refactoring
183+
184+
1. **Commit current state** - Have a clean git state so you can review changes
185+
2. **Identify your goals** - Know what problems you want to solve
186+
3. **Gather all instruction files** - Some projects have instructions scattered across multiple locations
187+
188+
### During Refactoring
189+
190+
1. **Resolve contradictions first** - Do not proceed until conflicts are addressed
191+
2. **Be aggressive about root minimization** - When in doubt, move it out
192+
3. **Aim for 3-8 linked files** - Not too granular, not too broad
193+
4. **Delete liberally** - Vague instructions waste tokens without providing value
194+
195+
### After Refactoring
196+
197+
1. **Verify all links work** - Test that referenced files exist
198+
2. **Check for lost instructions** - Ensure nothing important was dropped
199+
3. **Test with real tasks** - Run a few typical tasks to verify the agent can find needed instructions
200+
201+
## Anti-Patterns to Avoid
202+
203+
| Avoid | Why | Instead |
204+
|-------|-----|---------|
205+
| Keeping everything in root | Bloated, hard to maintain | Split into linked files |
206+
| Too many categories | Fragmentation, navigation overhead | Consolidate related topics |
207+
| Vague instructions | Wastes tokens, no value | Be specific or delete |
208+
| Duplicating defaults | Agent already knows | Only override when needed |
209+
| Deep nesting | Hard to navigate | Flat structure with links |
210+
211+
## Verification Checklist
212+
213+
After refactoring, verify:
214+
215+
- [ ] Root file is under 50 lines
216+
- [ ] Root contains ONLY universal information
217+
- [ ] All links to sub-files work correctly
218+
- [ ] No contradictions remain between files
219+
- [ ] Every instruction is specific and actionable
220+
- [ ] No instructions were lost (unless intentionally deleted)
221+
- [ ] Each linked file is self-contained for its topic
222+
223+
## License
224+
225+
MIT

0 commit comments

Comments
 (0)