agent-md-refactor

Refactor monolithic AGENTS.md files into modular AGENTS.md and SKILLS.md documents.

4|Updated Oct 6, 2025

Search Tags:#documentation #refactoring #progressive-disclosure #agent-docs #skills-template #context-splitting

Ready to run

npx skills add https://github.com/AgnosticSix/agent-md-template --skill agent-md-refactor-agnosticsix

💬 Prompt for ChatGPT / Claude Chat▼

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Refactors bloated AGENTS.md, CLAUDE.md, or similar agent instruction files that mix project context with executable procedures into a cleaner, modular structure so agents can understand both layers without being overwhelmed.

Core Features & Use Cases

Context vs. Capability Separation: Identifies where project background belongs and where procedural instructions should live, then generates AGENTS.md and SKILLS.md with progressive disclosure.
Template-Driven Output: Fills comprehensive templates for both context and skills, ensuring consistent architecture, tooling, and conventions coverage.
Use Case: When an AI agent inherits a massive AGENTS.md that is hard to maintain, this skill rewrites it into clear context documentation plus a dedicated catalog of skills for routine tasks.

Quick Start

Use the agent-md-refactor skill to split a bloated AGENTS.md into separate AGENTS.md context and SKILLS.md procedure documents.

Frequently Asked Questions about agent-md-refactor

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

FAQPage Schema

How do I split a monolithic AGENTS.md file into modular documentation?▼

Splitting a bloated CLAUDE.md file involves separating project background from procedural instructions, then generating modular AGENTS.md context and SKILLS.md procedure files with progressive disclosure to reduce agent overload.

What is progressive disclosure for agent documentation?▼

Progressive disclosure for agent docs structures information by linking high-level context with executable templates and skill entries, preventing AI agents from being overwhelmed by monolithic instruction files.

Can I refactor agent instruction files that mix backend and frontend procedures?▼

Yes, you can refactor agent instruction files that mix backend and frontend procedures. The refactoring process applies to hybrid repositories, cleanly separating broad project context from specific routine task skills.

What's the best way to separate project context from executable skills in CLAUDE.md?▼

The best way to separate project context from executable skills in CLAUDE.md is using template-driven refactoring to identify where background belongs and where procedures live, generating distinct context and skills catalogs.

Do I need any dependencies to refactor agent docs into modular context?▼

No dependencies are required to refactor agent docs into modular context. The skill operates independently to analyze existing monolithic files and rewrite them into structured context and skill entries.