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.
- Installs
- 4.2K
- Last 24h
- —
- Trending rank
- —
- Security
- Pass
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/softaworks/agent-toolkit --skill agent-md-refactor- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads agent-md-refactor automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
Security audits
Independent scans of the skill's instructions and bundled files.
SKILL.md
The instructions your agent reads when the skill is triggered.
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
FAQ
What does the agent-md-refactor skill do?
Refactor bloated AGENTS.md, CLAUDE.md, or similar agent instruction files to follow progressive disclosure principles. Splits monolithic files into organized, linked documentation.
How do I install agent-md-refactor?
Run npx skills add https://github.com/softaworks/agent-toolkit --skill agent-md-refactor in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/agent-md-refactor/ (personal) or .claude/skills/agent-md-refactor/ (project).
Which AI agents can use agent-md-refactor?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is agent-md-refactor safe to install?
Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk passed; Runlayer passed; ZeroLeaks passed. As with any skill, read the SKILL.md and bundled scripts before installing.
Who maintains agent-md-refactor?
It is published by softaworks in softaworks/agent-toolkit. It has 4,229 recorded installs.
More from softaworks/agent-toolkit
mermaid-diagrams
softaworks/agent-toolkit
Comprehensive guide for creating software diagrams using Mermaid syntax. Use when users need to create, visualize, or document software through diagrams including class diagrams (domain modeling, object-oriented design), sequence diagrams (application flows, API interactions, code execution), flowcharts (processes, algorithms, user journeys), entity relationship diagrams (database schemas), C4 architecture diagrams (system context, containers, components), state diagrams, git graphs, pie charts, gantt charts, or any other diagram type. Triggers include requests to "diagram", "visualize", "model", "map out", "show the flow", or when explaining system architecture, database design, code structure, or user/application flows.
humanizer
softaworks/agent-toolkit
Remove signs of AI-generated writing from text. Use when editing or reviewing text to make it sound more natural and human-written. Based on Wikipedia's comprehensive "Signs of AI writing" guide. Detects and fixes patterns including: inflated symbolism, promotional language, superficial -ing analyses, vague attributions, em dash overuse, rule of three, AI vocabulary words, negative parallelisms, and excessive conjunctive phrases. Credits: Original skill by @blader - https://github.com/blader/humanizer
database-schema-designer
softaworks/agent-toolkit
Design robust, scalable database schemas for SQL and NoSQL databases. Provides normalization guidelines, indexing strategies, migration patterns, constraint design, and performance optimization. Ensures data integrity, query performance, and maintainable data models.
qa-test-planner
softaworks/agent-toolkit
Generate comprehensive test plans, manual test cases, regression test suites, and bug reports for QA engineers. Includes Figma MCP integration for design validation.
writing-clearly-and-concisely
softaworks/agent-toolkit
Use when writing prose humans will read—documentation, commit messages, error messages, explanations, reports, or UI text. Applies Strunk's timeless rules for clearer, stronger, more professional writing.
skill-judge
softaworks/agent-toolkit
Evaluate Agent Skill design quality against official specifications and best practices. Use when reviewing, auditing, or improving SKILL.md files and skill packages. Provides multi-dimensional scoring and actionable improvement suggestions.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.