agent-md-refactor

Refactors bloated agent instruction files into linked documentation using progressive disclosure.

Updated Jun 2, 2026
One-click install
npx skills add https://github.com/lfuuu/claude-rules --skill agent-md-refactor-lfuuu
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: agent-md-refactor
Source: https://github.com/lfuuu/claude-rules/tree/main/global-skills/agent-md-refactor
Command: npx skills add https://github.com/lfuuu/claude-rules --skill agent-md-refactor-lfuuu

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Agent instruction files like CLAUDE.md, AGENTS.md, and COPILOT.md grow into bloated monoliths over time, wasting context tokens on every task, accumulating contradictions, and burying important rules among vague or redundant statements. ## Core Features & Use Cases - Contradiction Detection: Identifies conflicting instructions (e.g., opposing style rules) and asks the user to resolve them before restructuring. - Progressive Disclosure Restructuring: Keeps only universal, task-critical rules in a minimal root file (under 50 lines) and organizes the rest into 3-8 categorized linked files such as typescript.md, testing.md, and git-workflow.md. - Redundancy Cleanup: Flags vague, obvious, or outdated instructions for deletion so they stop consuming context tokens. - Use Case: Your CLAUDE.md has grown past 400 lines mixing code style, testing, and architecture rules. Run this Skill to get a lean root file with quick-reference commands plus organized, linked guideline files. ## Quick Start Ask the agent to refactor your CLAUDE.md file using progressive disclosure to split it into organized linked documentation.

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 CLAUDE.md file that is too long?

Apply progressive disclosure: keep only universal rules applying to every task in the root file, then move topic-specific instructions into linked files like testing.md or code-style.md. This Skill automates that five-phase process including contradiction detection and cleanup.

What should stay in the root AGENTS.md file?

Keep only information applying to 100% of tasks: a one-sentence project description, non-default package manager, custom build or test commands, and critical overrides. Move language conventions, testing guidance, and style details into linked files.

Does this work with AGENTS.md and COPILOT.md or only CLAUDE.md?

It works with any agent instruction file including CLAUDE.md, AGENTS.md, and COPILOT.md. The same five-phase refactoring process applies regardless of which agent platform the file targets.

How many linked files should agent instructions be split into?

Aim for 3-8 linked files grouped by logical topic such as typescript.md, testing.md, git-workflow.md, and architecture.md. Fewer causes bloating; more creates fragmentation and navigation overhead.

Which instructions should be deleted from agent config files?

Delete instructions that are redundant ("Use TypeScript" in a TS project), too vague ("write clean code"), overly obvious ("don't introduce bugs"), restate default behavior, or reference outdated APIs. These waste context tokens without value.