What is progressive disclosure in this context?

It is a design principle where you keep only the most essential, universal information at the root level and move specific, detailed guidelines to secondary files, which are linked and accessed only when relevant.

Does it work with files other than CLAUDE.md?

Yes, it is designed to refactor any agent-facing instruction file, including AGENTS.md, COPILOT.md, or custom project documentation used by AI agents.

How does this help with AI agent performance?

Large, monolithic instruction files waste context tokens and can confuse agents with conflicting rules. Streamlining the root file provides the agent with a clearer, faster, and more accurate project context.

Will this skill delete my existing instructions?

The skill identifies redundant, vague, or outdated instructions for potential deletion in Phase 5, but it flags them for your review so you maintain full control over your documentation.

Agent MD Refactor

Name: Agent MD Refactor
Author: softaworks

bysoftaworks

•

347

•

Productivity & Workflow

Refactors bloated agent instruction files into an organized, multi-file structure using progressive disclosure principles.

The Agent MD Refactor skill helps developers manage massive, monolithic instruction files like CLAUDE.md or AGENTS.md. By applying progressive disclosure, it extracts core project essentials into a minimal root file while delegating detailed conventions—such as TypeScript patterns, testing guidelines, and architecture rules—into specialized, linked sub-documents. This process reduces token waste, resolves instructional contradictions, and ensures AI agents receive only the most relevant context for any given task.

Key Features

01Prunes redundant or vague instructions to optimize AI context usage

02Automatically categorizes detailed rules into specialized Markdown sub-files

03Identifies and resolves conflicting instructions within monolithic files

04347 GitHub stars

05Extracts critical project metadata for a minimal, high-impact root file

06Creates a clean, linked documentation hierarchy for easier maintenance

Use Cases

01Standardizing instruction files across multiple microservices or repositories

02Organizing chaotic developer notes into actionable, categorized agent guidelines

03Slimming down a 500-line CLAUDE.md file that is causing token bloat

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add softaworks/agent-toolkit agent-md-refactor

For use in Claude.ai and ChatGPT

Download Skill