Skills

A skill is a written procedure. The agent reads it when the task at hand matches its description, and ignores it the rest of the time. Skills are how you make an agent good at something specific without turning its system prompt into a manual.

What a skill looks like

A skill is a folder, not a single file. It holds a SKILL.md and any reference files you want to give it.

SKILL.md

---
name: Weekly report
description: Use when asked for the weekly numbers, on Monday or on demand.
---

1. Query the `sales` table for the last 7 days
2. Follow the layout in `references/format.md`
3. Write the report to the shared folder as `reports/<week>.md`
4. Post the link in Slack

Two fields matter in the frontmatter:

name gives the skill its slug, which is how everything addresses it.
description is what makes the agent decide to open the skill. Write it as a trigger condition, not as a summary. “Use when asked for the weekly numbers” beats “About weekly numbers”.

Why it stays out of the way

Skills load in three layers:

Always in context

A one-line index: the name, the slug and the description of every skill. Nothing else.

On demand

When a task matches, the agent opens the skill and reads the whole procedure.

At the exact step

It opens a reference file only when the procedure tells it to.

That is why a skill can carry a long reference corpus without costing anything on every run. Keep the body short and push the detail into references/.

Create and edit one

In the app
Ask the agent
From the API

Open the agent panel, go to the Skills tab, and click New. Write the name, the description and the body. Reference files are added from the same editor.

Tell it what to do and to remember the procedure. It writes the skill itself, as long as the skills capability is on.

upsert_skill writes the body and the reference files in one atomic call. This is how you version skills in a repository.

When to write a skill instead of something else

Situation	Where it belongs
A repeatable procedure with steps	A skill
Who the agent is and how it behaves	The soul
A fact it should remember, like a preference or a name	Memory
Reference material that is long and rarely needed	A reference file inside a skill

When you correct an agent behaviour and the correction is a rule rather than a fact, fix the skill that governs it. A memory can be outvoted by a procedure, a procedure cannot.

Limits

A skill lists up to 200 bundled files.
A reference file is read up to 100,000 characters at a time.
SKILL.md itself cannot be written through the file tools. Change it through the skill body.

Get started

Build an agent

Your account

What a skill looks like

Why it stays out of the way

Create and edit one

When to write a skill instead of something else

Limits

​What a skill looks like

​Why it stays out of the way

​Create and edit one

​When to write a skill instead of something else

​Limits

What a skill looks like

Why it stays out of the way

Create and edit one

When to write a skill instead of something else

Limits