skill-scope

What this skill does

# Skill Scope

Decide the shape of a Claude skill before `skill-creator` builds it. Run four phases: fast-path check, scoping tests, explicit verdict, handoff.

---

## Workflow

1. **Fast-path check** — if scope is already settled, confirm in one line and skip to handoff.
2. **Apply scoping tests** — run the relevant tests below. Don't read all of them on every invocation; pull only the ones that fit the situation.
3. **State the verdict** — exactly one of: `NEW` / `EXTEND` / `SPLIT` / `MERGE`. No hedging.
4. **Hand off** — to `skill-creator` with the verdict and a one-sentence responsibility statement.

---

## Phase 1 — Fast-path check

Scope is already settled when the user's message:

- Names a clear single responsibility and a unique skill name (e.g., "make a skill for converting CSV files to Markdown tables").
- Explicitly states the verdict ("I want to add a new phase to `pr-create`", "split `monolith-skill` into X and Y").
- Confirms a previous scoping discussion ("we already agreed it's a new skill, just build it").

In those cases:

> "Scope checks out: <verdict> — <one-sentence responsibility>. Handing off to skill-creator."

Then go straight to Phase 4. Do not run the test suite.

Scope is **not** settled when the user:
- Asks "should this be one skill or two?" or any phrasing of the scope question itself.
- Describes a workflow without committing to it being a skill.
- Names an existing skill that might already cover the work.
- Proposes a skill whose responsibility overlaps multiple existing skills.

Continue to Phase 2.

---

## Phase 2 — Scoping tests

Apply only the tests relevant to the situation. Each test is a yes/no question with a consequence. Name the test by number in your response so the user can follow your reasoning.

### Test 1 — Atomic responsibility

> Does this have one logical responsibility, even if it takes multiple steps?

Atomic ≠ one step. Multi-phase skills are normal *when all phases serve one responsibility*. The real test:

> If you split it, do the pieces share state — objectives, history, intermediate artifacts — that would be painful to pass between separate skill invocations?

- Shared state → keep it together.
- No shared state → split candidate.

### Test 2 — Trigger timing

> Do all the parts fire on the same user intent?

A skill is invoked by description-matching. If parts fire on different intents ("draft a PRD" vs "review a PRD"), they want separate descriptions — and separate skills.

### Test 3 — Overlap with existing

> Does an existing skill already cover this responsibility, or part of it?

New skills cost description tokens in every session, forever. Default to extending an existing skill unless:

- The responsibility is genuinely distinct.
- Trigger phrases don't overlap with the existing skill (forced ambiguity is a tax on Claude's trigger choice).
- The existing skill's body would have to grow substantially to absorb the new work.

### Test 4 — Scope drift in an existing skill

> Has an existing skill grown past one responsibility?

Symptoms:
- Multiple unrelated trigger-phrase clusters in the description.
- Body sections that don't reference each other.
- Two natural names you could give the skill.

If yes → `SPLIT`.

### Test 5 — Duplicate responsibility across skills

> Do two skills serve the same responsibility from different angles?

Symptoms:
- Overlapping trigger phrases that confuse trigger choice.
- Users invoke them interchangeably.
- Both bodies repeat the same domain content.

If yes → `MERGE`. **But** distinct trigger phrases usually signal distinct intents — leave them alone unless the overlap is clear.

---

## Phase 3 — State the verdict

Pick exactly one:

| Verdict | Fires when |
|---|---|
| **`NEW`** | Tests 1–3 pass; responsibility is distinct from anything existing. |
| **`EXTEND`** | Test 3 fires; the work fits inside an existing skill. |
| **`SPLIT`** | Test 4 fires; an existing skill has drifted past one responsibility. |
| **`MERGE`** | Test 5 fires; two existing skills cover the same responsibility. |

State the verdict explicitly, in this format:

> **Verdict: `<NEW | EXTEND | SPLIT | MERGE>`**
> Responsibility: `<one sentence>`
> Name(s): `<proposed-name>` or `<target-skill-to-modify>`
> Reasoning: tests `<numbers>` fired.

If you can't pick exactly one verdict, that's the signal. Surface to the user and don't hand off — the scope question isn't settled yet.

---

## Phase 4 — Hand off

| Verdict | Handoff |
|---|---|
| `NEW` | Invoke `skill-creator` with the verdict block. Scope is done; let it build. |
| `EXTEND` | Name the target skill and the proposed addition. Hand off to `skill-creator`'s update path. |
| `SPLIT` | Produce a one-line responsibility statement for each resulting skill *before* any restructuring. Hand off one skill at a time. |
| `MERGE` | Produce a single responsibility statement for the merged skill and a list of trigger phrases to consolidate. Hand off as an `EXTEND` of the surviving skill, plus a delete of the other. |

---

## Anti-patterns

- **One step per skill.** Atomic means responsibility, not step count. Multi-phase skills are normal.
- **Splitting prematurely.** If the pieces share state, keep them together. Awkward state-passing between skills is worse than a longer skill.
- **Forking when extending would do.** New skills cost description tokens in every session, forever; extensions are cheap.
- **Merging for tidiness.** Distinct trigger phrases usually serve distinct user intents — leave them alone unless overlap is concrete.
- **Re-litigating settled scope.** If the user has stated the verdict, Phase 1 exits. Don't run tests for show.
- **Hedged verdicts.** "Probably a new skill, maybe an extension" is not a verdict — surface the ambiguity to the user instead.