agent-md-refactor

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

Refactor monolithic agent instruction files into linked markdown files with progressive disclosure.

Updated Mar 12, 2026

Search Tags:#documentation #markdown #refactor #code organization #progressive disclosure #agent instructions

Ready to run

npx skills add https://github.com/WesleyMarinho/codeseek-marketplace --skill agent-md-refactor-wesleymarinho

💬 Prompt for ChatGPT / Claude Chat▼

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

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 organizing them using progressive disclosure, making them easier to manage and understand.

Core Features & Use Cases

Progressive Disclosure: Splits monolithic instruction files into a minimal root file and linked, categorized sub-files.
Contradiction Detection: Identifies conflicting instructions within the original file.
Use Case: Refactor a 500-line CLAUDE.md file into a concise root file with links to separate markdown files for TypeScript, testing, and code style guidelines.

Quick Start

Refactor my CLAUDE.md file using progressive disclosure.

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 agent instruction file using progressive disclosure?▼

Refactoring agent instruction files using progressive disclosure splits monolithic configurations into a minimal root file and linked, categorized sub-files. It extracts essential information for the root file, categorizes remaining instructions into separate markdown files, and flags redundant content for deletion.

What is the best way to organize a large CLAUDE.md or AGENTS.md file?▼

The best way to organize large instruction files like CLAUDE.md is progressive disclosure, which creates a concise root file with links to separate markdown files for specific guidelines like TypeScript, testing, or code style, improving maintainability and readability.

Can I detect contradictions in agent instructions before splitting them into markdown files?▼

Yes, contradiction detection is supported during the refactoring process. The Skill analyzes the original monolithic file to identify conflicting instructions before extracting essential information and categorizing the remaining instructions into linked markdown files.

How do I split a 500-line CLAUDE.md into separate markdown files for code style and testing?▼

Splitting a 500-line CLAUDE.md involves analyzing the file, extracting essential instructions for a minimal root file, and categorizing the remaining content into linked markdown files for specific topics like testing and code style, while flagging redundant content for deletion.

Does refactoring agent instructions into linked markdown files improve code organization?▼

Refactoring agent instructions into linked markdown files improves code organization by applying progressive disclosure principles. This approach enhances the maintainability and readability of agent configurations by replacing monolithic files with a structured, categorized format.

When should I not use progressive disclosure for agent instruction files?▼

Progressive disclosure for agent instruction files may not suit small, simple configurations that do not suffer from maintainability or readability issues, as the overhead of creating linked markdown files outweighs the organizational benefits for minimal content.