skills/skill-authoring/references/triage-skills.md

# Triage skills

A triage skill owns one subject — a system, a failure family, a signature — and carries
the team's procedure for it.

How a caller finds and uses one is the platform's business and changes without notice.
This file is the part that is yours: what a skill needs when the caller is an agent
mid-incident rather than a person at a keyboard.

Read [format.md](format.md) and [what-works.md](what-works.md) first — they carry the
rules every skill follows. Nothing below repeats them; this is only the delta.

## Your name and description are the whole of selection

Nothing marks a skill as a triage skill. There is no field to declare and no file that
binds one to a moment: the frontmatter name and description are read against the
incident, and that is the entire decision.

- **Name the skill after what it owns.** The name is the quickest signal a caller has,
  and the first thing a person scanning your plugin understands, so spend it on the
  subject. `payments-ledger` or `checkout-queue-triage` says what it covers;
  `incident-triage` or `production-issues` says what everything covers.
- **The name that counts is the frontmatter `name`, not the directory.** format.md is
  right that the directory name is the skill's identity — usage history and allowlists
  key on it — but selection reads the frontmatter. A skill in `skills/twilio-triage/`
  whose frontmatter says `name: twilio` is chosen as `twilio`. Keep the two the same
  unless you have a reason not to.
- **The description has to back the name up.** It holds the veto: a fitting name over a
  vague description loses to a plain name over a sharp one. Apply format.md's
  description rules strictly — lead with the subject stated broadly, then the two or
  three signals only you match.
- **A subject can be a class of incident, not just a system.** Selection reads
  everything the incident carries, not only its error string — how it is classified,
  what its fields record, what it is called. A team that handles one class the same way
  every time can own that class: name it for the class and say so in the description.
- **Name the subject, however broad it is.** "Incident triage" or "production issues"
  names no subject at all, so there is nothing to match on. Saying which incidents to
  run on is fine even when the answer is all of them: a skill for working out which
  customers an incident affects, against your own tenancy model, applies to everything
  and still has a subject worth matching.
- **Use the words your organization uses.** Selection matches your name and description
  against what the incident actually carries. A skill named for a severity your
  organization does not use by that name, or for internal shorthand nothing records,
  matches nothing.

## Nobody is there to ask

The procedure runs once, unattended. There is no one to answer a follow-up, confirm a
guess, or pick between two branches.

- **Every branch is written down before it runs.** A step that ends in a decision needs
  the decision rule beside it.
- **State your entry conditions.** You may be reached with the failure already
  characterised, or with little more than a symptom. Say how to resolve the identifier
  the request didn't carry, and require an inferred one to be labelled inferred — see
  format.md's entry conditions.
- **A step that assumes a console, a laptop or a teammate stalls the procedure.** You are
  followed with the session's tools, not by the person who wrote you.

## You are not the first to look

An automated caller usually arrives holding evidence already: the alert, recent changes,
messages, prior incidents. Whether it hands you a summary or a mounted workspace differs
by environment ([agent-environments.md](agent-environments.md) has the map)
— what holds everywhere is that re-deriving what it already gathered spends the
incident's time on facts it was handed.

- **Start from carried evidence**, per what-works.md's rule, then query into the gaps.
- **Say what you need rather than fetching it twice.** Where a fact is likely already in
  hand, name it as an input instead of writing a step to go and get it.

## Your findings are someone else's evidence

Assume your output is lifted into a larger picture rather than read as a standalone
report. That changes two things.

- **State your output contract once**, per what-works.md, as a short set of headings.
  A procedure that ends in a fixed shape gets carried accurately; one that trails off in
  prose gets summarised away.
- **Every claim carries where it came from.** A caller can only attribute what you
  attribute. An unattributed finding is dropped, or carried without provenance — which
  is worse.
- **Say plainly when the answer is not there.** what-works.md's abstention rule matters
  more than usual: a confident guess made early gets built on.

## Round-trips cost time, depth does not

Whatever reaches for your procedure is waiting on it, and during an incident that wait is
paid by the people responding. But the cost is in how many times your skill has to go and
ask, not in how much it has to say. Time spent getting the question right tends to be
repaid by the work nobody then has to redo.

what-works.md's cost rule carries the mechanics: name which calls are expensive, rank on
the cheap ones and confirm with the dear ones, and give every search a stop rule. Two
things this caller adds:

- **Count the round-trips, not the words.** A procedure that could be three queries and is
  twelve delays every conclusion behind it, however tersely it is written. Say which calls
  can be made together, so a caller doesn't serialise what it could ask at once.
- **Say where a step is slow, and what it buys.** Then a caller can skip it on its own
  judgement rather than discovering the cost midway.

So don't truncate a step that decides the answer, and don't pad one that doesn't. Being
fast is not the same as being brief. The test is whether a responder would thank you for
the wait.

## What earns the reach

- **One subject, owned.** The utility shape in what-works.md is the target: teach the
  agent to interrogate one system, and the procedures fall out of that understanding.
- **Something a generic caller cannot work out.** Your value is the part that is true
  only of your estate — the vocabulary, the trap, the check that is obvious to your team
  and invisible from outside it.
- **Reading results correctly.** Confusing zero with failure is the most common way a
  correct procedure produces a wrong answer — see what-works.md's rule that the two never
  render the same.

## What gets you skipped

- **A skill with no stated subject.** "Incident triage" or "production issues" gives a
  caller nothing to match on. Applying to every incident is fine; saying nothing about
  what you do is not.
- **A skill that assumes a conversation.** Nobody is there to answer.
- **A skill that re-runs what the caller already swept.** Those results are already in
  hand.

A skill that never gets chosen is a problem with the name or the description, not with
the body — the body is only read once selection has already happened.