# 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](/docs/reference/instructions.md).

## 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 `@grok/agent-sdk/skills`. |

Use flat Markdown for static content:

```md
---
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:

```ts
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

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](/docs/reference/instructions.md): what stays always-on
- [Tools](/docs/reference/tools.md): when prose needs to become code
- [Extensions](/docs/reference/extensions.md): skills installed as a package under a
  namespace
- [Project layout](/docs/reference/project-layout.md): where skills sit in the tree