Skills
A skill is an on-demand procedure following the SKILL.md convention:
the harness advertises each skill by its description, and the model
loads the full content only when the task calls for it. Skills are how
you give an agent a multi-step workflow without carrying it in the
always-on instructions.
Authoring forms
Skills support three authoring forms.
| Form | Reach for it when |
|---|---|
bot/skills/<name>.md | Static Markdown. Optional description frontmatter; the first body line is the fallback. |
bot/skills/<name>/SKILL.md plus siblings | A packaged directory with reference files (references/…). Requires description frontmatter. |
bot/skills/<name>.ts | Generated content, with defineSkill from @cursor/bdk/skills. |
Use flat Markdown for static content:
---description: Use when a pull request needs a structured approval checklist.---# PR review checklist1. Call `inspect_pr` and confirm required checks passed.2. Summarize the PR title, author, and remaining risks.3. Call `approve_pr` only after an explicit request.Use TypeScript when the content must be generated or include inline sibling files:
import { defineSkill } from "@cursor/bdk/skills";export default defineSkill({ description: "Research unfamiliar topics before answering.", markdown: "Gather evidence first, then answer with the key facts.", files: { "references/checklist.md": "# Checklist\n\n- Find sources.\n" },});Skill delivery
Skills land in the session workspace at
.cursor/skills/<name>/SKILL.md, and the harness advertises and loads
them natively.
Skills, instructions, and tools
Instructions are always in context: identity, tool-choice rules, the output contract. Keep them short. Skills load when relevant: procedures, checklists, house style. Reach for a skill when the model needs to follow something but only sometimes needs it loaded. Tools are typed, executable behavior: anything that must be correct every time belongs in tool code, not in prose the model might paraphrase.
A good skill description is a routing rule, not a title. Say when to use it, like "Use when a pull request needs a structured approval checklist," because the description is all the model sees before deciding to load it.
Related
- Instructions: what stays always-on
- Tools: when prose needs to become code
- Extensions: skills installed as a package under a namespace
- Project layout: where skills sit in the tree