Commands

---
name: write-skill
description: Author a new skill from scratch with paired trigger fixtures and full validation. Use when adding a skill that has no upstream skills.sh source (discipline, meta, or internal-pattern skills).
argument-hint: "<skill-name>  (e.g. ia-foo)"
---

# Write Skill

**Skill name:** `$ARGUMENTS`

Scaffold a new plugin skill from scratch, generate paired trigger fixtures, register the regex pattern, and run all gates. For distilling a skill from skills.sh sources, use the `skill-distiller` skill instead — `/write-skill` is for skills with no external upstream.

## Phase 1: Resolve target

1. If `$ARGUMENTS` is empty or doesn't start with `ia-`, ask for the skill name.
2. Validate format: must match `^ia-[a-z0-9][a-z0-9-]*$`, no consecutive hyphens, no banned tokens (`anthropic`, `claude`).
3. Confirm the skill doesn't already exist:
   - `plugins/whetstone/skills/<name>/SKILL.md` must NOT exist.
   - `distillery/tests/fixtures/triggers/<name>.jsonl` must NOT exist.
   - No matching `SKILL_PATTERNS[<name>]=` line in `plugins/whetstone/hooks/skill-patterns.sh`.
4. Read `CLAUDE.md` "Skill compliance checklist" section to refresh the gates this skill must pass.

## Phase 2: Batch up-front interview

Use `AskUserQuestion` once to collect everything needed before scaffolding. Do not drip-feed questions across turns.

Ask:

1. **Class** — one of the five values from `CLAUDE.md` "Skill class taxonomy": `language`, `discipline`, `workflow`, `meta`, `tool`. Read that section before asking so the option descriptions match what the validator will accept.
2. **Scope summary** — one or two sentences: what this skill is for, when it fires.
3. **Primary trigger vocabulary** — 3-6 distinctive phrases users would type.
4. **Existing skills it should not overlap with** — names of any close-in-scope `ia-*` skills the user already has in mind.

## Phase 3: Inspect prior art

Read the SKILL.md of every skill the user named in question 4 (and any others that look similar by class). Goals:

- Match house style (frontmatter shape, body voice, references/ patterns).
- Identify trigger overlap risk — `validate-plugin` will flag descriptions with >70% word overlap.
- Find a close structural template to model the new skill after.

## Phase 4: Scaffold

Generate four artifacts atomically. Do not split across phases.

### 4a. SKILL.md

Path: `plugins/whetstone/skills/<name>/SKILL.md`

Frontmatter rules (all hard requirements — `validate-plugin` enforces them):

- `name:` matches the directory name exactly.
- `class:` one of `language`, `discipline`, `workflow`, `meta`, `tool` (the value from question 1). Required. The validator rejects unknown values.
- `description:` describes **what + when**, not how. Lead with one sentence on what the skill does, then `Use when ...` with concrete trigger language. Stay under 80 tokens. No vague phrases (`comprehensive`, `best practices`, `robust`, `seamless`, `powerful` — see `_VAGUE_DESCRIPTION_PHRASES` in `distillery/scripts/distiller.py`). No second person, no provider names unless the skill is intentionally provider-specific.
- No inert fields (`triggers`, `role`, `scope`, `domain`, `version`, `tags` — they're ignored by Claude Code).

Body rules:

- Imperative voice (verb-first instructions).
- 100-2000 tokens ideal, 4000 hard cap. Split to `references/` if larger.
- No machine-specific paths (`/home/...`, `/Users/...`, `~/ai/...`, `C:\Users\...`). Use `<repo-root>` or `<skill-dir>` placeholders.
- No placeholder text (`TODO`, `FIXME`, `XXX`, `[YOUR ...]`).
- No MUST/ALWAYS/NEVER spam (>15 directives is flagged as OVER_CONSTRAINED).
- Hunt no-ops sentence by sentence, not just line by line: run the no-op test on each sentence in isolation, and when one fails (it restates the obvious, or the agent would behave identically without it), delete the whole sentence rather than trim words from it. Most prose that fails should go, not be reworded.
- Anchor a behavior in a single strong token where one exists (`tight`, `red`, `surgical`) instead of spelling the same instruction out three ways -- a well-chosen leading word carries the intent at lower token cost than a paragraph.
- If creating `references/`, link every file with `[name](./references/name.md)` syntax — orphans are flagged. Each reference under 150 lines (warning) and 800 lines (error).
- **Skill Independence**: do not instruct the agent to invoke another skill by name. Forms to avoid: `run the ia-X skill`, `use the \`ia-X\` skill`, `hand off to ia-X`, `<vendor>:Y` runtime references. Other skills may be missing, renamed, or user-overridden — name-invocation silently breaks in all three cases. Instead, state the intent directly (`If on \`main\`, create a feature branch first.`) and trust skill discovery to surface the right skill, or load a local file via `[name](./references/name.md)`. Naming an agent (Agent tool dispatch) or referencing a skill in non-runtime prose (provenance, audit allowlist) is fine.

### 4b. Trigger fixtures

Path: `distillery/tests/fixtures/triggers/<name>.jsonl`

JSONL format. **Required floors: 5 should_trigger AND 5 should_not_trigger** — `test-triggers` fails the run if either count is below floor.

```json
{"prompt": "<realistic phrasing a user would type>", "expect": true, "added_in": "<current-version>", "source": "initial"}
{"prompt": "<adjacent task that must NOT trigger this skill>", "expect": false, "added_in": "<current-version>", "source": "initial"}
```

Drafting guidance:

- Positives: 5+ phrasings that exercise different ways a user might invoke this skill. Vary verb, vary scope, include at least one terse phrasing.
- Negatives: 5+ phrasings that look superficially related but should not trigger. Include phrasings that match adjacent skills' descriptions (the `validate-plugin` DUPLICATE_TRIGGER detector catches this kind of overlap).
- Do not use AI-flavored placeholders. Each prompt should be a thing a real user would type.

Read the current plugin version from `plugins/whetstone/.claude-plugin/plugin.json` for the `added_in` field.

### 4c. SPEC.md (maintenance contract)

Path: `plugins/whetstone/skills/<name>/SPEC.md`

Seven required headings (the validator rejects missing ones as HIGH):

```markdown
# <name> Specification

## Intent
<one paragraph: what this skill exists for, primary purpose, class context>

## Scope
In scope:
- <bullets pulled from SKILL.md routing>
Out of scope:
- <adjacent skills that should not overlap>

## Trigger Context
- Class: <one of language, discipline, workflow, meta, tool>
- Hook regex: SKILL_PATTERNS[<name>]
- Common requests: <3 should_trigger samples>
- Should not trigger for: <3 should_not_trigger samples>

## Source And Evidence Model
<canonical sources, data-not-stored rules, coverage matrix>

## Evaluation
<lightweight + deeper command snippets, acceptance gates>

## Known Limitations
<placeholder; fill in over time as drift surfaces>

## Maintenance Notes
<when each artifact must be updated>
```

For an existing filled example to model after, read any `plugins/whetstone/skills/ia-*/SPEC.md`. To auto-generate a starter SPEC.md from the SKILL.md and fixture pair, run `python3 scripts/generate-spec.py` (it skips skills that already have SPEC.md, so it's safe to re-run).

File-relationship matrix — what each artifact owns (don't duplicate across files):

| File | Purpose |
|---|---|
| `SKILL.md` | Runtime activation and execution instructions loaded by agents. |
| `SPEC.md` | Maintenance contract for humans and agents improving the skill. |
| `SOURCES.md` | Source inventory, decisions, coverage matrix, gaps, changelog (optional). |
| `references/` | Runtime-loadable domain/process detail. |
| `references/evidence/` | Persistent positive/negative iteration examples. |

SPEC.md design rules (apply when filling the template):

1. Describe intent and maintenance contract; do not add runtime instructions that belong in SKILL.md.
2. Summarize source categories and link to SOURCES.md (if present) — do not duplicate full source tables.
3. Describe evidence classes and storage policy; keep raw examples in `references/evidence/`.
4. Include out-of-scope behavior and known limitations so future edits do not expand the skill accidentally.
5. Include evaluation expectations that explain what "good" means; link to runnable prompts rather than duplicating them.
6. Keep private or sensitive evidence redacted; store only what is needed to reproduce and improve behavior.

SPEC.md must not contain machine-specific paths, secrets, or unredacted personal data. The same `MACHINE_PATH_LEAK` gate that scans SKILL.md and references applies here.

### 4d. SOURCES.md (optional source-provenance ledger)

Path: `plugins/whetstone/skills/<name>/SOURCES.md`

Recommended for skills synthesized from external repos, marketplace skills, a mixed source pack, or any skill that accumulates persistent iteration evidence under `references/evidence/` — anything where future maintainers will need to know *what shaped this skill*. Skip for skills authored from scratch with no external source pack and no evidence ledger (the SPEC.md "Source And Evidence Model" section already covers them).

Three sections:

1. **Source inventory** — markdown table: `| Source | Type | Trust tier | Retrieved | Confidence | Contribution | Usage constraints | Notes |`. Trust tiers: `canonical` (official spec, repo CLAUDE.md, owner-blessed) > `secondary` (well-regarded blog post, prior-art pattern). Avoid scraping low-tier content.
2. **Decisions** — numbered list of synthesis decisions and the constraint that drove each (e.g., "Path guidance avoids host-specific absolutes because plugin is mirrored to ai-skills"). One line per decision.
3. **Changelog** — date-stamped entries for source additions, scope changes, or rule reversals.

Keep SOURCES.md ledger-style. Do not duplicate runtime content from SKILL.md or maintenance contract content from SPEC.md.

If iteration evidence (positive/negative examples, holdout set) accumulates, store it under `references/evidence/EX-NNN.md` instead of in SOURCES.md — see `/diagnose-negatives` for the schema.

### 4e. Hook regex pattern

Append to `plugins/whetstone/hooks/skill-patterns.sh`:

```bash
SKILL_PATTERNS[<name>]='<regex>'
SKILL_TIERS[<name>]=<1|2|3>
```

Tier guide: 1 = high precision / always-relevant (`debugging`, `code-review`); 2 = stack-specific (`tailwind`, `pinescript`); 3 = niche or workflow (`compound-docs`, `file-todos`).

Build the regex from the trigger vocabulary in question 3. Test it locally first:

```bash
python3 distillery/scripts/distiller.py eval-triggers <name> \
  --pattern '<regex>' \
  --queries '{"should_trigger":["..."],"should_not_trigger":["..."]}'
```

`--queries` takes a single JSON object with `should_trigger` and `should_not_trigger` arrays (there is no `--negatives` flag).

Iterate until F1 = 1.0 across the fixture set, then commit the pattern to `skill-patterns.sh`.

## Phase 5: Run all gates

Run these in order. Stop at the first failure and fix before continuing.

```bash
# 1. Plugin-wide validator scoped to the new component
#    (catches frontmatter, body size, overlap, dead refs, machine paths, ref bloat)
python3 distillery/scripts/distiller.py validate-plugin --component <name>

# 2. Trigger regression (enforces 5+5 floor and F1 = 1.0)
python3 distillery/scripts/distiller.py test-triggers --skill <name>

# 3. Re-run validate-plugin without --component to confirm no DUPLICATE_TRIGGER
#    or count-mismatch findings appear at the fleet level
python3 distillery/scripts/distiller.py validate-plugin
```

Do not run `generate-manifest.py`, `update-metadata.sh`, `mirror-to-ai-skills.sh`, or any release scripts — those are owned by `/release`. Running `generate-manifest.py` mid-work stamps the skill's hashes at the current (pre-bump) version, which makes ClawHub skip it at publish time; `/release` regenerates the manifest at the right moment.

## Phase 6: Report

Output four sections in this order:

1. **Summary** — one line on what was created (skill name, class, trigger pattern).
2. **Changes Made** — bulleted list of files created/modified with line counts.
3. **Validation Results** — verbatim output of each gate above (PASS/FAIL with metrics).
4. **Open Gaps** — anything the skill needs that this command did not cover (e.g., `references/` content, integration tests, semantic injection fixture in `distillery/tests/fixtures/semantic-triggers.jsonl`).

If validation surfaces fixable issues mid-flight (e.g., an overly-broad regex catching a negative case), fix and re-run rather than reporting failure. Reject completion if any HIGH-severity finding remains in `validate-plugin --component <name>` or if `test-triggers --skill <name>` fails.

Run `ia-verification-before-completion` before reporting done.

## Success criteria

- New skill directory exists with valid SKILL.md.
- Trigger fixture has at least 5 positives and 5 negatives, F1 = 1.0.
- Hook pattern registered and matches the fixture set.
- `validate-plugin --component <name>` returns no HIGH findings.
- No version bumps, README edits, CHANGELOG entries, or manifest regeneration (those belong to `/release`).