/refactor-skill

name: refactor-skill
description: Use when about to refactor or refine an existing skill, its SKILL.md or sibling files, from a full restructure down to a one-line wording fix; a change that looks too small to need this skill is not an exemption. Not for creating a skill from scratch
argument-hint: [skill name | path/to/SKILL.md]
allowed-tools:
  - WebFetch(domain:platform.claude.com)
  - WebFetch(domain:code.claude.com)
  - WebFetch(domain:developers.openai.com)
  - Edit(**/skills/**)

Overview

Refactor a skill. A skill spends two budgets. Its description is loaded into every session, so each word there must do triggering work. Its body enters the context on invocation and stays there for the rest of the session, so each line there must guide every path through the skill. Conditional material moves behind a pointer; unnecessary material leaves the skill.

Instructions

Use `AskUserQuestion` in Claude Code or `request_user_input` in Codex when available.

1. **Pick the target.** If the invocation names one, resolve it to its `SKILL.md`. Otherwise ask which skill. For a full audit, read `SKILL.md` and every sibling file in its directory. For a targeted change, read `SKILL.md`, affected files, and references needed to assess their interactions. That change sets the scope: the verdicts below cover the lines it adds or touches, the rest of the skill stays as it is, and anything noticed there is a follow-up.

2. **Fetch the guides.** The platform and model guides below calibrate the delete, demote, and rewrite verdicts.

• Fetch one model guide, picked by the target skill's `model:` frontmatter. Unset or `inherit` means the most capable model of the family running this skill: `fable` under Claude, `gpt-6-astra` under a GPT model. Read the matching reference and fetch the pages it lists:
• **Claude Code** (`fable`, `opus`, `sonnet`): [references/claude-code.md](references/claude-code.md).
• **Codex** (`gpt-6-astra`): [references/codex.md](references/codex.md).

3. **Audit.** Give every frontmatter key, body instruction, and sibling file in scope exactly one verdict, judged against its bar below. Done when nothing in scope lacks a verdict.

• **contradiction**: conflicts with another instruction, or the frontmatter promises what the body does not deliver, such as a `context: fork` skill whose body assumes conversation history. Record both sides.
• **delete**: fails the no-op test, meaning the model the skill targets would behave the same without it, or the fetched pages say to remove it because it was written for an earlier model's habits. Judge defaults against those pages, not memory. Covers explanations of what the model already knows, emphasis that carries no instruction, and sibling files nothing points to.
• **demote**: real content that only some runs of the skill reach. Destinations: a file in the skill directory linked from `SKILL.md`, one level deep; a script under `scripts/` when the steps are deterministic; a separate skill only when it needs its own trigger or another skill must reach it. Name the destination.
• **rewrite**: right meaning, phrasing falls short of the fetched pages: a description that names features instead of triggers, a step with no completion criterion, a prohibition with no positive target, a rule shouted in capitals instead of explained. Also a rewrite when the line carries words that fail the no-op test on their own: a duplicate of another line, a definition of a term the model knows, or emphasis; a rationale or example stays, since both steer the model. Among wordings that pass the bar, the shortest wins. Voice follows the system prompt: the body addresses the model as "you" and names the human as "the user", so "I" or "my" for the human, and "Claude" or "the agent" for the model, are rewrites; words quoted as user speech keep their own voice.
• **keep**: earns its cost as written, and no shorter wording has the same effect.

The bar per part:

• **Frontmatter** (each key a decision, judged before the body): `disable-model-invocation: true` when only the user ever names the skill; omitted when the agent must reach the skill on its own, or another skill or a `CLAUDE.md` line invokes it. `user-invocable: false` when the human never runs it by hand. `context: fork` when the arguments fully specify the work and the body needs no conversation history. `model` and `effort` only when a run at the inherited value failed, and `model` only on a `context: fork` skill or one that owns the whole turn. `argument-hint` present when the skill takes arguments, absent when it does not.
• **Description** (loaded into every session): every word does triggering work. Leads with when to use, names each distinct trigger once, marks the near miss it must not fire on. A user-invoked skill gets a one-line human-facing summary with no trigger list.
• **Body** (in context from invocation to session end): actions, constraints, completion criteria, or reference every path through the skill needs. Require a fixed order only where correctness depends on it; route conditional workflows to supporting files. Written as standing instructions, since the body is never re-read.
• **Sibling files** (loaded only when reached): each has a pointer in `SKILL.md` stating what it is and when to read it, or for a script, when to run it. A file with no pointer is unreachable.

4. **Get decisions.** Reuse changes and verdicts the user already authorized. Resolve contradictions from instruction priority and explicit user intent where possible; for each unresolved one, ask with `AskUserQuestion` or `request_user_input`, each conflicting version an option. Present any remaining delete and demote proposals and collect sign-off. Preserve explicit review boundaries and leave unapproved proposals untouched.

5. **Rewrite.** Apply the authorized changes and verdicts in one pass, without asking again. Apply only those: anything else noticed while editing is a fol