agent-md-refactor

Installation
Summary

Refactor bloated agent instruction files into organized, linked documentation using progressive disclosure.

  • Analyzes existing AGENTS.md, CLAUDE.md, or similar files to identify contradictions, extract essentials, and categorize remaining instructions across 3–8 focused topic files
  • Keeps root file minimal (under 50 lines) with only universal project info and links to detailed guidelines organized by topic (TypeScript, testing, code style, git workflow, architecture)
  • Flags redundant, vague, or outdated instructions for deletion and provides templates for both root and linked files to ensure consistency
  • Follows a five-phase process: find contradictions, identify essentials, group remaining content, create file structure, and prune unnecessary instructions
SKILL.md

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

Related skills

More from softaworks/agent-toolkit

Installs
3.7K
GitHub Stars
1.8K
First Seen
Jan 20, 2026