Skills

A skill is a directory with a SKILL.md at its root. YAML frontmatter tells the assistant what the skill is for. The markdown body is the procedure it follows once the skill is active. A plugin ships skills under skills/<name>/.

What a skill is

Nothing runs on its own. The skill gives the assistant a procedure plus any scripts or assets it ships. The assistant decides when to load it from description and activation hints. Write those fields for the model.

Frontmatter

Field	Required	Purpose
`name`	Yes	Display name. The directory basename is the canonical id.
`description`	Yes	What it does and when to use it. Matching uses this.
`metadata.cadence.display-name`	No	Human-friendly label.
`metadata.cadence.activation-hints`	No	Situations that should fire the skill.
`metadata.cadence.avoid-when`	No	Adjacent-but-wrong situations.
`metadata.cadence.category`	No	Grouping in clients. Defaults to system.

Resolution order

Bundled skills shipped with the assistant.
Workspace skills under /workspace/skills/.
Plugin skills from each plugin skills/ directory.

First name wins. Duplicates are logged and skipped. Multiple skills can be active at once. See Skills and tools and Your first skill.

Anatomy

---
name: standup-notes
description: >-
  Draft a daily standup update from recent activity. Use when the user
  asks for their standup, daily update, or what they did yesterday.
metadata:
  cadence:
    display-name: "Standup Notes"
    activation-hints:
      - "User asks for their standup or daily update"
    avoid-when:
      - "User wants a full weekly report, not a daily standup"
---

Draft a concise standup with Yesterday, Today, and Blockers.

Optional scripts/ and references/ live beside SKILL.md. The body cites them by relative path. The assistant runs a script via the bash tool when the instructions say to.

When to write a skill

When the capability is a repeatable procedure in natural language. Skills load on demand, so they cost nothing in context until the request calls for them. If the action must run every turn at a fixed boundary, write a hook. If the model should call a typed action, write a tool.