agent-md-refactor

Refactor bloated agent instruction files into minimal roots with linked documentation.

1|Updated Mar 27, 2026

Search Tags:#documentation #refactor #progressive-disclosure #agent-instructions #file-structure #root-minimization

Ready to run

npx skills add https://github.com/leonanpereirapinto/ai-utils --skill agent-md-refactor-leonanpereirapinto

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: agent-md-refactor
Source: https://github.com/leonanpereirapinto/ai-utils/tree/main/.agents/skills/agent-md-refactor
Command: npx skills add https://github.com/leonanpereirapinto/ai-utils --skill agent-md-refactor-leonanpereirapinto

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill reduces bloated root agent instruction files (e.g., AGENTS.md, CLAUDE.md, COPILOT.md) by extracting universal rules and moving detailed instructions into linked, categorized documents using progressive disclosure.

Core Features & Use Cases

Contradiction detection to surface conflicting instructions.
Intelligent categorization to group instructions into logical topics.
Root minimization to keep the root file concise and easy to scan.
Deletion recommendations to remove vague or redundant content.
Template-driven output and link verification to ensure a coherent structure.

Quick Start

Refactor my AGENTS.md or CLAUDE.md to organize instructions into a minimal root and linked documentation.

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 bloated AGENTS.md or CLAUDE.md file?▼

Refactor bloated agent instruction files by splitting content into a minimal root and organized linked documentation using progressive disclosure. The process extracts universal rules and moves detailed instructions into categorized documents to keep the root file concise.

What is progressive disclosure for agent instruction files?▼

Progressive disclosure organizes agent instructions by keeping the root file minimal and easy to scan, while moving detailed instructions into linked, categorized documents. This structure surfaces universal rules immediately and hides complexity until needed.

How do I organize agent instructions into a minimal root structure?▼

Organize agent instructions through a five-phase process: contradiction discovery, essentials extraction, grouping, structuring, and deletion flagging. This extracts universal rules for the root file and moves detailed instructions into linked, categorized documents.

Can progressive disclosure detect conflicting instructions in agent docs?▼

Yes, progressive disclosure refactoring includes a contradiction discovery phase that surfaces conflicting instructions within agent files. This happens during the essentials extraction and grouping stages before structuring the final linked documentation.

What is the best way to minimize root agent instruction files?▼

The best way to minimize root agent instruction files is extracting universal rules and moving detailed instructions into linked, categorized documents. Template-driven output and link verification ensure a coherent progressive disclosure structure while flagging redundant content for deletion.

Does progressive disclosure refactoring work with COPILOT.md files?▼

Yes, progressive disclosure refactoring applies to AGENTS.md, CLAUDE.md, COPILOT.md and similar agent instruction files. It splits their content into a minimal root file and organized linked documentation regardless of the specific agent platform.