Skip to content

Playbooks (skills)

A playbook defines a capability that a goal can invoke within its team. Its executable definition declares the inputs, steps or planning constraints, permitted operations, and output contract. Its skill supplies the agent with instructions and supporting files for performing that work. Together they describe a capability a harness can load, validate, and run.

A persona defines one or more teams. Each goal belongs to a team and invokes playbooks available to that team. The harness runs the selected revision with the destination workspace’s models, connector grants, and approval policy. The same definition can be reused by another team with its own bindings. Goals · Teams

  1. Define the work. Identify the playbook by a stable key and revision. Declare the required inputs, expected results, permitted operations, and any decisions that require review.
  2. Package the agent’s instructions. Use SKILL.md to describe how to perform the work and when the capability applies. Include references, assets, and checks when the instructions depend on them. The same skill can be reused in another playbook whose contract and permissions support it.
  3. Version the definition and skill together. A run resolves both to exact revisions. When a team adopts that revision, the workspace supplies its own authorized accounts, credentials, compute, and approval rules. Portable playbook contract

For example, Verify signals accepts an organization and date range and returns findings with evidence. The workflow reads a declared source. Its skill defines what counts as a dated signal and which citations to retain. An eval checks that unsupported findings remain unknown. Another team can adopt the same playbook and bind the source requirement to its own authorized research connection.

An authoring tool can present the executable definition and the playbook’s own skill as a single revision for review. The harness validates that revision before adopting it. Review should surface changes to inputs, outputs, privileges, dependencies, and executable files, since they can affect the callers and permissions of the installed playbook.

The executable definition and skill contents are identified by the package profile. In the version 2 profile, playbook.json is the entry. An included Agent Skill has its own root containing SKILL.md. The other files below are optional and are loaded or invoked according to the definition.

Path or declaration Purpose
playbook.json Versioned executable definition and runtime requirements. Equivalent YAML may be accepted as authoring input.
SKILL.md Agent Skills instructions in Markdown with name and description in YAML frontmatter.
references/ Supporting instructions or reference data the agent can load when needed.
assets/ Templates, examples, and other resources addressed relative to the skill root.
scripts/ and runtime.scripts Script files and explicit declarations of when and how the harness may invoke them.
evals/evals.json One convention for recording test inputs and expected behavior.

The Agent Skills specification defines the skill folder. The playbook profile defines how the harness binds that folder to the executable and governs scripts. Portable playbook definition · Evals

---
name: verify-signals
description: Verify dated public buying signals and return their source links.
---
Use the evidence rules in references/evidence-rules.md.
Record the source and date for every reported signal.

The skill directory matches the metadata name, verify-signals. The relative path resolves within that skill’s pinned files.

The harness supplies the instructions from the pinned skill and allows access only to referenced files within the run’s scope. A script requires a declared entry point and an execution policy. If a playbook delegates to another playbook, the child runs its own pinned definition and skill with the inputs and permissions allowed for that call. References and assets · Script execution

Owned files are versioned with the playbook. An external skill remains a separate dependency identified by an immutable source and a content digest. The harness should verify the dependency before adoption and resolve the reviewed content at run time. A skill can declare the tools it needs. Access to those tools comes from destination workspace grants. External skills

Declare the agent’s instructions, model capabilities, tools, and any requirements for isolation, realtime interaction, or delegation. Guardrails, human decisions, session continuity, and tracing are also part of the execution contract. The harness checks whether it can enforce the required behavior with the destination’s bindings and reports what must be configured or supported before a run can begin.

A team can select a coordinator for its goal. Individual playbooks can declare compatible execution targets and use their own permitted bindings. Changing the coordinator leaves each invoked playbook subject to its own contract. Runtime compatibility

In the structured definition profile, a playbook has a stable key, a positive revision, and a kind. The inputs describe values the caller supplies, requirements declare external operations, and outputFields identify the values returned to the caller. The harness validates the declared inputs and outputs at the corresponding run boundaries.

Each step has a unique identifier. In this profile, dependsOn identifies preceding steps whose results must be available. A harness validates step references and rejects cyclic playbook dependencies. A child playbook receives explicitly mapped inputs and returns only its declared outputs.

In the Meeting desk fixture, the calendar requirement provides a logical upcoming operation. The step maps the dates from the run input and selects meetings from the result. These mappings use JSON Pointers. The workspace supplies and authorizes the calendar binding.

{
"id": "read",
"title": "Read upcoming meetings",
"instruction": "Read only the selected time window.",
"dependsOn": [],
"type": "connector_operation",
"operation": {
"requirementId": "calendar",
"operationId": "upcoming",
"values": {
"from": "/input/from",
"until": "/input/until"
},
"effect": "read"
},
"inputMappings": {},
"outputFields": {
"meetings": "/meetings"
},
"requiresApproval": false
}
Step type in this profile Behavior
reason Invokes a model with the step’s authorized context.
connector_operation Runs a declared read, write, or process through a workspace binding.
playbook Invokes a pinned child with explicit input and output mappings.
wait_until Suspends execution until the declared time.
publish_page, publish_list Publishes mapped fields to an authorized workspace destination.

The step’s requiresApproval flag expresses a requirement from the definition. Workspace policy can still require review, and the read still needs a valid grant. Connector requirements · Meeting desk fixture

A saved goal playbook defines an objective and the playbooks the harness may use to plan the work. Each invocation stays in its team. A graph-based profile can encode stages, handlers, and review points as its executable definition. A package declares the profile its entry requires so the destination can check that its runtime can interpret it. Saved goal playbooks · Package entry files

Gabriel implements team-scoped playbook execution and versions the executable with its skill. Its Advanced Skill Editor provides one authoring interface for the files, dependency review, and runtime requirements described here. Portable playbooks