agent-md-refactor

Refactor monolithic agent instruction files into linked documentation hierarchies.

Updated May 21, 2026

Search Tags:#documentation #refactoring #claude-code #token-optimization #progressive-disclosure #agent-config

Ready to run

npx skills add https://github.com/caiohbfurtado/apac-web --skill agent-md-refactor-caiohbfurtado

💬 Prompt for ChatGPT / Claude Chat▼

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill solves the problem of bloated, unmanageable agent instruction files (like CLAUDE.md or AGENTS.md) that waste context tokens and contain contradictory or redundant information.

Core Features & Use Cases

Progressive Disclosure: Automatically splits monolithic instruction files into a minimal root file and categorized, linked sub-files.
Contradiction Detection: Identifies conflicting rules and prompts the user for resolution before restructuring.
Pruning: Identifies and flags vague, redundant, or outdated instructions for deletion to optimize token usage.

Quick Start

Ask the agent to refactor your CLAUDE.md file to apply progressive disclosure principles and clean up your instructions.

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 bloated CLAUDE.md file to optimize context tokens?▼

You can refactor a bloated agent instruction file by applying progressive disclosure principles to split it into a minimal root file and categorized, linked sub-files. This structure optimizes token usage and improves AI context management.

What is progressive disclosure for agent configuration files?▼

Progressive disclosure for agent configuration files is the practice of breaking down monolithic instruction documents into a minimal root file with links to categorized sub-files. This technique reduces context token waste and enhances instruction clarity for AI agents.

How do I identify and resolve contradictions in AGENTS.md instructions?▼

Identifying contradictions in AGENTS.md instructions requires systematic analysis of the file content to detect conflicting rules. The refactoring process flags these conflicts and prompts the user for resolution before restructuring the documentation hierarchy.

Can I use this refactoring approach to prune redundant instructions from project-level configuration files?▼

Yes, the refactoring approach specifically prunes project-level configuration files by identifying and flagging vague, redundant, or outdated instructions for deletion. This optimizes token usage and ensures only essential rules remain in the documentation.

Does agent-md-refactor work with any dependencies or specific frameworks?▼

Agent-md-refactor operates independently without requiring external dependencies or frameworks. It functions as a standalone skill to restructure project-level configuration files like CLAUDE.md or AGENTS.md by analyzing existing instruction content.

What is the best way to clean up unmanageable agent instruction files?▼

The best way to clean up unmanageable agent instruction files is to systematically analyze the content for contradictions, essential rules, and redundant information. This allows you to prune outdated instructions and restructure the remaining content into a linked documentation hierarchy.