crew-skill git:20260926.d19d454A

Immutable. This exact content never changes and is served at /api/v1/blob/df723daa14e4105d.

---
name: crew-skill
description: Author or change a Crewforth component (skill / agent / command) against the template and its gates.
disable-model-invocation: true
metadata:
  kind: command
---
# /crew-skill

`AGENT_TEMPLATE.md` states the contract for a component. Full installs carry it (refreshed on `update`); the
plugin edition does not. No gate routes to it, so this command is the route, and it ends in the gates.

**A component is not finished when it is written. It is finished when the suite says so.**

## 1. Decide the shape before writing anything
Read `.claude/AGENT_TEMPLATE.md`. Then answer, in one line each:

- **What is the smallest form that works?** A rule in an existing skill's body beats a new skill; a new skill beats
  a new agent. Every new skill costs its NAME in every session, forever, for every user — and its description too,
  until the listing overflows its budget, at which point descriptions start being dropped from the skills you
  invoke least. Say what that buys.
- **Who reaches it?** An agent, a command, or the discipline's trigger map. If the answer is "the model will notice
  the description", stop — that is the dark component §3b exists to catch.
- **Read or write?** A component that reports and a component that changes files do not belong together: different
  risk, different done-criterion. Split them.
- **Is it stack-neutral?** Anything shipped to every profile names no language, framework or vendor as *the* case.
  The example you have in mind is not the scope.

## 2. Write it
- Skill: `.claude/skills/<name>/SKILL.md` — the directory name and the `name:` field must match. Keep the body
  lean; depth goes to `references/*.md` and is loaded on demand.
- Agent: a thin trigger — *who and when*. The *how* lives in the skill it applies; do not copy the method in.
- The `description` says **when to reach for this**, not what its author knows.

## 3. Register it — the cascade, in this order
Skipping one of these is how a component ships half-installed:
1. **Route it.** Name it in an agent body, a command, or the trigger map. §3b checks exactly this.
2. **Golden case.** Add a positive line to `.claude/eval/golden-routing.txt` — and a **negative** one
   (`prompt|!target`) for a neighbour it must NOT steal.
3. **Catalog + counts** *(Crewforth repository only — `packaging/` is not installed anywhere)*.
   Add the Turkish summary line (`packaging/skill-summaries.tr.tsv`; agents and commands have their own `.tr.tsv`),
   which the site build requires (`cd site && npm ci && npm run build`), and the diagrams if the component set changed:
   `node packaging/gen-diagrams.mjs` writes `assets/`, and smoke fails while any of them is stale.
4. **Plugin edition** *(Crewforth repository only)*. `bash packaging/build-plugin.sh` — in the same commit, or the
   release stops at the sync gate.
5. **Budget.** A new skill moves `BUDGET_SKILLS`; raise it in the same commit with the justification comment the
   file's convention requires. Never raise it to make a red gate green without saying why.

## 4. Prove it — run all four, in this order
```
bash .claude/eval/scan-skill.sh .claude/skills/<name>    # supply-chain: SAFE, and rc=3 means NOT scanned
bash .claude/eval/routing-eval.sh                        # the golden case, positive and negative
bash .claude/eval/smoke-test.sh                          # structure, budget, §3b routed, cross-links
CREW_NO_STAR=1 bash .claude/eval/doctor.sh               # the live install still healthy (star line off here)
```

In the plugin edition none of the four commands above exist — it ships no `eval/` at all — so there the proof is
the Crewforth repository's own suite, not a local run.

**Do not finish while §3b is red.** "It works when I invoke it by name" is not the claim being tested — the claim
is that something reaches it without being told to. If the suite skips a case, that is not a pass: chase why.