Portable playbooks
A portable playbook packages a workflow, its agent instructions, and the requirements a compatible harness must satisfy to run it. A goal belongs to a team and invokes the playbook within that team. The playbook defines the work and the privileges it needs. The destination workspace supplies the model and connector bindings, compute, permissions, and approval authority.
This draft specifies behavior a harness can implement and a versioned package profile for exchanging definitions. Requirements apply to the capabilities a playbook declares. A harness can support a subset and must report when it cannot satisfy a requirement. Specification conventions and runtime rules
The playbook definition
Section titled “The playbook definition”The version 2 package profile uses playbook.json as its entry and sets the entry’s schemaVersion to 2. The nested definition contains the structured or goal workflow and its runtime block. The entry can also point to the playbook’s included skill directory. A harness that accepts YAML authoring input must normalize equivalent JSON and YAML to the same definition before fingerprinting. The profile rejects duplicate mapping keys, YAML aliases and tags, and remote schema references.
| Declaration | What the harness resolves or enforces |
|---|---|
| Workflow | Stable key and revision, typed inputs and outputs, plus structured steps or goal planning constraints |
runtime.targets and runtime.agent |
Compatible targets, agent instructions, role, and model requirements |
runtime.skills and runtime.scripts |
Pinned external skill content and the permitted executable entry points |
runtime.tools and runtime.delegation |
Logical operations, input and output schemas, and permitted specialist calls or handoffs |
runtime.execution and runtime.guardrails |
Execution profile, voice mode when applicable, and checks at input, tool, or output boundaries |
runtime.approvals, runtime.session, and runtime.tracing |
Protected effects, continuity policy, and execution metadata |
Model identifiers in the profile describe what a target should run. Connector requirements identify logical operations. The workspace maps those requirements to authorized accounts and deployment resources. Credentials, local binding identifiers, run history, and approvals stay with the workspace. Binding
Package layout
Section titled “Package layout”This profile uses an npm archive and the gabriel-package.json manifest. Its runtime.contract value is gabriel-studio-v2. The manifest identifies the entry and any pinned playbook dependencies. These names identify the exchange format. An independent harness can implement the same format with its own runtime services.
package.jsongabriel-package.jsonplaybook.jsonskills/verify-signals/ SKILL.mdThis tree shows the downloadable fixture. An included skill can also carry references, assets, declared scripts, and evals. Package manifest schema · Skill files
An exact package pin
Section titled “An exact package pin”A dependency pin identifies a registry, scoped package name, exact version, and SHA-512 archive integrity. A harness verifies each dependency against its pin before accepting the package. The Verify signals pin has an illustrative package name and describes the bytes of the downloadable fixture. An actual registry release needs its own resolvable identity and digest. Example archive · Exact pin
Legacy playbooks
Section titled “Legacy playbooks”A team can pin a version 1 or version 2 release when the destination supports its declared contract. Adopting a different profile requires a new reviewed revision. Review the executable, skill files, requirements, and lifecycle hooks as part of migration. Existing runs retain the revision and bindings recorded for them. Graphs or commands with different execution semantics require a compatible runtime or an explicit conversion.
External skills
Section titled “External skills”A playbook may package an owned skill or declare external Agent Skills as immutable dependencies. The version 2 profile accepts a GitHub repository, full commit, and skill directory, or an npm registry package pin with an optional skill directory. A complete skill pin also carries a logical ID and the content digest of the resolved files. Agent Skills specification
This example shows the source portion of a GitHub pin.
{ "kind": "github", "owner": "example-org", "repository": "approved-skills", "commit": "0123456789abcdef0123456789abcdef01234567", "path": "skills/verify-signals"}Before adopting a dependency, the harness should make its source, license, files, declared tools, and executable entry points available for review. It must use the reviewed bytes and verify their digest at resolution time. Public releases in this profile require publicly resolvable dependencies. The destination still decides which declared tools the skill may use.
References and assets
Section titled “References and assets”References contain material the agent can consult. Assets can include templates, schemas, and fixtures. Resolve a requested path relative to the pinned skill root and reject paths outside it. A runtime can load files on demand within the run’s allowed scope. Live records and connector data are accessed through authorized workspace services. Playbook skill files
Review and run scripts
Section titled “Review and run scripts”An executable needs an explicit declaration. In this profile, each runtime.scripts entry specifies an ID, relative path, interpreter, invocation event, input and output schemas, and timeout. BeforeTask and AfterTask are lifecycle boundaries. A tool entry is callable by the playbook under its declared permissions. The profile supports Node and Python, with a JSON object passed on standard input and a bounded JSON object returned on standard output.
Execute only reviewed entry points. Isolate each invocation with the required interpreter and prepared dependencies, constrain its files and resources, and keep outbound network, credentials, and connector access disabled. Validate input before invocation and output before accepting the result. Missing compute or interpreter support blocks the affected work. A failed check blocks progression. Reconcile uncertain attempts before retrying. Code execution · Lifecycle hooks
Installation and execution lifecycle
Section titled “Installation and execution lifecycle”- Resolve and validate. Verify package integrity, the declared contract, skill digests, and exact dependency pins. Reject unsafe archive paths, unresolved dependencies, and cycles.
- Bind and check readiness. Resolve the playbook’s logical requirements to local grants, models, compute, and output destinations. Report missing bindings and unsupported capabilities before dispatch.
- Start a team-scoped run. When a goal invokes the playbook, record the definition and skill revisions, selected target and model, and workspace binding identifiers. Evaluate the run against that snapshot and current permissions.
- Govern external effects. Derive the operation, arguments, destination, and acting account from the bound request. Rehearse when required, obtain the applicable human approval, and recheck the reviewed proposal and current grants before live dispatch.
- Record and reconcile. Preserve the decision, outcome, and receipt under the run’s identity. Use the original invocation identity to resolve an uncertain dispatch before any retry. Governed execution · Execution receipts
Runtime compatibility
Section titled “Runtime compatibility”A harness checks the saved definition and its effective workspace bindings against the selected runtime. Its report should distinguish capabilities the adapter provides directly from those the surrounding harness enforces. Identify each missing prerequisite or unsupported requirement and hold execution when a required behavior cannot be enforced. A supported runtime target does not by itself establish that a particular account, model, or workspace is ready. Capability reports
Agents
Section titled “Agents”An agent profile defines instructions, a role, and model requirements. The runtime binds a compatible model and supplies only the authorized input and context. Validate input at invocation and output before returning it to the caller. Agents
Sandbox agents
Section titled “Sandbox agents”An agent sandbox isolates the agent’s workspace and constrains file, network, and credential access. Its policy must cover the files and actions exposed to the selected runtime. A rehearsal also requires isolation, with controls that prevent the proposed operation from reaching production. Code execution · Sandbox rehearsal
Realtime agents
Section titled “Realtime agents”A realtime profile declares the required speech mode and transcript policy. Native speech streams audio to a compatible model. Transcribed speech converts input to text and renders the response as speech. The runtime must enforce the declared retention policy and preserve action identity across interruptions or reconnects. Realtime interactions use the same grants and approval boundary as other invocations. Coach and computer use
Agents as tools and handoffs
Section titled “Agents as tools and handoffs”A specialist call runs a declared child and returns its accepted result to the caller. A handoff transfers responsibility for the next response to the declared specialist. In both cases, the harness passes only the authorized fields and applies the child’s own pinned definition, skill, and checks within the caller’s permission ceiling. Delegation
A tool declares an input schema, output schema, and effect. A connector tool also names the logical requirement and operation it invokes. Dispatch requires a destination binding that grants the operation. Validate the request and evaluate the declared effect and approval rules before execution. Tools
Guardrails
Section titled “Guardrails”Evaluate input checks before using the input, tool checks before dispatch, and output checks before releasing the result. The selected runtime must enforce the required checks at their declared boundaries. Evals can cover invalid inputs, forbidden operations, and results that fail the output contract. Evals
Human in the loop
Section titled “Human in the loop”The workspace determines who can resolve a judgment call or authorize a protected effect. Approval applies to the reviewed proposal, including the operation, arguments, destination, and acting account. Material changes require a new review. Preserve rehearsal evidence and the decision with the corresponding run. Governed execution · Approvals
Sessions
Section titled “Sessions”Keep a durable run checkpoint with the original playbook and pending decisions. A provider session handle can help resume provider work. Cross-run continuity depends on the declared conversation policy and a fresh authorization check on any carried context. Protected effects in the new run require their own approvals. Context and conversations
Tracing
Section titled “Tracing”Tie decisions, tool events, handoffs, approvals, and receipts to a stable run identity. Provider session or turn IDs can be used to correlate external events. Trace metadata should omit sensitive payloads by default. The effect receipt records the outcome of live dispatch. Runs · Execution receipts
Gabriel reference implementation
Section titled “Gabriel reference implementation”Gabriel implements this package profile and checks each playbook against a native runtime or a configured OpenAI, Claude, or Google adapter. Workspace policy governs actions across those adapters. Gabriel reference implementation