# agent-md-refactor

Splits oversized CLAUDE.md or AGENTS.md files into modular docs. It leaves only universal directives in root and links out to detailed subtopics.

- skill · `type=skill` · Claude Code · 193 installs
- Author: davila7
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/davila7/claude-code-templates/tree/HEAD/cli-tool/components/skills/development/agent-md-refactor
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/skills/agent-md-refactor

## What it does

The skill breaks monolithic agent instruction files into a lean root file and linked documents inside `.claude/`. The main document retains only context relevant to every single task: a brief project summary, package manager nuances, and custom build scripts. Specific areas like TypeScript rules, testing practices, and architecture patterns migrate into standalone guides.

Execution moves across five distinct steps: flagging contradictions, extracting essential defaults, sorting guidelines into topical files, generating markdown links, and pruning dead weight. It targets vague phrasing, obvious programming basics, and redundant settings for deletion.

If your current instructions contain opposing rules, the skill pauses immediately during analysis and demands a manual resolution.

## Install

### Claude Code (native platform)

1. **claude-code-templates**
```bash
npx claude-code-templates@latest --skill development/agent-md-refactor
```

2. **Skills CLI (Vercel)**
```bash
npx skills add davila7/claude-code-templates --skill agent-md-refactor -a claude-code
```

3. **Manually: put the files in place**
- File: `~/.claude/skills/agent-md-refactor/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/agent-md-refactor/

### Codex

**Manually: put the files in place**
- File: `.agents/skills/agent-md-refactor/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

**Manually: put the files in place**
- File: `.cursor/skills/agent-md-refactor/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install davila7/claude-code-templates agent-md-refactor
```

2. **Manually: put the files in place**
- File: `.github/skills/agent-md-refactor/SKILL.md`

### Gemini CLI

**Platform CLI**
```bash
gemini skills install https://github.com/davila7/claude-code-templates --path cli-tool/components/skills/development/agent-md-refactor
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/agent-md-refactor/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/davila7/claude-code-templates/tree/HEAD/cli-tool/components/skills/development/agent-md-refactor

## When to use it
- shrink bloated root CLAUDE.md files
- uncover conflicting guidelines inside agent documentation
- strip vague rules and generic advice from instructions
- split coding conventions into focused topic files

## Example prompts
- Refactor my CLAUDE.md using progressive disclosure
- Split this long AGENTS.md into separate topic files
- Check agent instructions for conflicts and eliminate fluff

## Similar
- [setup-matt-pocock-skills](https://affpapa.org/en/nevibecode/skills/setup-matt-pocock-skills.md) — skill · 1052851 installs
- [ask-matt](https://affpapa.org/en/nevibecode/skills/ask-matt.md) — skill · 766587 installs
- [to-tickets](https://affpapa.org/en/nevibecode/skills/to-tickets.md) — skill · 711230 installs
- [writing-plans](https://affpapa.org/en/nevibecode/skills/writing-plans.md) — skill · 282859 installs
- [caveman-review](https://affpapa.org/en/nevibecode/skills/caveman-review.md) — skill · 411800 installs
- [caveman-compress](https://affpapa.org/en/nevibecode/skills/caveman-compress.md) — skill · 411500 installs

From the same set: [davila7/claude-code-templates](https://affpapa.org/en/nevibecode/by/davila7/claude-code-templates.md) — 804 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md