Skip to content

Agent Skills Authoring

Condensed from best practices for skill creators. Load this when drafting or revising skill instructions.

Ground in Real Expertise

Do not synthesize a skill from generic model knowledge. Before writing domain claims, follow source-first research: official documentation first, then implementation source only for unresolved mechanics.

Capture:

  • Sequences that actually worked
  • Corrections that steered the agent (library choice, edge case, forbidden path)
  • Input and output shapes
  • Project facts the model does not already have

Useful source material: runbooks, schemas, review comments, patches, incident resolutions. Extract from a completed task, or synthesize from those artifacts.

Context Budget

Once activated, the full SKILL.md body competes with conversation, system context, and other skills.

  • Include only facts the agent would get wrong without the skill.
  • Omit explanations of well-known formats, protocols, and language features.
  • Test uncertain lines: if the agent already succeeds, cut the instruction.
  • Scope one coherent unit that composes with other skills.
  • Prefer moderate, stepwise detail plus one working example over exhaustive edge-case catalogs.

When the body would exceed ~500 lines / 5,000 tokens, move depth to references/ (or scripts/ / assets/) and state the load condition:

Read references/api-errors.md if the API returns a non-200 status code.

That is more useful than "see references/".

Control Calibration

Match specificity to fragility.

  • Flexible: several valid approaches. Explain why so the agent can adapt.
  • Prescriptive: fragile, consistency-critical, or ordered sequences. Give the exact command and forbid extra flags.
  • Defaults, not menus: pick one tool or path; mention alternatives only as escape hatches.
  • Procedures, not instances: teach how to approach the class of problem. Templates, hard constraints ("never output PII"), and tool-specific commands still belong; the approach must generalize.

Instruction Patterns

Use only the patterns the task needs.

Gotchas. Environment facts that contradict reasonable assumptions. Keep them in SKILL.md so they are read before the failure. When a live run is corrected, add the correction here.

Output templates. Concrete structure the agent can pattern-match. Short templates inline; long or conditional templates in assets/.

Checklists. Multi-step work with dependencies or gates. Track progress explicitly.

Validation loops. Do the work, run a validator (script, reference, or self-check), fix, repeat until it passes.

Plan-validate-execute. For batch or destructive work: emit a structured plan, validate against a source of truth, then execute.

Bundled scripts. If traces show the agent reinventing the same parser, chart, or check, put a tested script in scripts/. See scripts.

Iteration

Run the skill on real tasks. Feed successes and failures back in. Watch traces, not only final output. Vague instructions, always-on inapplicable steps, and option menus without a default are common sources of wasted turns.

For structured evals, see evaluation. For trigger wording, see descriptions.