Skills

A skill is a written procedure an agent can pull in when it needs one. Not a tool it calls and not code that runs on its behalf — a document, in Markdown, describing how to do something well.

That sounds slight, and it is the point. Most of what makes an agent good at a task is knowing the shape of the task: what to check first, what the usual failure is, what “done” looks like. Encoding that as prose is cheaper than encoding it as code, easier to review, and easier to correct when it turns out to be wrong.

The shape of a skill

A skill is a directory. SKILL.md is mandatory; anything else beside it — scripts, reference documents, templates, sample data — is optional and up to you.

skills/
  web-research/
    SKILL.md
    checklist.md

SKILL.md opens with YAML frontmatter and continues as ordinary Markdown:

---
name: web-research
description: Structured approach to answering questions that need looking
  something up rather than being answered from memory.
---

Both fields are required, and name must match the directory name exactly. The platform rejects a skill that breaks either rule at save time rather than accepting it and letting it misbehave later, because the failure it prevents is a quiet one: a malformed skill saves cleanly and then simply never appears to the agent, with nothing anywhere to say why.

description has a hard limit of 1024 characters, enforced for the same reason — the runtime truncates a longer one silently, and a truncated description is exactly the kind of thing you would not notice while wondering why an agent keeps ignoring a skill.

Why the description is the important field

Agents do not read every skill on every run. They see an index of names and descriptions, and read the full text of a skill only after deciding it applies. The description is therefore not a summary for humans; it is the entire basis on which the agent decides whether to open the document at all.

Write it as a trigger, not a title. “Structured approach to answering questions that need looking something up rather than being answered from memory” tells an agent when. “Web research helper” tells it nothing it can act on.

The body is where the detail goes, and it can be as long as it needs to be, because it is only loaded when it is relevant.

What an agent can see

Skills come from two layers. A platform base layer is shared across the whole installation; your tenant’s own layer sits on top of it, and a tenant skill with the same name as a base skill replaces it. That is how a tenant adapts a shared procedure without forking it or asking anyone.

An agent’s skills: frontmatter list records which skills the agent is meant to use, and travels with the agent when it is exported as a plugin. It does not currently narrow what the agent can see: every agent in a tenant is offered that tenant’s whole skill library plus the base layer. Treat the list as documentation of intent, and expect an agent to reach for a relevant skill you did not list.

Skills that carry scripts

A skill may ship executable files, and an agent may run them. When it does, they execute in an isolated sandbox — never inside the API or the agent runtime. A skill’s script cannot reach the platform’s own processes, its database, or another tenant’s data, regardless of what the skill’s prose says.

That last clause is the one to internalise: prose in a skill is never a security boundary. A skill saying “only run this for trusted users” is a note to a model, not an enforcement mechanism. The boundaries that hold are the sandbox and the agent’s trust tier.

Skills are also read-only to the agents that use them. An agent can read a skill’s files; it cannot write to them.

Managing skills

Skills are authored on the Skills screen, or shipped in a plugin. Both paths run the same validation, so a plugin that imports cleanly contains skills that would have saved cleanly, and vice versa.

Skill management is not part of the published API. Author skills in the platform, and let your API clients run agents that have them.

Next: Plugins.