Skill Authoring

Skill Authoring

A skill competes for selection in a context window shared with every other installed tool. There are two ways to win: describe your territory precisely, or shout. Shouting works once — then every neighbor escalates, emphasis stops carrying information, and selection quality degrades for the whole toolkit. This doctrine is the first way, made enforceable.

This is a rigid skill: the description contract, register rules, and shipping requirement are bright lines, each with a mechanical check.

The description contract

The frontmatter description is a trigger surface. It has one job: let a model holding only descriptions rank this skill correctly against its neighbors — high when the task is the skill's, low when it is not.

1. Open with a verb-led capability sentence. What the skill does and produces, before any trigger list.
2. Quote the triggers users actually type. Concrete phrasings ("wrap up", "which tool should handle this"), task shapes, and situations — not abstract categories. Paraphrase variety beats repetition.
3. Draw the boundary, then name the owner. Every description ends with negative space: "Not for X — that is Y." Naming the sibling does two jobs: it stops the skill from poaching, and it routes the reader to the right place.
4. No obedience language. Descriptions never instruct the model to use them, never inflate stakes, never claim priority over neighbors. A description that needs to demand attention is compensating for triggers that fail to earn it.

A plain-scalar description must not contain : (colon + space): YAML reads it as a nested mapping, the frontmatter silently breaks, and the skill never loads — caught only by validate_plugins, not by anything as you write. Quote the whole scalar, use a > folded block, or replace the : with an em-dash. (evaluate-skill sees the same trap as an instant, total recall collapse.)

Selection and execution are different layers

The description decides when the skill loads. The body instructs how the work proceeds once loaded. Keep the registers separate:

• A bright line in a body is content, stated plainly: "production code is written only against a test you have watched fail." Firm, testable, neutral.
• Identity pressure is not content: "you are rationalizing", "you do not have a choice", all-caps banners. These bully the reader's judgment instead of informing it, and they read as noise to anyone auditing the skill.
• Catalogs of known failure modes and rationalizations are valuable — keep them as descriptive tables ("common shortcuts and what they miss"), so a reader recognizes the pattern without being accused of it.
• A step whose executor is not the reader says so. "Write each reviewer's output to disk as it lands" reads as something the operator does by hand; a reader building an automated panel implements the surrounding structure and drops the step, and the persisted evidence it existed to keep is gone. Name the executor where it is not obviously the reader.

Rigid or flexible — declare it

Every skill states which it is, near the top of the body:

• Rigid: bright-line constraints plus the verification step that proves compliance. For disciplines whose dominant failure mode is self-granted exceptions (TDD, verification before completion).
• Flexible: principles with judgment explicitly delegated — the skill says what to optimize for and trusts the reader to adapt.

The choice is part of the design, not the prose: a rigid skill with soft constraints fails differently from a flexible skill with hard constraints, and both fail.

Register rules

The deny-list: imperative-obedience phrases, importance banners, and runs of three or more consecutive all-caps words outside code — the patterns that buy salience instead of fit. Emphasis budget inside a body: bold the one load-bearing sentence of a section, sparingly. If a constraint feels like it needs caps to hold, it needs a verification step or a gate instead — move the enforcement to mechanism. Enforce what you can mechanically: craft-collection wires a register linter (scripts/lint_register.py) into pre-commit, but it catches only the detectable subset — importance banners, all-caps runs, and a fixed list of obedience/priority phrases. Obedience framing that dodges those literal patterns is not caught, so review holds the rest. A standalone install applies the whole deny-list by review until it wires its own gate.

Shipping requirement

A skill ships when all of these exist, not before:

1. Trigger dataset — balanced positives and negatives; the negatives include near-misses that sit in named siblings' territory.
2. Sealed holdout, with a birth baseline — authored at the same sitting as the dev set, never consulted while tuning the description, and run once at seal time with the result recorded next to the seal. A holdout that informed tuning is dev data, not a holdout; a holdout that has never been run is false confidence (one sat four days hiding a dev-0.95/holdout-0.33 overfit).
3. Correct-usage rubric (rigid skills) — tasks plus checks that the output actually followed the discipline, deterministic where possible.
4. Gates pass — recall, specificity, and correct-usage thresholds, run by a behavioral eval harness when one is available (craft-collection ships one: datasets under evals/trigger/, thresholds in evals/config.json, run mechanics owned by session-workflow's evaluate-skill). Standalone installs keep requirements 1–3 and 5 as authored artifacts and run them with whatever harness they have — the discipline is the contract, the harness is one implementation.
5. A registered threshold states what the design can detect — the maximum movement attainable at the planned repeat count, and its p, computed before the run. Without it a failed edit and a design incapable of succeeding leave the same record. Cannot reach the bar: raise repeats, or do not register it.

Two skill classes cannot be gated at trigger time at all, and one worked example of a threshold that could not move: references/shipping-gate.md, which also carries the measured record behind the register rules.

References between tools

Skills reference other tools without depending on them. Four rules and a test:

1. Same-plugin references are free — the plugin installs as a unit, so a sibling skill in the same plugin is guaranteed present. A different plugin is not, even one in the same marketplace: plugins install individually (/plugin install humblepowers@craft-collection), so a sibling plugin under the same marketplace is a cross-tool reference and rule 2 applies — role-generic, with a working fallback.
2. Cross-tool references are role-generic with a named example and a working fallback: "when a capacity-dispatch policy is installed (e.g. humblepowers' choosing-models), its tier rule wins — otherwise this heuristic." Name the role, give the example, work alone.
3. Artifacts never carry tool dependencies. A plan or spec that embeds "REQUIRED SUB-SKILL: " locks the artifact to a toolchain; state the execution contract in the artifact itself instead.
4. Bindings over assumptions — when integration genuinely needs wiring, the user supplies it (a bindings table, a config entry); tools never hunt the environment for each other.

The degradation test: uninstall every other tool — the skill still produces a correct, if less optimized, result.

Authoring checklist

• Verb-led capability sentence opens the description
• Concrete trigger phrasings, with paraphrase variety
• Negative space names every adjacent owner
• No obedience language anywhere in the description
• Rigid or flexible declared; bright lines plain; catalogs descriptive
• Register deny-list clean (lint-enforced where a gate is wired)
• Cross-tool references are role-generic with fallback (degradation test)
• Dev dataset and sealed holdout authored together, before any tuning; holdout baseline run and recorded at seal time
• Correct-usage rubric for rigid skills