# Agent Md Refactor

Refactor bloated AGENTS.md, CLAUDE.md, or similar agent instruction files to follow...

- Repository: https://github.com/softaworks/agent-toolkit (2611 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-03-05
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add softaworks/agent-toolkit --skill agent-md-refactor -g -a claude-code -y`
Codex: `npx skills add softaworks/agent-toolkit --skill agent-md-refactor -g -a codex -y`
Cursor: `npx skills add softaworks/agent-toolkit --skill agent-md-refactor -g -a cursor -y`
Gemini CLI: `npx skills add softaworks/agent-toolkit --skill agent-md-refactor -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add softaworks/agent-toolkit`

## Description

Refactor bloated AGENTS.md, CLAUDE.md, or similar agent instruction files to follow progressive disclosure principles. Splits monolithic files into organized, linked documentation.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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:**
```markdown
## 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**.

The rest: https://github.com/softaworks/agent-toolkit/blob/HEAD/dist/plugins/agent-md-refactor/skills/agent-md-refactor/SKILL.md