Skills

A skill is an on-demand procedure in the SKILL.md convention. Agent SDK advertises each skill by its description, and the model loads a skill only when the task calls for it. Skills give an agent a multi-step workflow without carrying it in the always-on instructions.

Authoring forms

Form	Reach for it when
bot/skills/<name>.md	Static Markdown. description frontmatter is optional and falls back to the first body line
bot/skills/<name>/SKILL.md plus siblings	A packaged directory with reference files. Requires description frontmatter
bot/skills/<name>.ts	Generated content, with defineSkill from @grok/agent-sdk/skills

Use flat Markdown for static content:

---
description: Use when a pull request needs a structured approval checklist.
---

# PR review checklist

1. 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 "@grok/agent-sdk/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

Local sessions get each skill at .cursor/skills/<name>/SKILL.md in the session workspace, and the agent lists and loads them from there.

Skills, instructions, and tools

Instructions stay in context on every turn. Skills hold procedures, checklists, and house style that the model needs only sometimes. Put anything that must be correct every time in a typed tool, where the model can't paraphrase it.

A description is a routing hint, so say when to use the skill, as the checklist example does. The model sees only the description before it decides to load the skill.