Agent Md Refactor

If your AGENTS.md has turned into a 500-line wall of text that nobody reads, this will split it into something manageable. It walks through finding contradictions in your instructions, pulling out the truly essential stuff for the root file (project description, non-standard commands, critical overrides), then organizing everything else into linked topic files like typescript.md or testing.md. The process flags vague instructions like "write clean code" for deletion since they just waste context. The goal is a root file under 50 lines that links to self-contained guides, following progressive disclosure principles. Works for CLAUDE.md, COPILOT.md, or whatever you call your agent instructions.

skills.sh installs: 4.3K
GitHub stars: 2.7K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add softaworks/agent-toolkit --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