agent-md-refactor

Refactor monolithic agent instruction files into linked Markdown documents.

1|Updated Oct 19, 2025

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

Ready to run

npx skills add https://github.com/antoine-bouteiller/autoscan --skill agent-md-refactor-antoine-bouteiller

💬 Prompt for ChatGPT / Claude Chat▼

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

SYSTEM DOCUMENTATION & REQUIREMENTS

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 clarity and maintainability.

Core Features & Use Cases

Progressive Disclosure: Splits monolithic instruction files into a concise root file and linked, categorized sub-files.
Conflict Resolution: Identifies and helps resolve contradictory instructions within the agent's configuration.
Use Case: You have a 500-line CLAUDE.md file. Use this skill to distill it into a single-page overview with links to detailed sections for code style, testing, and Git workflow, making it much easier for the agent (and you) to navigate.

Quick Start

Refactor my AGENTS.md file to follow progressive disclosure principles.

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 long agent instruction file into linked Markdown documents?▼

To refactor a long agent instruction file, restructure the monolithic Markdown into a concise root file and linked sub-files. This progressive disclosure organizes detailed instructions into separate categorized documents for improved readability.

What is progressive disclosure for agent instructions?▼

Progressive disclosure for agent instructions is the process of splitting a monolithic configuration file into a concise root overview with links to detailed, categorized sub-files, making the hierarchy easier to navigate.

How do I resolve contradictory instructions in a CLAUDE.md or AGENTS.md file?▼

Resolving contradictory instructions in a CLAUDE.md or AGENTS.md file involves refactoring the monolithic document to identify conflicts, address contradictions, and flag redundant content for deletion during the restructuring process.

When should I split my monolithic agent instructions into separate files?▼

You should split monolithic agent instructions into separate files when the configuration becomes overly long and complex, such as a 500-line file, to distill it into a single-page overview with links to detailed sections.

Does refactoring agent instructions affect the existing content categories?▼

Refactoring agent instructions preserves existing content categories by organizing them into linked sub-files. It categorizes detailed instructions for specific areas like code style, testing, and Git workflow into separate, maintainable documents.