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, and read_skill_file reads one back. This is how you version skills in a repository.

Skills an app installed

Installing an app puts a skill on the agent explaining how to use that service tools. That skill belongs to the app, so it is read only everywhere: the editor opens it without a save button, the agent’s own skill tools refuse to touch it, and the API refuses too. Rewriting it would be lost at the next install, and deleting it would leave the app pointing at nothing. To change what the agent does with a service, either reconfigure the app or write a skill of your own next to it. Uninstalling the app removes its skill with it.

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.
Each text file can be up to 10 MB, with a 50 MB total per skill including SKILL.md.
A reference file is read 100,000 characters at a time; the agent follows nextOffset when it needs the next page.
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

Skills an app installed

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

​Skills an app installed

​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

Skills an app installed

When to write a skill instead of something else

Limits