agent-md-refactor

Refactor monolithic agent instruction files into a minimal root file and linked topic documents.

1|Updated Feb 21, 2026

Search Tags:#documentation #claude #refactor #guidelines #progressive-disclosure #agent-instructions

Ready to run

npx skills add https://github.com/creep1ng/arte-chatbot --skill agent-md-refactor-creep1ng

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: agent-md-refactor
Source: https://github.com/creep1ng/arte-chatbot/tree/main/.kilo/skills/agent-md-refactor
Command: npx skills add https://github.com/creep1ng/arte-chatbot --skill agent-md-refactor-creep1ng

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Refactors monolithic agent instruction files (AGENTS.md, CLAUDE.md, COPILOT.md) that are overly long, contradictory, or hard to navigate into a concise, discoverable structure that follows progressive disclosure principles.

Core Features & Use Cases

Contradiction detection: Identify and surface conflicting or mutually exclusive instructions for user resolution.
Essentials extraction: Isolate universal, project-wide rules for a minimal root file and move the rest into linked topic files.
Categorization & restructuring: Group remaining guidance into 3–8 self-contained topic documents with clear names and templates, and produce a file layout and verification checklist.
Pruning recommendations: Flag vague, redundant, or obsolete instructions for deletion to reduce maintenance burden.

Quick Start

Refactor my AGENTS.md into a minimal root file and a linked .claude/ directory with categorized topic files, listing contradictions and items flagged for deletion.

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?▼

To refactor bloated agent instructions, split the monolithic file into a minimal root file containing universal essentials and 3 to 8 linked topic-specific documents. This process applies progressive disclosure, making categorized guidelines easier to navigate and maintain.

What is progressive disclosure for agent instruction files?▼

Progressive disclosure organizes agent instructions by keeping a minimal root file with universal rules and linking to detailed, categorized topic documents. This structure prevents monolithic files like CLAUDE.md from becoming overly long, contradictory, or hard to navigate during onboarding tasks.

How do I organize contradictory instructions in COPILOT.md?▼

Organizing contradictory instructions involves detecting conflicting or mutually exclusive entries within your COPILOT.md and surfacing them for user resolution. The remaining valid guidelines are then grouped into self-contained topic documents with clear names.

Can I split agent guidelines into multiple linked documents?▼

Yes, you can split agent guidelines by extracting universal project-wide rules into a minimal root file and moving the rest into 3 to 8 linked documents. This restructuring groups remaining guidance into self-contained topic files with clear names and templates.

What is the best way to prune redundant entries in agent documentation?▼

The best way to prune agent documentation is to flag vague, redundant, or obsolete instructions for deletion, reducing the maintenance burden. This process isolates universal essentials and outputs a verification checklist to ensure the cleaned file structure remains accurate.

When do I need to restructure monolithic agent guidance?▼

You need to restructure monolithic agent guidance when files like AGENTS.md become overly long, contradictory, or hard to maintain during documentation tasks. Restructuring produces a concise, discoverable file layout that separates universal rules from topic-specific details.