‹ Back to the directory

Skill Authoring Guide

Write agent skills that trigger reliably and execute consistently: sharp descriptions, concrete steps, testable output.

by Lunefield·0 installs
skillsauthoringagentsdocumentation
K

Create a free shareskills account to install Skill Authoring Guide into Claude.

Create a free account

Skill Authoring Guide

A skill is a procedure you trust an agent to run when you are not watching, written down well enough to survive the author's absence. This skill guides the writing of new agent skills: choosing a scope worth encoding, writing a description that triggers exactly when it should, and turning expert judgment into steps concrete enough to produce the same quality twice.

When to use this skill

  • Capturing a workflow you have now explained to an agent — or a colleague — three separate times
  • A skill exists but fires at the wrong moments, or never fires, and its description needs rebuilding
  • A skill runs but produces different quality on identical inputs; the body needs de-vaguing
  • Converting a checklist, runbook, or process document into an executable skill

Instructions

  1. Pick one job. A skill encodes one repeatable outcome — "produce a release-notes draft from merged changes" — not a topic like "releases." If the description needs the word "and," consider writing two skills.
  2. Write the trigger description as honest retrieval bait. It must answer three questions: what this does, when it should fire, and when it should NOT. Include the words users actually say — "changelog," "what shipped," "release notes" — because matching happens against user phrasing, not your taxonomy. Negative triggers ("not for hotfix announcements") prevent the overfiring that gets skills switched off.
  3. Open the body with the mission paragraph: the outcome, the standard it is held to, and the one or two principles that resolve ambiguity when the steps run out. Agents fall back on this paragraph the moment reality goes off-script, so make it load-bearing.
  4. Write steps as decisions, not gestures. "Review the data" is a gesture. "Sort by amount descending; flag rows above the 95th percentile; if more than 10% get flagged, stop and ask" is a decision an agent can execute and a reviewer can audit. Each step says what to produce, from which input, and what done looks like.
  5. Encode the judgment, not just the motions. The expert value lives in the tie-breakers: what wins when speed and completeness conflict, what is never acceptable, which errors are recoverable. Write these as explicit rules — they are the difference between a skill and a to-do list.
  6. Specify the output format literally. A template with placeholders beats three paragraphs describing one. Include the degraded mode: what to emit when inputs are missing or the task turns out to be impossible.
  7. Add guardrails as hard boundaries, separate from the workflow: what the skill must never do — send, delete, guess silently — and the conditions under which it must stop and ask.
  8. Test it like software. Run 3-5 realistic prompts: one obvious trigger, one paraphrased trigger, one near-miss that should NOT fire, one input with a missing prerequisite. Fix firing bugs in the description; fix quality bugs in the body. Never fix a body bug by fattening the description.
  9. Trim before shipping. Every sentence costs attention at execution time. Delete anything that does not change behavior; merge steps that always run together.

Output format

The shape of a well-formed skill file:

# <Name>
<mission paragraph: outcome, standard, tie-breaking principles>

## When to use this skill
<3-6 positive triggers, 1-2 negative triggers>

## Workflow
<numbered decisions, each with inputs and a done-criterion>

## Output format
<a literal template, plus the degraded mode>

## Guardrails
<hard prohibitions and stop-and-ask conditions>

Quality bar

  • Two different agents given the same input would produce interchangeable output
  • The description alone lets a router decide correctly on ten realistic prompts
  • No step depends on knowledge that exists only in the author's head
  • Guardrails are enforceable prohibitions, not values statements
  • A domain expert reads the steps and recognizes their actual judgment, not a generic process

Smells that demand a rewrite

  • A description that is a topic sentence with no verbs in it
  • Steps where "appropriately," "as needed," or "relevant" carry the load
  • An example output that could not have been produced by following the steps
  • A skill pushing past ~150 lines because it quietly encodes three jobs
Skill Authoring Guide — AI skill by Lunefield | shareskills