Agent SDK0.2.29

Appearance

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.

FormReach for it when
bot/skills/<name>.mdStatic Markdown. Optional description frontmatter; the first body line is the fallback.
bot/skills/<name>/SKILL.md plus siblingsA packaged directory with reference files (references/…). Requires description frontmatter.
bot/skills/<name>.tsGenerated 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.