Skills

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 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.

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: 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). 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.

The skill handler

Returns the instructions and curated examples in its skill block; see Skills. 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. Loading takes an empty input object, and returns the instructions and examples, with examples an empty list when there are none.

Copyskill: {
  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" }]
}