Skill Authoring
Create, change, and keep skills healthy. The catalog is code: every edit runs
the same checks.
Contract
name == directory name, lowercase-hyphen.
description: third person, what + when, one narrow load condition;
<= 1024 chars; never a summary of the workflow.
- Body < 500 lines; move long checklists to
references/.
- Never hand-edit generated skills (
openspec-*, any generatedBy: in
metadata): the CLI overwrites them on the next update.
- One skill = one intent. Do not add a near-duplicate; extend or reference.
Workflow
- Before adding: search the catalog (
rg -l "<term>" skills/), read the
routing cases (skills-janitor/evals/routing.json), and prefer editing an
existing skill. Justify a new skill in one sentence.
- Write or edit
SKILL.md. Keep the sections: Overview, When to Use,
Process, Common Rationalizations, Red Flags, Verification.
- Run the checks yourself (never ask the user to run them):
bash skills-janitor/scripts/lint.sh — frontmatter, links, size.
python3 skills-janitor/scripts/route_evals.py — rank-1/top-3, negative
violations, cross-family collisions; --strict to gate.
python3 skills-janitor/scripts/skill_usage.py --exclude-probe — real
loads, zero-skill sessions, cost by model, tool error rates.
bash skills-janitor/scripts/tokencost.sh — always-loaded description
cost and body size.
- If the description or triggers changed: add/update cases in
skills-janitor/evals/routing.json (>= 3 positive, >= 2 negative with
owner) and run route_live.py --skills <name> --reps 3. Live firing is
stochastic; 1 run is a signal, 3+ is a rate.
- Fix the description, not the prompt. Cross-family similarity >= 0.75 is
an error; >= 0.50 warns. Same-family overlap (
openspec-*, ponytail-*) is
expected.
- Report the numbers — rank-1 before/after, collisions, usage — with the
diff. A skill edit without a fresh run is not done.
When a skill does not fire
- The description lacks the words users say. Add the situation, including
"even when the input is pasted inline and the answer looks obvious".
- Measure the real router, not only the lexical ranker:
route_live.py --skills <name> --reps 3.
- A process-shaped request fires more reliably than a one-shot request; that is
a model property, not a description bug. Say so instead of padding.
Pruning and consolidation
- Zero measured loads is not enough to delete a safety net (debugging,
verification, review). Judge expected value, not count.
- Merge families that share a prefix and overlap: one skill with modes, the
commands as entry points.
- Delete only with explicit user approval. When asked to disable without
removing, rename
SKILL.md to SKILL.md.disabled — the directory stays.
- Body size only costs when loaded; description size costs every request.
Mining sessions
skill_usage.py shows zero-skill sessions and never-loaded skills. A recurring
task with no skill is a candidate for a new skill; a skill with zero loads and a
large body is a candidate for removal. omp stats --json gives cost, tokens and
cache rate per model.
Verification
1---2name: skill-authoring3description: Use when creating, editing, renaming, deleting, or adding a skill; when a skill stops firing or its description changes; when auditing skill health, routing, or token cost. Runs the catalog checks itself — never asks the user to run scripts.4metadata:5 source: https://skillmd.com/skills/existencialistap/skill-authoring6---78# Skill Authoring910Create, change, and keep skills healthy. The catalog is code: every edit runs11the same checks.1213## Contract1415- `name` == directory name, lowercase-hyphen.16- `description`: third person, what + when, **one narrow load condition**;17 <= 1024 chars; never a summary of the workflow.18- Body < 500 lines; move long checklists to `references/`.19- Never hand-edit generated skills (`openspec-*`, any `generatedBy:` in20 metadata): the CLI overwrites them on the next update.21- One skill = one intent. Do not add a near-duplicate; extend or reference.2223## Workflow24251. **Before adding:** search the catalog (`rg -l "<term>" skills/`), read the26 routing cases (`skills-janitor/evals/routing.json`), and prefer editing an27 existing skill. Justify a new skill in one sentence.282. **Write or edit** `SKILL.md`. Keep the sections: Overview, When to Use,29 Process, Common Rationalizations, Red Flags, Verification.303. **Run the checks yourself** (never ask the user to run them):31 - `bash skills-janitor/scripts/lint.sh` — frontmatter, links, size.32 - `python3 skills-janitor/scripts/route_evals.py` — rank-1/top-3, negative33 violations, cross-family collisions; `--strict` to gate.34 - `python3 skills-janitor/scripts/skill_usage.py --exclude-probe` — real35 loads, zero-skill sessions, cost by model, tool error rates.36 - `bash skills-janitor/scripts/tokencost.sh` — always-loaded description37 cost and body size.384. **If the description or triggers changed:** add/update cases in39 `skills-janitor/evals/routing.json` (>= 3 positive, >= 2 negative with40 `owner`) and run `route_live.py --skills <name> --reps 3`. Live firing is41 stochastic; 1 run is a signal, 3+ is a rate.425. **Fix the description, not the prompt.** Cross-family similarity >= 0.75 is43 an error; >= 0.50 warns. Same-family overlap (`openspec-*`, `ponytail-*`) is44 expected.456. **Report the numbers** — rank-1 before/after, collisions, usage — with the46 diff. A skill edit without a fresh run is not done.4748## When a skill does not fire4950- The description lacks the words users say. Add the situation, including51 "even when the input is pasted inline and the answer looks obvious".52- Measure the real router, not only the lexical ranker:53 `route_live.py --skills <name> --reps 3`.54- A process-shaped request fires more reliably than a one-shot request; that is55 a model property, not a description bug. Say so instead of padding.5657## Pruning and consolidation5859- Zero measured loads is **not** enough to delete a safety net (debugging,60 verification, review). Judge expected value, not count.61- Merge families that share a prefix and overlap: one skill with modes, the62 commands as entry points.63- Delete only with explicit user approval. When asked to disable without64 removing, rename `SKILL.md` to `SKILL.md.disabled` — the directory stays.65- Body size only costs when loaded; description size costs every request.6667## Mining sessions6869`skill_usage.py` shows zero-skill sessions and never-loaded skills. A recurring70task with no skill is a candidate for a new skill; a skill with zero loads and a71large body is a candidate for removal. `omp stats --json` gives cost, tokens and72cache rate per model.7374## Verification7576- [ ] `lint.sh` reports no new critical/warning for this skill.77- [ ] `route_evals.py` shows no new negative violation and no collision >= 0.75.78- [ ] Cases updated when the description changed; live check run with `--reps 3`.79- [ ] Body under 500 lines; every `references/` link resolves.