Agent Md Refactor

If your AGENTS.md or CLAUDE.md has ballooned into a 500-line monolith, this walks you through splitting it into a minimal root file plus organized, linked documentation. It's built around progressive disclosure: keep only universal info at the top (commands, project basics), then move language-specific rules, testing patterns, and style guides into separate files like typescript.md or code-style.md. The process flags contradictions first, then helps you prune vague instructions like "write clean code" that just waste tokens. The checklist aims for a root file under 50 lines. Solid if you're drowning in agent instructions and need a structured cleanup.

skills.sh installs: 446
GitHub stars: 33.2K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add davila7/claude-code-templates --skill agent-md-refactor --agent claude-code

Installs into .claude/skills of the current project.

Files

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