great-skill-writing

Files (9)

• SKILL.md
• skill-template.md · assets/
• failure-modes.md · references/
• glossary.md · references/
• scripts-python.md · references/
• scripts-typescript.md · references/
• spec.md · references/
• testing.md · references/
• lint_skill.py · scripts/

SKILL.md (first lines)

# Great Skill Writing

A skill exists to extend an agent's capability, to wrangle determinism out
of a stochastic system, or both: supplying context the agent doesn't yet
have pushes the boundary of what it can do; restricting output makes how it
does it **predictable** — the same _process_ every run, consistent
high-quality output rather than identical output. Every rule below is a
lever on one or the other.

## Route by task

- Creating a new skill → define it in step 1, then run the remaining workflow.
- Improving, reviewing, or pruning an existing skill, or diagnosing one that
  misbehaved → follow the improvement workflow below.
- Read [references/spec.md](references/spec.md) when a spec constraint is uncertain or a lint finding is unclear.
- Read [references/glossary.md](references/glossary.md) when a term used here needs its full definition.

## Rules that apply on every branch

### Value: add what the agent lacks

A skill earns its load in two ways, separately or together: **context
provision** — supplying what the agent doesn't already have (project-specific
conventions, non-obvious procedures, exact APIs) — and **output restriction** —
reducing output variance with the instruction patterns below. Skip
explanations of standard concepts. Teach the approach, not one worked
instance — instructions must survive task variations. Give one default per
decision, alternatives in a single sentence: presented equal options make
agents choose inconsistently, the opposite of predictability. Calibrate
specificity to fragility: fragile or ordered operations get prescriptive
steps; where several approaches are valid, explain why, not what. Write for
agents, not humans: concise and directive, no pleasantries. And "the agent"
is not one model: a distributed skill runs on models of unequal capability
across different harnesses, so make every model-relative judgement — what
the agent lacks, what counts as standard, the no-op verdict — against the
least capable model the skill is meant to support, not the model at hand.
Write to the floor: a stronger model tolerates restriction it doesn't need;
a weaker one breaks without it.

### Instruction patterns

The restriction toolkit — use each where it applies, none by obligation:

- **Gotchas** — non-obvious domain facts the agent would get wrong
  by reasonable assumption (naming inconsistencies, soft deletes,
  endpoints that lie). Add one only when a correction reveals a reusable
  failure mode; general advice ("validate inputs") adds no signal.
- **Checklists** — for multi-step workflows with dependencies or validation
  gates.
- **Validation loops** — do → validate → fix → repeat; a validator whose
  errors state what is wrong and how to fix it lets the agent self-correct
  without a round-trip.
- **Plan-validate-execute** — for batch or destructive operations: produce a
  structured plan, validate it against a source of truth, then execute.
  Never skip the validation.
- **Templates (assets)** — only for intentionally fixed or stable-pattern
  material the agent copies or lightly edits. Templates constrain output
  diversity: content needing task-specific judgment, broad rewriting, or
  flexible organization becomes instructions on the hierarchy instead, never
  an asset. An asset may carry inline fill-guidance — placeholders or embedded
  comments marking what to replace — but its surrounding how-to-use
  documentation (when and how to use it) belongs in SKILL.md or a reference;
  wrap the copied material in that framing and the file stops being the thing
  to copy and becomes a document about it.

### Descriptions

The description is the only text the agent reads before activating, so it
does two jobs: name the capability and list the triggers. The trigger clause
is the payload — give it most of the space, and compress the capability into
a short third-person lead-in (action verbs, domain keywords), never a
feature list: features are identity, and identity lives in the body. Every
character is permanent context load — prune it harder than the body:

- Front-load the skill's leading word; never open with filler ("This skill
  helps…").
- Mine triggers from every signal type, not only domain words. Walk the list
  asking "should this signal fire the skill?": direct naming and indirect
  phrasings (what a user says without naming the domain), intent verbs
  (create, review, fix), the scenario the user is in, observed agent
  behavior the skill corrects, the shape of the material at hand (a pasted
  or open file of the skill's kind), lifecycle events (before release, after
  a model or harness change), questions about the domain, and exclusions —
  adjacent tasks that must not fire it.
- One trigger per branch. Synonyms renaming the same branch are duplication;
  collapse them.
- Cut identity that's already in the body; keep triggers.

### Invocation

Default to model-invoked: keep the description visible so the agent (and
other skills) can reach it, and accept the context load it costs. Make a
skill user-invoked only when it should never fire except by the human typing
its name — then the human pays cognitive load as the index that remembers
it. The switch is host-specific (Claude Code: `disable-model-invocation:
true`), not part of the Agent Skills spec — read the portability section of
[references/spec.md](references/spec.md) when setting it or any other
non-spec field.

### Information hierarchy

Rank every piece of content by how immediately the agent needs it:

1. **Steps** — ordered actions in SKILL.md. Add a completion criterion when a
   step needs a meaningful boundary: the work is prone to premature
   completion, thoroughness matters, or the result has an observable success
   condition. Make it _checkable_ (the agent can tell done from not-done) and,
   where thoroughness matters, _exhaustive_ ("every modified model accounted
   for", not "produce a change list"). Omit it when it would not change how
   the agent executes or judges the step. A demanding criterion can also drive
   legwork in flat reference: "every rule applied" binds a rule list just as
   "every step done" binds a sequence.
2. **In-file reference** — rules and facts in SKILL.md, consulted on demand.
   A flat peer-set (every rule of a review on one rung) is fine.
3. **Disclosed reference** — a `references/` file behind a context pointer,
   loaded only when the pointer fires.

Branching decides the split: inline what every branch needs, disclose what
only some branches reach. The pointer's _wording_ decides reach — "Read

From ryan-minato/skills, Apache-2.0.

More from ryan-minato/skills