An automated workflow optimization skill designed to refactor bloated AGENTS.md and CLAUDE.md files into streamlined, high-performance instruction trees using progressive disclosure.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install refactor-agents-md
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install refactor-agents-md using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Refactor Agents Markdown?
The refactor-agents-md skill is a developer-centric tool designed to combat context bloat and instruction drift in AI agent configuration files. As AI-native codebases evolve, AGENTS.md and CLAUDE.md files often devolve into a chaotic "ball of mud" filled with contradictory commands, redundant specs, and stale project instructions. By integrating this skill into your library of Openclaw Skills, you can systematically audit, prune, and refactor these files to ensure your coding assistants always receive hyper-focused, accurate context.
This skill employs the principle of progressive disclosure, ensuring that the root AGENTS.md remains short, stable, and universal. Highly specific guidelines—such as state management protocols, testing setups, or database schema patterns—are extracted into dedicated, topic-specific follow-up documents. This structured hierarchical routing prevents AI context window pollution and helps coding agents execute tasks with surgical precision.
Refactor Agents Markdown Use Cases
- Resolving Instruction Bloat: Clean up giant AGENTS.md files that have accumulated stale commands, duplicative workflows, and outdated guidelines over months of active development.
- Eliminating Agent Contradictions: Identify and surface hidden conflicts between old and new development commands before they confuse your coding agents.
- Optimizing Context Windows: Transition to a progressive disclosure model where the root config file acts as a clean router to modular topic documents.
- Repository Onboarding Audit: Establish a reliable baseline of agent instructions when introducing AI coding tools to an existing legacy repository.
- Standardizing Multi-Agent Workflows: Partition guidelines by functional topics rather than chronological updates or individual author preferences.
How Refactor Agents Markdown Works
- Intake and Mode Selection: The skill asks the user to choose an operational mode: Review only, Propose a rewrite, or Apply the refactor directly within the repository.
- Instruction Classification: It reads the existing AGENTS.md content and classifies every instruction line as either root-essential, topic-specific, conflicting, redundant, vague, or stale.
- Conflict Resolution: If conflicting instructions are identified, the skill halts the automated rewrite to surface the contradiction and seek developer clarification.
- Pruning and Extraction: It filters out redundant and self-evident bloat while extracting detailed instructions into modular topic files within a structured documentation hierarchy.
- Deployment or Proposal Generation: The skill either generates a comprehensive markdown proposal detailing the new file tree or applies the refactored files directly to the target repository paths.
Refactor Agents Markdown Setup
To integrate this skill into your local workspace, clone the repository containing the skill configuration and register it within your agent host. Below is a standard setup template:
# Navigate to your agent workspace directory
cd ~/.openclaw/skills
# Clone or copy the refactor-agents-md skill definition
git clone https://github.com/Fei2-Labs/skill-genie.git
# Initialize the skill via your CLI runtime
openclaw skills register ./skill-genie/refactor-agents-md
Ensure that your workspace runner has read and write permissions for the directory containing your project's AGENTS.md or CLAUDE.md file.
Refactor Agents Markdown Data Schema & Taxonomy
This skill operates on structured inputs and generates a standardized file layout to achieve progressive disclosure. It categorizes markdown instruction sets according to the taxonomy below:
| Document Type | Target Directory | Description |
|---|---|---|
| Root AGENTS.md | / (Project Root) |
Minimal file containing only one-line project description, package manager expectations, and universal build/test commands. |
| Topic Guidance | /docs/agents/ or /references/ |
Modular, topic-specific guidelines grouped by architectural layer or functional concern (e.g., state, testing, styling). |
| Principles Manifest | /references/principles.md |
Core heuristics and development constraints shared across all specialized agents. |
Instruction Classification Taxonomy
- Root-Essential: Universal instructions valid for every command run within the repository.
- Topic-Specific: Deep technical instructions relative only to specific files, languages, or features.
- Stale/Redundant: Duplicated directives, standard boilerplate, or instructions superseded by newer project constraints.
Refactor Agents Markdown Advanced Features
- Automated In-Repo Refactoring: Seamlessly writes newly partitioned topic files and updates the root instruction file in a single execution loop.
- Conflict Alert Interceptor: Halts modification processes to alert developers of logical paradoxes within their current instruction sets.
- Progressive Disclosure Routing: Structures root configuration files to act as high-level routers, pointing coding agents directly to specialized follow-up documentation on demand.
- Compatibility with Openclaw Skills ecosystems: Native integration with open-source agent protocols allows this refactoring workflow to clean instructions for a wide array of secondary automated skills.
SKILL.md
Loading
Related Openclaw Skills
WordPress VPS Install
An automated workflow to provision, secure, and bootstrap WordPress on a fresh VPS using Dokploy and Docker Compose.
The Book of Forgiving Skill
An interactive AI agent skill that guides users through Desmond and Mpho Tutu's Fourfold Path for healing, forgiveness, and personal reconciliation.
IdeaForge
IdeaForge transforms vague ideas and raw coding concepts into zero-ambiguity, implementation-ready project specs tailored for human developers and downstream AI coding agents.
The Brain That Changes Itself - Neuroplasticity AI Guide
An interactive AI agent skill that guides users through the principles and clinical techniques of neuroplasticity, based on Norman Doidge's landmark book, to help rewire the brain for stroke recovery, cognitive enhancement, and mental wellness.
RTK Token Saver
A CLI proxy skill designed to compress verbose terminal, build, and git outputs to minimize LLM token usage during agent executions.
Stalwart Mail Server on Dokploy with Resend SMTP Relay
An automated skill to deploy Stalwart Mail Server on Dokploy with a Resend SMTP relay fallback for blocked port 25 environments.
Featured*
