agent-md-refactor

Refactor monolithic agent instruction files into linked markdown files.

Updated Dec 16, 2025

Search Tags:#documentation #markdown #refactoring #organization #progressive disclosure #agent instructions

Ready to run

npx skills add https://github.com/EanLee/article-write --skill agent-md-refactor-eanlee

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: agent-md-refactor
Source: https://github.com/EanLee/article-write/tree/main/.github/skills/agent-md-refactor
Command: npx skills add https://github.com/EanLee/article-write --skill agent-md-refactor-eanlee

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill tackles the issue of overly long and disorganized agent instruction files (like AGENTS.md or CLAUDE.md) by restructuring them for better readability and maintainability.

Core Features & Use Cases

Progressive Disclosure: Organizes information by keeping essential details in the root file and moving less critical or specialized instructions into linked, categorized files.
Contradiction Detection: Identifies conflicting instructions within the original file to ensure consistency.
Use Case: You have a massive CLAUDE.md file with hundreds of lines of instructions. This Skill will split it into a concise CLAUDE.md with links to separate files for code-style.md, testing.md, git-workflow.md, etc., making it much easier to manage and understand.

Quick Start

Use the agent-md-refactor skill to refactor my CLAUDE.md file.

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 agent instruction file like CLAUDE.md for better readability?▼

To refactor agent instruction files, this Skill restructures monolithic configurations into a concise root file with links to categorized markdown files, applying progressive disclosure to keep essential details accessible while moving specialized instructions away.

What is progressive disclosure for organizing agent instructions?▼

Progressive disclosure organizes agent instructions by retaining essential root configurations in the primary file while migrating less critical or specialized details into linked, categorized markdown files, ensuring improved clarity and maintainability for complex setups.

How do I split a massive CLAUDE.md file into multiple linked markdown files?▼

Splitting a massive CLAUDE.md file involves identifying essential root instructions, categorizing remaining details into separate linked files like code-style.md or testing.md, and flagging redundant or vague content for deletion to improve maintainability.

Can agent-md-refactor detect conflicting instructions in an AGENTS.md file?▼

Yes, during the refactoring process, the Skill identifies conflicting instructions within the original monolithic file to ensure consistency across the newly structured, multi-file agent configuration.

What are the limitations of using progressive disclosure to organize markdown agent configurations?▼

While progressive disclosure improves clarity by splitting configurations into linked files, it requires maintaining multiple markdown files instead of one, which may complicate version control if your agent setup is extremely simple or does not require categorized instructions.