---
title: Runbooks reference
description: Authoring and execution reference for ThinkWork-published Computer runbooks.
---

Computer runbooks are standard Agent Skill directories. ThinkWork-published starters live in `packages/skill-catalog/<slug>/` and are marked with `metadata.thinkwork_kind: computer-runbook` in `SKILL.md`.

```text
packages/skill-catalog/crm-dashboard/
  SKILL.md
  references/
    thinkwork-runbook.json
    discover.md
    analyze.md
    produce.md
    validate.md
  assets/
    crm-dashboard-data.schema.json
```

## Skill shape

`SKILL.md` is the skill entrypoint and discovery surface. A Computer-runbook-capable skill must include:

```yaml
---
name: crm-dashboard
description: Build an opinionated CRM dashboard app.
execution: context
metadata:
  thinkwork_kind: computer-runbook
  thinkwork_runbook_contract: references/thinkwork-runbook.json
---
```

`references/thinkwork-runbook.json` is the machine-readable contract Computer needs before loading every skill file:

| Field          | Purpose                                                        |
| -------------- | -------------------------------------------------------------- |
| `routing`      | explicit aliases, trigger examples, and confidence hints       |
| `inputs`       | user, context, or system inputs expected by the runbook        |
| `confirmation` | Confirmation-card copy for auto-selected runs                  |
| `phases`       | ordered phase ids, titles, guidance paths, roles, dependencies |
| `outputs`      | expected artifacts, summaries, evidence, datasets, or maps     |
| `assets`       | schemas, layout recipes, examples, or validation fixtures      |
| `overrides`    | fields future operators may safely edit                        |

Minimal phase example:

```json
{
  "id": "produce",
  "title": "Produce dashboard artifact",
  "guidance": "references/produce.md",
  "capabilityRoles": ["artifact_build"],
  "dependsOn": ["analyze"],
  "taskSeeds": [
    "Generate an interactive dashboard using the runbook phase guidance.",
    "Persist the dashboard through save_app with runbook metadata."
  ]
}
```

## References and Assets

Phase Markdown under `references/` is execution guidance. It should be specific enough for the runtime to execute one task at a time without inventing a new plan.

Good phase Markdown includes:

- source and evidence handling rules
- output shape or artifact metadata requirements
- capability-specific constraints such as `MapView` for map artifacts
- save and validation expectations
- what to do with missing or partial data

Do not put secrets, tenant-specific credentials, or concrete specialist agent names in phase Markdown.

Use `assets/` for output-shaping material such as JSON schemas, example payloads, layout recipes, and validation fixtures. Artifact-producing runbooks should keep these contracts outside `SKILL.md` so agents can progressively load only the detail needed for the current phase.

## Routing rules

Explicit invocation starts directly when the prompt names the runbook, slug, display name, or one of its explicit aliases.

Auto-selection uses deterministic API-side scoring over trigger examples and confidence hints. High-confidence auto-selection creates an `awaiting_confirmation` run and a `data-runbook-confirmation` part. Ambiguous or no-match prompts fall back to normal Computer execution.

## Run lifecycle

| State                   | Meaning                                               |
| ----------------------- | ----------------------------------------------------- |
| `awaiting_confirmation` | auto-selected run waiting for user approval           |
| `queued`                | approved or explicit run has a `runbook_execute` task |
| `running`               | runtime is executing current expanded task            |
| `completed`             | every required task completed                         |
| `failed`                | execution failed and recorded an error                |
| `cancelled`             | user cancelled run; later tasks must not continue     |
| `rejected`              | user rejected auto-selected run before execution      |

Every run stores `definitionSnapshot` so catalog changes do not rewrite history.

## UIMessage data parts

Runbook UI uses the AI SDK `data-${name}` extension point:

| Part type                   | Used for                                    |
| --------------------------- | ------------------------------------------- |
| `data-runbook-confirmation` | auto-selected approval card                 |
| `data-runbook-queue`        | phase/task progress, including ad hoc plans |

Stable ids matter. Queue updates for the same run should reuse `runbook-queue:<runId>` so the Computer client replaces the existing queue card instead of appending duplicates.

## Smoke coverage

Use the runbook smoke script after deploying a stack with the runbook migrations and GraphQL API:

```sh
node scripts/smoke/computer-runbook-smoke.mjs
SMOKE_ENABLE_COMPUTER_RUNBOOKS=1 node scripts/smoke/computer-runbook-smoke.mjs
```

Dry-run mode validates the repo-authored runbook-capable skills and expected part names. Live mode exercises:

- auto-selected `map-artifact` confirmation before execution
- explicit `crm-dashboard` Queue without confirmation
- explicit `research-dashboard` Queue plus cancellation
- no-match prompt avoiding a published runbook run

Live mode accepts `SMOKE_TENANT_ID`, `SMOKE_COMPUTER_ID`, and `SMOKE_USER_ID`; otherwise it selects the most recently updated owned Computer.
