Docs: Skills

A skill is guidance stored as data: instructions for a task, curated examples of how to handle it, and the tools its procedure uses. It is an action of kind skill, so it has a name, versions, policies, and a record of every load. Agents load a skill when the task calls for it, and MCP servers offer skills to agents outside Twisp.

A skill does no work of its own. It tells an agent how to do work with the tools it has.

What a skill holds

The skill block holds:

Instructions. The procedure, in plain text: what to check, in what order, and what counts as done.
Examples. Up to 20 cases, each a situation and its resolution, optionally with the reason and the source session it came from. Examples teach the edge cases instructions state badly, such as what to do when a read fails partway.
Tools. The tools the procedure uses, by name and optionally by version.

mutation CreateSkill($id: UUID!) {
  actions {
    createAction(
      id: $id
      input: {
        name: "review-fraud-watch-activity"
        description: "How to review a watched account's activity and record findings."
        kind: "skill"
        config: {}
        skill: {
          instructions: "Review account activity and record the evidence for each finding."
          examples: [
            {
              situation: "A page of activity failed to load."
              resolution: "Mark the review incomplete."
              reason: "A partial read is not evidence that the rest was clean."
            }
          ]
          tools: [{ name: "get_account_activity" }]
        }
      }
    ) {
      actionId
      pending
    }
  }
}

A skill needs a name, which the model sees together with its description, so write the description as when to load it. A skill has no triggers, session, or tool block. See Skills for every field and limit.

How an agent loads a skill

An agent declares the skills it may load in its skills list. The model sees each one's name and description, and loads one when its task needs it. A load returns exactly the instructions and examples of the version the agent's invocation resolved, and is recorded as a child execution of the agent, like a tool call.

skills: [{ name: "review-fraud-watch-activity" }]

A reference without a version loads the skill's latest version, resolved when each execution or session turn starts, so editing a skill reaches its agents at their next turn. Pin a version when a change to the guidance must be a deliberate edit of the agent. See Skill references.

A client can load a skill too, through invokeAction with an empty input object.

Tools a skill makes available

When an agent loads a skill, the tools the skill lists join the agent's tools for the rest of its session, or, without a session, the rest of its invocation. Before the load, the agent is not offered them and cannot call them. This keeps an agent's tool list short until a task needs more, and keeps a procedure and its tools together, so they change together.

A skill grants nothing. A call to one of its tools is authorized as any call the agent makes, by the agent's policies and the tool's own. When the agent lists the same tool itself, its own reference applies instead, with its version, fixed input, and approval. See Tools a skill makes available.

When an MCP server serves a skill, the external agent receives its instructions and examples, but the load makes none of the skill's tools available: the external agent can call only the server's own tools. See Skills in the MCP reference.

Preloading

A skill an agent always needs can be preloaded with preload: true. At the start of every turn, the agent loads each preloaded skill before its first model call and places its guidance after the agent's prompt, and the tools the skill lists are offered from the start. An agent can preload at most 8 skills. Each preload is still an ordinary, recorded load of an exact version. See Preloaded skills.

skills: [{ name: "ledger-conventions", preload: true }, { name: "review-fraud-watch-activity" }]

Preload guidance that applies to every turn. Leave guidance for particular tasks to load on demand, so a turn carries only what it uses.

Output uses

Each invocation records, in uses, the tool answers and skill guidance that reached its handler, each naming the exact call or load and version that produced it. For an agent, Twisp derives these from its calls. So for any decision, you can read which guidance the agent had in front of it. A use records what was supplied, not whether it was followed: the transcript shows what the agent did with it. See Output uses.

A skill or the agent prompt

Both are text an agent reads. They differ in how they are versioned, shared, and recorded.

Put it in the agent `prompt` when	Write a skill when
It describes what this agent is for and how it works.	It describes how to do a task that more than one agent, or an outside agent, does.
It applies to every turn.	It applies to some tasks, and the agent can tell from the description when.
It changes when the agent changes.	It should change on its own schedule, with its own versions, without editing agents.
It needs no tools beyond the agent's own.	It brings the tools its procedure uses.
You do not need a record of when it was used.	You want each use recorded with the exact version supplied.

A preloaded skill sits between the two: it applies to every turn like prompt text, and is versioned, shared, and recorded like a skill.

Next steps

Read Agents to declare skills on an agent, and follow Your First Agent.
Read MCP Servers to offer skills to agents outside Twisp.
See the Skills reference for every field, limit, and error.