/create-skill

name: create-skill
description: "Author a new Dex skill — a reusable `/command` — that actually fires and passes the quality bar. Runs a collision check, classifies the shape, writes a router-grade description, generates the real package (SKILL.md + evals), and grades it with `skill-score` before calling it done. Use when the user says 'make a skill', 'I want a /command for X', 'turn this into a skill'. A skill the user builds for themselves is saved as `-custom` (protected from updates) and coached, never blocked; a first-party skill is held to the hard gate. Not for connecting an external tool; use `create-mcp`. Not for grading a skill that already exists; use `skill-score`."

Create a Skill

Author a skill the way the router and a real user will experience it: it must **fire when it should** (the description is the router) and **do the job safely and well when it fires** (the body is a contract, not a how-to essay). This skill runs a real authoring sequence — collision → classify → contract → generate → validate → score — and does not declare done until `skill-score` has graded the package.

Governing principle: **hard on Core, gentle on the user's own creations.** A first-party (Core) skill must pass `skill-score ≥ 85` to ship — a hard gate we hold ourselves to. A skill the user writes for themselves is *coached, never blocked*: show the score, name the one change that would make it fire, offer to make it — but always create/keep their skill if they want it.

Compose, don't fork: `anthropic-skill-creator` (vendored) is the general skill-authoring guide; the Dex-specific delta lives in `references/dex-skill-standard.md`. Read that reference before generating the package.

---

Step 1 — Get intent

Ask the user for:

1. A short name (e.g. "meeting-notes", "board-update") — hyphens, no spaces
2. What it should do for you, in 1–2 sentences
3. When you'd want it to fire — the phrases you'd actually say

Point 3 is not optional — it is the raw material for the WHEN trigger. If the user only gives 1–2, ask for the trigger phrases before continuing.

Step 2 — Determine origin

• **User skill** (the default in an end-user vault): the user is building this for themselves. It is authored under `{name}-custom/` and is **coached, never blocked**. Do NOT let the user add `-custom` themselves — you append it automatically.
• **First-party / Core skill** (authoring inside the Dex repo, to ship to everyone): authored under its real `{name}/` and **held to the hard gate** (`skill-score ≥ 85`).

Infer from context; if genuinely unsure, ask one line: "Is this just for you, or something Dex should ship to everyone?"

Step 3 — Collision check (before writing anything)

The most common failure is a skill the router can't tell apart from one that already exists. Check first — run `skill-score --all` (its portfolio mode lists every routing collision and the nearest neighbor of each skill; it owns and runs the scorer, so you don't re-implement it here).

Read the `routing collisions` list and find the nearest neighbor to the intended job. Then decide:

• **This is a genuinely new job** → note the nearest neighbor; its name goes in the anti-trigger (Step 5).
• **A skill with this exact job already exists** → do NOT create a duplicate. Either **edit that skill in place** (overwrite its `SKILL.md`, keep its name — never a `-name-2` or `-v2` fork) or, if it's a Core skill the user wants to customize, save the user's version as `{name}-custom` alongside it (both stay invocable) and hand off to the conflict-resolution flow. A suffixed fork of a job that already exists fragments discoverability and is not allowed.
• **A near neighbor exists but the jobs are distinct** → sharpen this skill's outcome and add an anti-trigger naming that neighbor so the router can disambiguate.

If the scorer can't run (no `python3`), fall back to reading the descriptions in `.claude/skills/*/SKILL.md` by hand and say you did so — never skip the collision check silently.

Step 4 — Classify the shape

Pick the shape(s) — a skill can be more than one — because it decides the contract the body must carry (see `references/dex-skill-standard.md`):

• **workflow** — a multi-step process over the vault
• **setup / integration** — connects a tool; must be idempotent + carry a re-run/repair path
• **dependent** — needs a tool/feature; must detect → explain → fix-path when it's missing
• **generative** — produces user-facing content; must name a quality bar + anti-slop rules + inspect real output before claiming success
• **script-bearing** — ships a script; the script needs a `--diagnose`/`--dry-run` and machine-readable output
• **multi-session / stateful** — state kept in a file and sized to a single session

Step 5 — Write the description (the router)

This is the highest-leverage line in the whole package. Follow the template in `references/dex-skill-standard.md`. It must:

1. **Lead with the outcome** in plain language — what the user gets, no internal function/file names. 2. **Carry a WHEN trigger** — concrete situations AND the user phrases from Step 1 ("Use when the user says…"). 3. **Carry an anti-trigger** — "Not for X; use Y" naming the real nearest neighbor from Step 3.

Step 6 — Generate the package

Create the folder — `{name}-custom/` for a user skill, `{name}/` for a first-party skill — and write:

• **`SKILL.md`** — the description from Step 5 + a **thin body**: a router + contract, not a reference essay. Name the quality bar and at least one anti-pattern. Push long procedural detail into `references/`. Soft cap ~200 lines.
• **`evals/trigger-cases.yaml`** — the standard fixture every skill carries: 3 positive paraphrases (must fire), 2 negative/collision (must route to the named neighbor), 1 ambiguous (ask), 1 missing-prerequisite (degrade honestly), 1 failure-recovery (never claim false success). Copy the shape from `.claude/skills/skill-score/evals/trigger-cases.yaml`.
• Optional `reference