agent-md-refactor

Refactor bloated AGENTS.md files into minimal root and linked topic files.

2|1|Updated Jan 26, 2026

Search Tags:#documentation #organization #refactor #progressive-disclosure #agent-instructions #linked-files

Ready to run

npx skills add https://github.com/TrevorEdris/fellowship-of-the-workflows --skill agent-md-refactor-trevoredris

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: agent-md-refactor
Source: https://github.com/TrevorEdris/fellowship-of-the-workflows/tree/main/workflows/skills/agent-md-refactor
Command: npx skills add https://github.com/TrevorEdris/fellowship-of-the-workflows --skill agent-md-refactor-trevoredris

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps teams refactor bloated agent instruction files (AGENTS.md, CLAUDE.md, COPILOT.md, etc.) into a concise, progressive-disclosure structure to improve readability and maintainability.

Core Features & Use Cases

Root minimization: Keeps essential guidelines in the root document.
Linked documentation: Organizes remaining rules into categorized files under a .claude or .cursor structure.
Safe refactoring workflow: Provides a staged process (contradiction detection, essentials extraction, categorization, structuring, pruning).
Use Case: A team wants to trim a 200-line CLAUDE.md into a minimal root plus focused topics to speed up agent startup.

Quick Start

Invoke the skill on a large AGENTS.md or CLAUDE.md to generate a minimal root file and a new .claude/ documentation tree.
Review generated categories and adjust as needed.

Frequently Asked Questions about agent-md-refactor

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I refactor a large CLAUDE.md or AGENTS.md file into linked documentation?▼

To refactor large CLAUDE.md or AGENTS.md files, you extract essential guidelines into a minimal root document and reorganize remaining rules into categorized linked files under a project structure. This progressive-disclosure approach improves readability and speeds up agent startup.

What is progressive disclosure for agent instruction files?▼

Progressive disclosure for agent instruction files is a structure where a minimal root document contains essential guidelines, while remaining rules are grouped into categorized linked files under a directory like .claude or .cursor to improve maintainability.

How do I resolve contradictions when cleaning up bloated agent docs?▼

Resolving contradictions when cleaning up bloated agent docs involves a staged refactoring workflow that starts with contradiction detection, followed by essentials extraction, categorization, structuring, and pruning to ensure a consistent rule set.

When should I split my agent instructions into separate topic-specific files?▼

You should split your agent instructions into topic-specific files when your root document exceeds 50 lines, causing readability issues and slowing down agent startup in CLAUDE Code or Cursor workflows.

Can I use this refactoring process for a COPILOT.md file?▼

Yes, you can use this refactoring process for a COPILOT.md file. The skill handles bloated agent instruction files across multiple formats, including AGENTS.md, CLAUDE.md, and COPILOT.md, reorganizing them into a minimal root plus linked documentation.

What is the best way to organize agent guidelines into a .claude or .cursor directory structure?▼

The best way to organize agent guidelines into a .claude or .cursor directory structure is through a five-phase process: contradiction detection, essentials extraction, grouping, structuring, and deletion flagging, outputting a minimal root file plus topic-specific guidelines.