# Skills

Define skills that supply reusable guidance, the tools they make available, and how agents load them.

A skill is an action of kind `skill` whose output supplies reusable guidance: the instructions and examples in its `skill` block. See the [`skill` handler](https://www.twisp.com/docs/reference/actions/skills.md#the-skill-handler) for the block. A skill needs a portable `name`, which the model sees with its `description`, and has no triggers, `session`, `tool` block, or `tools` and `skills` lists. Its `config` is `{}`.

## Loading a skill

A load is a call through `invokeAction` with an empty input object. It returns exactly the instructions and examples of the version it names, and its execution commits or rolls back with the caller's transaction. An agent can load only the skill versions its invocation resolved. An agent's loads of one skill version within one invocation share one identity, so repeating a load returns the same execution; a retried invocation loads again, from the version it resolves.

## Tools a skill makes available

A skill's `tools` lists the tools its procedure uses, each with a `name` and optionally a `version`, and no `input` or `approval`. When an agent loads the skill, those tools 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. The load's `invocation.tools` lists the tool versions it made available, which leaves out a tool the agent lists itself and one an earlier load made available at a pinned version. The agent's `invocation.tools` lists them after its own references, each with the version its calls used, and each call to one of them names the load in `skillLoadExecutionId`.

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 tool in its own `tools`, the agent's reference applies instead, with its version, fixed input, and approval. When two loaded skills list the same tool, a pinned version wins over the latest one, and two different pinned versions fail the second load. In a session, later turns keep the tools of the skills the session has loaded, each at its reference's version or its latest one. A turn leaves out a kept tool that no longer fits the agent's tools, such as one whose latest version now has the name of one of the agent's tools or skills, and a `harness.log` warning in the turn's transcript says why.

## Skill references

`skills` lists, in order, the skills an action may load.

| Field     | Type      | Meaning                                                                                                                                                                    |
| --------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`    | `String!` | Registry name of the skill action, which must have kind `skill`.                                                                                                           |
| `version` | `Int`     | The skill version to load. Omit it to load the skill's latest version.                                                                                                     |
| `preload` | `Boolean` | Load the skill at the start of every turn and place its guidance in the agent's instructions. Agents only, at most 8 per agent. See [Preloaded skills](https://www.twisp.com/docs/reference/actions/skills.md#preloaded-skills). |

When the definition is written, each name resolves to the skill's action, and reads return it as `actionId`. A missing, duplicate, disabled, or deleted skill, an action that is not a skill, a `version` the skill does not have, or a skill whose name is also the name the model sees for one of the action's tools fails the write. Versions follow the [tool rule](https://www.twisp.com/docs/reference/actions/tools.md#versions): a reference with a `version` always loads that version, and one without loads the skill's latest version, resolved when each execution starts, so editing a skill reaches such an action at its next invocation or turn. Like `tools`, a `skills` list is accepted only by handler kinds that call tools. Declaring a skill makes it available; it is not a record that the skill was used.

### Preloaded skills

A skill the agent always needs can be preloaded with `preload: true`. At the start of every turn, and of every invocation of an agent without a session, the agent loads each preloaded skill, in the order of `skills`, before its first model call. Each is an ordinary load of the version the turn resolved, with its own execution and the turn's own `SKILL` use, never a reused one. Its guidance follows the agent's `prompt` in the agent's instructions, where it stays the same from turn to turn until the skill changes, and the tools it lists are offered from the turn's first model call. The skill is not listed for the model to load; if other skills are listed and the model asks for a preloaded one anyway, the load returns the turn's preload. The transcript records each preload as a `skill.preload` event before the turn's first model call. A preload does not count against `limits.tool_calls`. A replay preloads the version the original turn did, under a load of its own.

## Output uses

An invocation's `uses` lists the tool answers and skill guidance its handler reported supplying to it; for an agent, Twisp derives them from its calls (see [Agent uses](https://www.twisp.com/docs/reference/actions/agents.md#agent-uses)). Each use names the committed call or load that produced the output and the version of that execution holding it. A use of output carried forward from earlier is marked `reused` and keeps its original producer. A session turn can reuse only output produced in earlier turns of the same session, and an execution of an action without sessions only output from its own earlier invocations; finalizing with any other reused output fails with `reuse_out_of_scope`. A failed call, a rolled-back load, and a declared but unreported tool or skill never appear as uses. A use records what was supplied, not whether it was followed.

| Field              | Type                   | Meaning                                                                                                                  |
| ------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `role`             | `ActionOutputUseRole!` | `TOOL`, `SKILL`, or `RETRIEVED` for an agent's memory recall, memory search, or context retrieval.                       |
| `actionId`         | `UUID!`                | The tool or skill action that produced the output.                                                                       |
| `actionVersion`    | `Int!`                 | The version that produced it.                                                                                            |
| `executionId`      | `UUID!`                | The producing call or load.                                                                                              |
| `executionVersion` | `Int!`                 | The version of the producing execution that holds the output.                                                            |
| `reused`           | `Boolean!`             | True when the output was produced by an earlier invocation of the same execution or an earlier turn of the same session. |
| `execution`        | `ActionExecution`      | The producing execution at `executionVersion`, subject to your read permissions.                                         |
| `action`           | `Action!`              | The tool or skill at `actionVersion`.                                                                                    |

## The `skill` handler

Returns the instructions and curated examples in its `skill` block; see [Skills](https://www.twisp.com/docs/reference/actions/skills.md). A skill needs a `name`, has no triggers, `session`, or `tool` block, and its `config` is `{}`. `instructions` is required and holds at most 65,536 characters; `examples` is optional and holds at most 20 examples of at most 4 KiB each. Each example has a non-empty `situation` and `resolution`, and optionally a `reason` and a `source` naming an `actionId` and a non-empty `sessionId`. `tools` lists the [tools a load makes available](https://www.twisp.com/docs/reference/actions/skills.md#tools-a-skill-makes-available). Loading takes an empty input object, and returns the instructions and examples, with `examples` an empty list when there are none.

```graphql
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" }]
}
```