Skills

Frontmatter reference

These are the fields the SKILL.md frontmatter can set. Only name and description are required; everything under metadata is optional and refines how the skill is presented and matched.

Resolution order

Skills are discovered at boot and loaded into the catalog in a fixed order. The model then pulls skills into context on demand: it matches the conversation against each skill's description and activation hints, then loads the ones that fit. Multiple skills can be active at the same time.

Discovery is filesystem-driven and happens before the first turn:

1. Bundled skills. Shipped with the Assistant, discovered from the built-in skills directory.
2. Workspace skills. Discovered from /workspace/skills/, letting you drop a skill directory without packaging it as a plugin.
3. Plugin skills. Discovered from every plugin's skills/ subdirectory at boot.

When two skills with the same name are discovered, the first one found wins and the duplicate is logged and skipped. The load order above determines which skill wins a name collision; once loaded, there is no execution priority between skills. They are instruction bundles, not runnable hooks, and the model decides which to follow based on the frontmatter, not on timing.

Anatomy of a skill

One skill per directory. The SKILL.md is required; assets and helper scripts are optional and live alongside it:

plugins/my-plugin/
└── skills/
    └── standup-notes/
        ├── SKILL.md        # Frontmatter + instructions (required)
        ├── references/     # Optional docs the instructions cite
        └── scripts/        # Optional helper scripts the skill runs
            └── post_summary.ts

The SKILL.md itself is frontmatter plus the procedure the Assistant follows once the skill is active:

---
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:
  vellum:
    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 update with three sections: Yesterday, Today,
and Blockers.

## Steps

1. Summarize what was completed since the last standup.
2. List what the user plans to work on today.
3. Call out any blockers, or write "None" when there are none.

Keep each section to a few short bullet points.

The scripts/ and references/ directories are optional companions to SKILL.md. The body invokes them by relative path:

• Scripts. Reference a script by its path relative to the skill directory. The assistant runs it via the bashtool when the instructions call for it. For example, a body that says "Run scripts/post_summary.tsto submit the summary" tells the assistant to execute bun run scripts/post_summary.ts from the skill directory.
• References. Cite a reference file by relative path when the body needs to defer detail. For example, "See references/api-fields.mdfor the full field contract" tells the assistant to read that file when it needs the details, rather than inlining them in the body. This keeps the body short and loads the detail only when relevant.

See the Extensibility overview for how skills sit alongside the other surfaces a plugin can bundle.

When should my assistant write a Skill?

Reach for a skill when the capability is a repeatable procedure the model should follow in natural language, not code that has to run deterministically. A skill is the right home for “here is how we do X”: the steps, the house style, the reference material, and any helper scripts those steps call. It is dynamically loaded only when the conversation matches, so it costs nothing in the model's context until the request calls for it.