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 its right rail answers two questions while you type:

• Cost estimate — what one call and one month of this draft cost on the model it will run on: ≈ $0.0031 per call on ‹model› · was $0.0028 in v1.2 (+11%) and ≈ $31 / month at 10,000 calls (your last 30 days when the skill has run; a neutral scale otherwise). The badge says how exact the count is; Assumptions opens the model, the output-token figure and the rates behind it. When a draft costs more than a fifth more per call than the saved revision the panel says so, in dollars per month.
• Inputs — the form a consumer sees, generated from inputs, with the schema's errors and warnings listed by line (the same underlines the YAML editor shows) and hints when the form would be hard to use. Fill it in and Run to render the body with those values before saving; View JSON shows the same payload raw.

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 maps of field name → field (type — string, number, integer, boolean, object, array — plus description, format, required, enum, default, items, properties); the runtime validates the caller's input against inputs before the skill runs, and the editor underlines anything outside that shape. 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.