Authoring a skill

A skill is a single SKILL.md-shaped document: YAML frontmatter that describes the skill, followed by a markdown body that is the work. This page walks through authoring one from the dashboard.

1. Open the skill editor

Go to /a/<account>/settings/skills and choose New skill, or open an agent's Skills tab to author one bound to that agent. The editor validates the frontmatter live, shows a preview of the discovery card the model will see, and includes a Test invoke panel so you can run the skill with sample input before saving.

2. Write the frontmatter

The frontmatter is the discovery card — it is loaded into the model's tool list at every turn, so keep it tight and concrete.

---
name: pr-recap
description: Summarise a GitHub PR's diff and comments in three bullets.
version: 0.4.2
when_to_use: When a user asks "what changed in PR #X" or wants standup prep.
inputs:
  pr_url:
    type: string
    format: uri
    required: true
outputs:
  summary:
    type: string
---

name, description, version, and when_to_use are required. inputs and outputs are JSON Schema shapes; the runtime validates the caller's input against inputs before the skill runs. name is the skill's slug (kebab-case). Make when_to_use specific — it is the hint the model uses to decide when to reach for the skill.

3. Pick a body kind

The body kind determines what running the skill actually does. There are six, each mapping to one runtime:

Body kind	What the body is	Runs as
prompt	A prompt template with {{var}} substitution	The agent's current model
model_call	A user-message template	One call to a chosen catalog model
mcp_tool	Human-facing description	A passthrough to an MCP tool
integration_action	Description	One call through a connector
script	A fenced code block (or sidecar file)	A sandboxed script in /workspace
composition	A description of the steps	A linear pipeline of other skills

The most common kind is prompt — the body is the instruction:

Summarise the following PR for a standup. Return three bullets:
what changed, why, and any risk.

{{pr_url}}

For a model_call or integration_action skill, declare the binding in frontmatter (the catalog model slug, or the connector the action runs through) so the skill is self-contained.

4. Save — every save is a revision

Saving creates a new revision and points the skill at it. History is the full revision list, so you can diff and revert. Recommend semver-ish version strings; imported skills inherit their upstream version.

Where to go next

• Managing skills to scope, enable, and attach the skill to an agent.
• Create an agent that calls the skill you just wrote.