agent-md-refactor

Name: agent-md-refactor
Availability: InStock
Author: fefogarcia

Refactor monolithic AGENTS.md files into linked, categorized Markdown documents.

1|Updated Feb 10, 2026

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

Ready to run

npx skills add https://github.com/fefogarcia/approved-skills --skill agent-md-refactor-fefogarcia

💬 Prompt for ChatGPT / Claude Chat▼

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

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill tackles the issue of overly long and complex 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 context-specific instructions into linked, categorized files.
Conflict Resolution: Identifies and helps resolve contradictory instructions within the agent's documentation.
Use Case: You have a monolithic CLAUDE.md file with hundreds of lines covering everything from code style to API design. This skill will split it into a concise CLAUDE.md and separate files like typescript.md, testing.md, and git-workflow.md, making it easier for the agent to process and for you to manage.

Quick Start

Use the agent-md-refactor skill to split my long CLAUDE.md file into organized sections.

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 monolithic CLAUDE.md file into organized sections?▼

To refactor a monolithic CLAUDE.md file, apply progressive disclosure to split long instructions into a minimal root file and linked Markdown documents. This extracts universal rules and moves context-specific guidelines into categorized files for better maintainability.

What is progressive disclosure for agent instructions?▼

Progressive disclosure for agent instructions is an organization method that keeps essential details in a root file and moves less critical instructions into linked, categorized Markdown documents. This structure improves clarity and makes agent instructions easier to process and manage.

How do I resolve contradictions in AGENTS.md documentation?▼

Resolving contradictions in AGENTS.md documentation involves analyzing the file to identify conflicting instructions and extracting essential universal rules. The refactoring process flags vague or redundant instructions for deletion to ensure consistent agent behavior.

Can I split my agent instructions by categories like testing and git workflow?▼

Yes, you can split agent instructions by categories like testing and git workflow. The refactoring process organizes content by extracting context-specific details from the root file and moving them into separate categorized Markdown files such as typescript.md or testing.md.

What is the best way to maintain long Markdown agent instruction files?▼

The best way to maintain long Markdown agent instruction files is restructuring them via progressive disclosure. This separates essential universal rules into a concise root file and links to categorized documents, resolving contradictions and eliminating redundant instructions.