agent-md-refactor

Overview of agent-md-refactor skill

The agent-md-refactor skill helps you turn an overgrown AGENTS.md, CLAUDE.md, COPILOT.md, or similar agent instruction file into a smaller root file plus linked supporting docs. The core idea is progressive disclosure: keep only universal, always-needed instructions at the top level, and move specialized guidance into organized files.

What agent-md-refactor is for

agent-md-refactor is best for teams or solo maintainers whose agent docs have become long, repetitive, contradictory, or expensive to load on every task. The real job-to-be-done is not “make markdown prettier.” It is to reduce context waste, surface the few rules that must always apply, and make the rest easier to maintain.

Who should install this skill

This agent-md-refactor skill is a strong fit if you:

• maintain a root instruction file that keeps growing
• have mixed topics in one file, such as coding style, testing, architecture, and workflows
• suspect contradictions have accumulated
• want a cleaner setup for Context Engineering without rewriting everything manually

What makes it different from a normal rewrite prompt

A generic prompt may summarize or shorten your file. agent-md-refactor is more structured: it starts by checking for contradictions, separates essential instructions from optional ones, groups the remainder into categories, proposes a file hierarchy, and flags vague or redundant content for deletion. That process is the main differentiator.

What users usually care about first

Before adopting agent-md-refactor, most users want to know:

• Will it preserve important rules instead of deleting them?
• Will it help reduce token/context load?
• Will it expose conflicting instructions clearly?
• Can it work with my existing file names and repo conventions?

Based on the repository, the answer is broadly yes, but the quality depends heavily on the quality of the source file and the clarity of your desired structure.

How to Use agent-md-refactor skill

agent-md-refactor install context

The upstream skill lives in softaworks/agent-toolkit under skills/agent-md-refactor. A typical install pattern is:

npx skills add softaworks/agent-toolkit --skill agent-md-refactor

If your environment uses a different skill-loading workflow, use that instead. The key point is that agent-md-refactor is meant to be invoked as a reusable skill, not copied line-by-line into your own prompt.

Files to read before first use

Start with:

• skills/agent-md-refactor/SKILL.md
• skills/agent-md-refactor/README.md

Read SKILL.md first for the operational workflow. Read README.md next for fit guidance, why the skill exists, and what kinds of instruction files are good candidates.

Best input candidates

agent-md-refactor usage is strongest when the source file:

• exceeds roughly 50 to 100 lines
• mixes multiple topics in one place
• contains both universal rules and task-specific guidance
• has grown incrementally over time
• likely contains outdated or duplicate instructions

If your file is already short, clean, and intentionally minimal, this skill may add structure without much benefit.

What input to give the skill

At minimum, provide:

• the current root instruction file content
• the current filename, such as AGENTS.md or CLAUDE.md
• your preferred target structure, if you have one
• any constraints on file naming, depth, or link style

Helpful extras:

• whether agents should load only the root file by default
• whether some sections must remain at root
• whether certain content is deprecated but still needs review

Turn a vague goal into a strong prompt

Weak prompt:

• “Refactor my agent file.”

Stronger prompt:

• “Use agent-md-refactor on this CLAUDE.md. First identify contradictions. Then separate universal root instructions from topic-specific guidance. Propose a progressive-disclosure structure using linked markdown files. Keep the root file as short as possible without losing always-needed rules. Flag vague, redundant, or obsolete instructions instead of preserving them blindly.”

That stronger prompt improves results because it gives the skill its intended sequence and decision criteria.

Recommended workflow in practice

A practical agent-md-refactor guide looks like this:

1. Paste the current instruction file.
2. Ask for contradictions first.
3. Confirm which side of each conflict should win.
4. Ask for the essential root-only instructions.
5. Ask for the proposed file tree and linked file breakdown.
6. Review what the skill recommends pruning.
7. Apply the rewrite and then manually validate links, filenames, and load behavior.

The contradiction step matters. If skipped, the skill may reorganize conflicting instructions instead of resolving them.

What the output should contain

A good agent-md-refactor usage result usually includes:

• a contradiction list
• a short root file draft
• categorized supporting files
• internal links between files
• explicit deletion candidates
• rationale for what stays at root versus what moves

If you only get a shortened single document, you likely asked for summarization rather than a full skill-driven refactor.

How to use agent-md-refactor for Context Engineering

agent-md-refactor for Context Engineering is mainly about controlling what gets loaded by default. Keep universal rules in the root file and move specialized guidance into discoverable linked docs. That can reduce irrelevant context on routine tasks while preserving deeper instructions when needed.

The skill is especially useful when your current setup forces every task to read a giant instruction file even though most tasks only need a small subset.

Practical review criteria after generation

Before accepting the output, check:

• Is the root file genuinely small and universal?
• Were contradictions surfaced clearly?
• Did related topics get grouped logically?
• Are links and filenames easy for agents and humans to follow?
• Were low-value statements pruned instead of merely relocated?

This review catches the most common failure mode: moving clutter around without increasing clarity.

agent-md-refactor skill FAQ

Is agent-md-refactor better than just asking an LLM to shorten my file?

Usually yes, if your problem is structure rather than length alone. The value of agent-md-refactor is the workflow: contradiction detection, extraction of essentials, categorization, hierarchy design, and pruning. A plain shortening prompt often misses those steps.

Is this skill beginner-friendly?

Yes, with one caveat: beginners may accept every proposed deletion too quickly. The process is easy to follow, but you still need to judge which instructions are truly universal, which are optional, and which are outdated.

When should I not use agent-md-refactor?

Skip agent-md-refactor if:

• your file is already compact and well-structured
• you only need copyediting
• your team has not yet agreed on core conventions
• the real problem is missing instructions, not bloated ones

This skill is for reorganization and pruning, not policy creation from scratch.

Does it require a specific agent tool or file name?

No. The repository examples mention files like AGENTS.md, CLAUDE.md, and COPILOT.md, but the method is portable. What matters is that you have a markdown instruction file that has become too broad or too long.

Will it automatically resolve contradictions for me?

Not safely on its own. agent-md-refactor is good at surfacing contradictions and framing the decision, but a human or repo owner should decide which rule wins. That is especially important for style guides, workflow rules, and tool preferences.

How to Improve agent-md-refactor skill

Give stronger structure targets

To improve agent-md-refactor output, tell it what “good structure” means in your repo. Examples:

• “Keep the root file under 40 lines.”
• “Use one file per topic: testing, style, architecture, workflows.”
• “Do not nest more than one directory deep.”
• “Use relative markdown links only.”

Without these constraints, the skill may produce a reasonable structure that still does not fit your environment.

Resolve conflicts before asking for final drafts

The highest-impact improvement is to handle contradiction questions explicitly. If the model finds “use semicolons” and “no semicolons,” do not ask for the final refactor until you have chosen one. Otherwise the final structure may look clean while preserving unclear policy.

Mark what must stay at root

A common failure mode is over-decomposition. Improve results by labeling content such as:

• always-on behavioral rules
• critical safety constraints
• universal repo workflow expectations
• mandatory communication style requirements

This keeps agent-md-refactor from pushing important baseline instructions too far down the tree.

Tell it what to prune aggressively

If you want real information gain, instruct the skill to flag:

• vague platitudes
• duplicate rules
• obvious defaults
• historical notes that no longer guide behavior
• low-signal reminders that do not change decisions

That pruning step is where many refactors become genuinely useful instead of merely better formatted.

Iterate on the root file separately

After the first pass, do one focused revision only on the root file. Ask:

• Is every line universally relevant?
• Does anything belong in a linked doc instead?
• Is any essential rule still buried outside the root?

This second pass usually improves the final result more than asking for a full rewrite again.

Compare before and after load behavior

For agent-md-refactor for Context Engineering, the success metric is not just readability. It is whether routine tasks now need less irrelevant instruction context. After refactoring, compare:

• old root file length
• new root file length
• number of specialized topics moved out
• whether common tasks can proceed from the root file alone

If nothing meaningful changed, the refactor may be cosmetic rather than operational.

Keep the file map simple

More files are not always better. A strong agent-md-refactor skill result usually creates enough separation to improve discoverability, but not so much that agents must chase a maze of links. If the proposed hierarchy feels too deep, ask for a flatter version with fewer categories.

Use your first repo pass to sharpen future prompts

Once you have used agent-md-refactor once, save a reusable invocation pattern for your team. Include:

• your preferred root-file length
• your standard topic categories
• your pruning standards
• your link conventions
• your preferred contradiction resolution format

That turns the skill from a one-off cleanup tool into a repeatable maintenance workflow.