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.
Install / Use
npx skills add softaworks/agent-toolkit --skill agent-md-refactorInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Content & MediaSupported Platforms
Our assessment of agent-md-refactor
agent-md-refactor scores 88/100 on our quality scale, 579th of 1,155 Content & Media skills we index.
Its SKILL.md is 7.3 KB long, well organised into 35 sections with 8 code examples: a thorough specification that gives an agent plenty to work with.
With 2,502 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 9 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
- Our last check on 2026-11-01 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 94/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-01. Automated pattern scan on 2026-10-01. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
agent-md-refactor compared with similar skills
All 4 of these similar skills score higher than agent-md-refactor; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| agent-md-refactor (this skill)by softaworks | 88 | 2.5k | 9mo ago | SKILL.md |
| siyuanby siyuan-note | 100 | 47.3k | today | MCP Server |
| x402by browser-use | 100 | 121.0k | 3d ago | SKILL.md |
| algorithmic-artby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
| pptxby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
Frequently asked questions
- How do I install agent-md-refactor?
- Run
npx skills add softaworks/agent-toolkit --skill agent-md-refactor. The install tabs above show the steps for each supported agent. - Which AI agents does agent-md-refactor work with?
- It is written for Claude Code, GitHub Copilot, Zed and OpenAI Codex, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is agent-md-refactor safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 94/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is agent-md-refactor still maintained?
- The repository was last updated about 9 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
Skill content
View source on GitHubname: agent-md-refactor description: Refactor bloated AGENTS.md, CLAUDE.md, or similar agent instruction files to follow progressive disclosure principles. Splits monolithic files into organized, linked documentation. license: MIT
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:
## 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:
- Each file should be self-contained for its topic
- Aim for 3-8 files (not too granular, not too broad)
- Name files clearly:
{topic}.md - 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:
# 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:
# {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:
## 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)
# 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)
# 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:
- Root file is minimal - Under 50 lines, only universal info
- Links work - All referenced files exist
- No contradictions - Instructions are consistent
- Actionable content - Every instruction is specific
- Complete coverage - No instructions were lost (unless flagged for deletion)
- Self-contained files - Each linked file stands alone
Related Skills
siyuan
47.3kAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间,让人与智能体在此协作
x402
121.0kSet up Browser Use Cloud payments with x402 — pay per request from a crypto wallet (USDC on Base mainnet), no signup or API key.
algorithmic-art
177.9kCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems.
pptx
177.9kUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an em…
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
