# Refactor Skills

> Reviews the markdown and template files changed in the current session and tightens them for agent performance — sharper trigger descriptions, progressive disclosure, imperative voice, one-claim-per-bullet, fewer redundant rules — while preserving every workflow step, constraint, and trigger condition. Use when the user has just edited one or more skill or prompt files (`SKILL.md`, `references/*.md`, `recipes/*.md`, agent templates, slash-command prompts) and wants a tightening pass before committing, or invokes "/refactor-skills", "refactor this skill", "tighten the skill", "polish SKILL.md", "make this skill leaner". Behaviour-preserving only — never use this to add features, expand scope, or remove rules.

- Skill: `usrrname/refactor-skills` (Agent Skill)
- Install (CLI): `npx skillmds@latest add usrrname/refactor-skills`
- Raw SKILL.md: https://api.skillmd.com/api/skills/usrrname/refactor-skills/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: usrrname (https://skillmd.com/u/usrrname)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/usrrname/refactor-skills

---


# Refactor Skills — agent performance ↑, behaviour =

Tightens the markdown / template / skill files touched in the current session. Every edit must make the file cheaper or clearer for an agent to load and act on, **without changing what the skill does**.

## Inputs

- Default: every uncommitted `.md`, `.tmpl`, `.txt`, and `.prompt` file under `.claude/`, `~/.claude/`, `docs/`, or any path the session has been editing. Discover with `git status --porcelain` plus the Edit/Write tool history of the current conversation.
- If the user names specific files or a directory, restrict to those.
- Skip files outside `.claude/`, `docs/`, or the user-specified scope; this skill is not a general prose editor.

## Agent-performance heuristics

Apply in this order. Each is a **no-behaviour-change** edit:

1. **Sharper trigger description.** The frontmatter `description` is the only thing the harness sees when ranking skills. Lead with the capability in 1 sentence; follow with "Use when …" listing concrete phrases the user actually says. Drop hedging ("might be helpful for …") and synonyms that add no discoverability. Keep ≤ 1024 chars.
2. **Progressive disclosure.** `SKILL.md` stays under 100 lines. Anything longer, domain-heavy, or rarely needed → move to `references/<topic>.md` and link from SKILL.md. The agent only loads SKILL.md by default.
3. **Imperative voice.** "Run X" > "You should run X" > "It is recommended to run X". Cut auxiliaries.
4. **Concrete over abstract.** Replace "use appropriate tools" with the actual tool name; replace placeholder code with code that runs.
5. **One claim per bullet.** Split bullets that say "do A and B and C" — the agent skims faster and misses less.
6. **Cut dead weight.** Repeated rules, restated context, "let me know if you need anything else", filler intros — gone.
7. **Co-locate constraints.** Rules buried in a trailing "Notes" section get missed. Move them next to the step they constrain.
8. **Examples match the description.** If the description claims "use when X", an example must contain X verbatim.

## What you must NOT change

These are behaviour. Touching them changes what the skill does:

- The set of workflow steps (rename or reorder for clarity, but never drop, add, or merge).
- Any explicit `must` / `do not` / `never` rule — the user codified those deliberately.
- The `allowed-tools:` list in frontmatter.
- Required artefact paths, file naming conventions, output formats.
- Trigger scope in the description (sharpen wording, never narrow or broaden which situations match).
- Examples that document edge cases — those are tests of the description's contract.

If unsure whether a change is performance or behaviour, **ask the user** before applying.

## Workflow

1. **Inventory.** `git status --porcelain` + the Edit/Write tool history. List candidate files with line counts. Filter to `.md` / `.tmpl` / `.prompt` under in-scope paths.
2. **Read each file in full.** Note its frontmatter purpose and structural divisions.
3. **Per-file diff plan.** For each file, list heuristic violations as `heuristic → location → proposed change`. One bullet per violation. Do not write the rewrite yet.
4. **Confirm with the user.** Show the diff plan; ask whether any item crosses the behaviour line. Wait for approval before any edit.
5. **Apply via Edit.** Use the Edit tool, not Write — minimal diffs are reviewable; full rewrites hide regressions.
6. **Verify behaviour preserved.** Re-read each file end-to-end. Workflow steps, rules, allowed-tools, and trigger conditions must read the same.
7. **Report.** Per file: `<path>: <before> → <after> lines. Key wins: <2-3 bullets>.`

## Final assistant-message summary

```text
Refactored N file(s).

- <path>: <before> → <after> lines. <one-line headline change>
- <path>: <before> → <after> lines. <one-line headline change>

Behaviour preserved: workflow steps, rules, allowed-tools, triggers unchanged.
```

If any file was left untouched (already tight, or change would cross the behaviour line), say so explicitly with the reason.