Skill writing - a trigger that fires, a body that changes the run, proof on both sides
A skill is judgment loaded on demand: the model sees its description on every turn and reads its
body only once the description says the moment has come. So a skill earns its place twice - a
description that fires on the right requests and stays quiet on the rest, and a body that makes the
run do what it would have got wrong without it. Miss the first and the body never loads; miss the
second and every session pays for a description that changes nothing.
When to use
- Fires for writing, changing or reviewing a skill - its SKILL.md, description or frontmatter, or a file under its references/ folder - when a skill does not fire, fires on the wrong request or is ignored after it loads, or when deciding whether a piece of guidance belongs in a skill at all rather than a rule, a hook or a reference.
- The skill-authoring method, from the trigger to the proof that the skill changes a run.
- This repo's own skill since 2026-10-22, beside
plugin-authoring: it serves authoring the stack, so no install carries it.
- Not for a plugin's manifest or marketplace entry, which
plugin-authoring covers, or a project's AGENTS.md, which its instruction-file tooling owns.
Is it a skill at all
Pick the home before writing a word:
- A check a script can decide (a file present, a pattern in a diff, an exit code) - a hook or a
lint. The model may skip prose; nobody skips a gate.
- A convention tied to a file type - a path-scoped rule whose one job is to load the skill that
holds the convention, attached when a matching file is touched.
- Something every session needs from its first message - an always-on rule, its size charged to
every message of every session.
- A long lookup one step consults (an API table, a catalog of error signatures) - a file under
the skill's
references/, named at the step that reads it.
- A judgment call keyed to a situation - a skill.
- How one bug was fixed once, or a fact about one project - no skill: the project's docs or its
memory.
The description is the trigger
The body stays unread until the description earns the load, and the description is paid for on
every message whether it fires or not.
- At most 160 characters, on one line - an appended
when_to_use counts with it, so add none.
Why: where the harness is Claude Code, every model-invocable skill's description shares ONE listing
budget that scales with the context window, and past it the least-used skills lose their whole
description, trigger words included, and keep only their name (/doctor shows the cost). The
budget and the per-entry cap are version-coupled: read them at use from
https://code.claude.com/docs/en/skills, never from memory.
- Lead with the trigger -
Use when / Load when, or Use before / Load before for a gate that
must run before an act - then the situation in the words a request or a file would carry: the
strongest 3-6 of the file types, tool names, error text and phrases a user actually types. A
synonym that adds no new match is dropped.
- One short
Not for boundary, and only where it stops a real mis-fire - a neighbour sharing the
triggers - naming where that request goes instead.
- Everything else - examples, version floors, the 'Covers ...' list, companions, the rest of the
negative scope - goes into a
## When to use section of the body, before its first heading, and
never repeats the description word for word.
- List what it covers as keywords, never its steps in order: a description that retells the
procedure gets obeyed in place of the body, and whatever it left out is skipped.
- Third person throughout.
- A skill that needs the user to name it before it loads has a broken description - repair the
description, not the body.
- Where the harness is Claude Code (version-coupled, so re-check the page above before leaning on it):
name is optional and defaults to the folder name;
disable-model-invocation: true makes the skill the user's to type: its description leaves the
model's context, and no subagent can preload it;
user-invocable: false hides it from the slash menu while its description stays in context -
background knowledge only the model loads.
One home per piece
- Every rule, step and fact lives in one file; anything else that needs it points there. A second
copy drifts, and within a release the two disagree. Across skills, a rule two skills both need is
copied into each and the copies kept in sync - a pointer into another skill's folder breaks
wherever that skill is not installed.
- Name another skill only where it is guaranteed to sit beside the citer - preloaded by the same
seat, shipped in the same package, or part of the always-installed set. Anywhere else, describe
what it covers ('the skill covering the ORM, where the project has one'), so an absent skill costs
nothing and a present one is still found.
- Point with a load directive at the step that needs the other skill, never a 'see also' list at the
end.
The body
Lean: every line is paid for when the skill loads. Write for a capable model - state the decision
it would get wrong, never what it already knows.
Steps that must happen in order are numbered and imperative; the rest is bullets.
Platform-neutral: no tool, path or command of one harness as the only way. Where harnesses differ,
a condition says which branch applies ('inline when no dispatch is available').
Detail that one step needs goes under references/, directly beneath the skill folder, read when
that step names it. A reference longer than about a hundred lines opens with its own contents list.
Choose the shape by the failure you saw:
- skipped under pressure though the model knew better - a hard rule, the excuses it answers, and
the signs it was skipped;
- the right action with output in the wrong shape - a recipe that lays that shape out part by
part, instead of a list of don'ts;
- a required part left out - a slot for it in the template being filled;
- behavior that hinges on a condition - the condition, stated as something the run can observe.
A real exception gets a condition of its own; a hedge tacked on the end ('unless it matters') puts
the whole rule back up for negotiation.
One worked example in the project's own language beats several, and none is lifted from the
session that wrote the skill.
A script the skill runs is started through its interpreter (node tool.js), never as a bare
path - an executable bit does not survive every packager.
Prove it before shipping
A skill is code the model runs, so its test comes first and is seen to fail - the
test-first loop for code, applied to prose:
- Baseline WITHOUT the skill. Give a fresh context a realistic task that invites the failure,
and record what it did and the reasons it gave. No failure seen means nothing to write - stop.
- Write the least that answers those failures - nothing for a case the baseline never showed.
- The same task WITH it. The failure is gone, and nothing else got worse.
- The adverse phrasing. The same task plus pressure against the discipline - a deadline, 'just
do it', work already sunk - and no explicit waiver. The discipline holds.
- The plain phrasing. The task in the user's words, the skill unnamed. The description fires
on its own.
- A new excuse seen in any run is answered in the body, and the runs go again. One sample per
arm proves little: run several, and read every hit a grader counts before trusting its number.
A lookup skill (a catalog, a reference table) has no discipline to hold: it is proven by retrieval -
the plain phrasing finds the right entry, and the run uses it correctly - and pressure applies only
to a discipline.
Where the project keeps a step grader - fixtures replayed at explicit, plain and adverse prompt
levels, a before arm compared with an after arm (a skill-comply harness) - add the new skill's steps
to it, and ship only when the after arm is no worse on any step. A replay through a nested session
is billed: ONE AskUserQuestion first, the unbilled route recommended (a dry run that prints the
commands, or a grade of a transcript already on disk).
An edit to an existing skill is proven the same way. A change nobody saw alter a run is not known
to help.
Signs it was skipped
- A skill shipped with no run seen failing without it.
- A description that retells the steps, runs past 160 characters, or opens on anything but its trigger.
- The same rule restated in a second file with nothing keeping the copies in sync.
- A skill named by a citer it is not guaranteed beside.
- A table in the body that only one step reads.
1---2name: skill-authoring3description: "Use when writing, changing or reviewing a skill or its description - or when one does not fire. Not for a plugin manifest, which plugin-authoring owns."4metadata:5 source: https://skillmd.com/skills/envoydev/skill-authoring6---78# Skill writing - a trigger that fires, a body that changes the run, proof on both sides910A skill is judgment loaded on demand: the model sees its description on every turn and reads its11body only once the description says the moment has come. So a skill earns its place twice - a12description that fires on the right requests and stays quiet on the rest, and a body that makes the13run do what it would have got wrong without it. Miss the first and the body never loads; miss the14second and every session pays for a description that changes nothing.1516## When to use1718- Fires for writing, changing or reviewing a skill - its SKILL.md, description or frontmatter, or a file under its references/ folder - when a skill does not fire, fires on the wrong request or is ignored after it loads, or when deciding whether a piece of guidance belongs in a skill at all rather than a rule, a hook or a reference.19- The skill-authoring method, from the trigger to the proof that the skill changes a run.20- This repo's own skill since 2026-10-22, beside `plugin-authoring`: it serves authoring the stack, so no install carries it.21- Not for a plugin's manifest or marketplace entry, which `plugin-authoring` covers, or a project's AGENTS.md, which its instruction-file tooling owns.2223## Is it a skill at all2425Pick the home before writing a word:2627- **A check a script can decide** (a file present, a pattern in a diff, an exit code) - a hook or a28 lint. The model may skip prose; nobody skips a gate.29- **A convention tied to a file type** - a path-scoped rule whose one job is to load the skill that30 holds the convention, attached when a matching file is touched.31- **Something every session needs from its first message** - an always-on rule, its size charged to32 every message of every session.33- **A long lookup one step consults** (an API table, a catalog of error signatures) - a file under34 the skill's `references/`, named at the step that reads it.35- **A judgment call keyed to a situation** - a skill.36- **How one bug was fixed once, or a fact about one project** - no skill: the project's docs or its37 memory.3839## The description is the trigger4041The body stays unread until the description earns the load, and the description is paid for on42every message whether it fires or not.4344- **At most 160 characters, on one line** - an appended `when_to_use` counts with it, so add none.45 Why: where the harness is Claude Code, every model-invocable skill's description shares ONE listing46 budget that scales with the context window, and past it the least-used skills lose their whole47 description, trigger words included, and keep only their name (`/doctor` shows the cost). The48 budget and the per-entry cap are version-coupled: read them at use from49 <https://code.claude.com/docs/en/skills>, never from memory.50- Lead with the trigger - `Use when` / `Load when`, or `Use before` / `Load before` for a gate that51 must run before an act - then the situation in the words a request or a file would carry: the52 strongest 3-6 of the file types, tool names, error text and phrases a user actually types. A53 synonym that adds no new match is dropped.54- One short `Not for` boundary, and only where it stops a real mis-fire - a neighbour sharing the55 triggers - naming where that request goes instead.56- Everything else - examples, version floors, the 'Covers ...' list, companions, the rest of the57 negative scope - goes into a `## When to use` section of the body, before its first heading, and58 never repeats the description word for word.59- List what it covers as keywords, never its steps in order: a description that retells the60 procedure gets obeyed in place of the body, and whatever it left out is skipped.61- Third person throughout.62- A skill that needs the user to name it before it loads has a broken description - repair the63 description, not the body.64- Where the harness is Claude Code (version-coupled, so re-check the page above before leaning on it):65 - `name` is optional and defaults to the folder name;66 - `disable-model-invocation: true` makes the skill the user's to type: its description leaves the67 model's context, and no subagent can preload it;68 - `user-invocable: false` hides it from the slash menu while its description stays in context -69 background knowledge only the model loads.7071## One home per piece7273- Every rule, step and fact lives in one file; anything else that needs it points there. A second74 copy drifts, and within a release the two disagree. Across skills, a rule two skills both need is75 copied into each and the copies kept in sync - a pointer into another skill's folder breaks76 wherever that skill is not installed.77- Name another skill only where it is guaranteed to sit beside the citer - preloaded by the same78 seat, shipped in the same package, or part of the always-installed set. Anywhere else, describe79 what it covers ('the skill covering the ORM, where the project has one'), so an absent skill costs80 nothing and a present one is still found.81- Point with a load directive at the step that needs the other skill, never a 'see also' list at the82 end.8384## The body8586- Lean: every line is paid for when the skill loads. Write for a capable model - state the decision87 it would get wrong, never what it already knows.88- Steps that must happen in order are numbered and imperative; the rest is bullets.89- Platform-neutral: no tool, path or command of one harness as the only way. Where harnesses differ,90 a condition says which branch applies ('inline when no dispatch is available').91- Detail that one step needs goes under `references/`, directly beneath the skill folder, read when92 that step names it. A reference longer than about a hundred lines opens with its own contents list.93- Choose the shape by the failure you saw:94 - skipped under pressure though the model knew better - a hard rule, the excuses it answers, and95 the signs it was skipped;96 - the right action with output in the wrong shape - a recipe that lays that shape out part by97 part, instead of a list of don'ts;98 - a required part left out - a slot for it in the template being filled;99 - behavior that hinges on a condition - the condition, stated as something the run can observe.100101 A real exception gets a condition of its own; a hedge tacked on the end ('unless it matters') puts102 the whole rule back up for negotiation.103- One worked example in the project's own language beats several, and none is lifted from the104 session that wrote the skill.105- A script the skill runs is started through its interpreter (`node tool.js`), never as a bare106 path - an executable bit does not survive every packager.107108## Prove it before shipping109110A skill is code the model runs, so its test comes first and is seen to fail - the111test-first loop for code, applied to prose:1121131. **Baseline WITHOUT the skill.** Give a fresh context a realistic task that invites the failure,114 and record what it did and the reasons it gave. No failure seen means nothing to write - stop.1152. **Write the least that answers those failures** - nothing for a case the baseline never showed.1163. **The same task WITH it.** The failure is gone, and nothing else got worse.1174. **The adverse phrasing.** The same task plus pressure against the discipline - a deadline, 'just118 do it', work already sunk - and no explicit waiver. The discipline holds.1195. **The plain phrasing.** The task in the user's words, the skill unnamed. The description fires120 on its own.1216. **A new excuse** seen in any run is answered in the body, and the runs go again. One sample per122 arm proves little: run several, and read every hit a grader counts before trusting its number.123124A lookup skill (a catalog, a reference table) has no discipline to hold: it is proven by retrieval -125the plain phrasing finds the right entry, and the run uses it correctly - and pressure applies only126to a discipline.127128Where the project keeps a step grader - fixtures replayed at explicit, plain and adverse prompt129levels, a before arm compared with an after arm (a skill-comply harness) - add the new skill's steps130to it, and ship only when the after arm is no worse on any step. A replay through a nested session131is billed: ONE AskUserQuestion first, the unbilled route recommended (a dry run that prints the132commands, or a grade of a transcript already on disk).133134An edit to an existing skill is proven the same way. A change nobody saw alter a run is not known135to help.136137## Signs it was skipped138139- A skill shipped with no run seen failing without it.140- A description that retells the steps, runs past 160 characters, or opens on anything but its trigger.141- The same rule restated in a second file with nothing keeping the copies in sync.142- A skill named by a citer it is not guaranteed beside.143- A table in the body that only one step reads.