Skip to main content

SKILL.md

Writing a skill

Define the load boundary and operating rules. Keep repo policy in the repo.

  1. Load
  2. Act
  3. Prove
  4. Stop

Skill anatomy

portable context packet
  1. 01TriggeradmissionLoad only when the task matches; name the skips.
  2. 02MethodoperatingHard imperatives. No repeated rationale or catalog jargon.
  3. 03Referencessource packTemplates and examples stay one hop away.
  4. 04Scopelocal factsCommands and product policy stay in AGENTS.md.
layout

Use a small folder.

Keep the entry point in SKILL.md. Move support material to references only when it would bury the load rule.

Entry
SKILL.md
Optional
references/
Keep out
repo policy

skill folder

minimal layout

files
# minimal
skills/sus-spec/
  SKILL.md

# with one reference
skills/sus-spec/
  SKILL.md
  references/
    task-template.md
description

Write the trigger first

Treat the description as the load contract. Name the work it should match and the work it should skip.

  • Sentence one: action and target.
  • Sentence two: a positive Use when trigger.
  • Sentence three: genuine near misses under Do not use.
  • Keep procedure, sequencing, evidence rules, and completion mechanics in the body.

SKILL.md

front matter

skill
---
name: sus-spec
description: Write, revise, or structurally check a verifiable Suspec spec. Use when intent must become requirements or acceptance criteria, or unresolved behavior blocks implementation. Do not use for direct implementation, small clear work, factual verification, or implementation design.
---
body

Put execution in Method

Hard imperatives only. Add a section when it changes behavior, not because the template had one.

  • Method is mandatory

    Put executable behavior under Method. Add other sections only when they carry behavior.

  • Keep it self-contained

    Skills install individually. Never name, require, invoke, or assume a sibling.

  • Compose by meaning

    A useful next job may match another skill's trigger, but must still work when that skill is absent.

references

Use references sparingly.

Put long templates or examples in references/. Keep them one hop away from SKILL.md.

templates

Add a task template only when useful.

Use a template for long work that needs state: plans, evidence, attempts, decisions, and follow-up.

scope

Keep repo knowledge out

A Suspec skill must work in any repo. Put local commands and product knowledge in that repo's AGENTS.md. Do not smuggle a project into a global skill.

  • engineering-domain knowledge (auth patterns, caching, runbooks)

  • stack- or vendor-specific skills

  • internal product docs

  • automation, scripts, or CI in the catalog

  • core or loader skills that other skills depend on

  • skills designed to always load

next

Read the source

The catalog has universal methods and canonical artifact authors. Read the source; it is shorter than guessing.