Write Template Playbooks

Write a template playbook

A playbook is one markdown file under references/agent-templates/<key>.md in the build-an-agent skill. The builder agent reads the one that matches the user's ask, then follows it to configure that specific agent. Your job: encode the use-case thinking so a Sonnet-class model can execute it. You get one inventory row as input (name, one-line pitch, integrations, trigger). Turn it into a spec-conforming playbook.

Keep each playbook 1 to 2 KB. An over-comprehensive playbook hurts: the agent cannot extract what is relevant. Write a coherent, moderately detailed unit with a working instructions template.

The skeleton

Fill this in. Omit any section the use case does not need (a no-tool template drops Explore and Connections; a no-trigger template drops the trigger half of Verify).

# <Template name> playbook

## Match
One line: when this playbook applies. The card key plus the shape of the ask, including
free-text asks that match no card.

## Required context (ask via one request_input form)
- <field>: why the agent cannot proceed without it. When the agent can propose a value, set
  it as the field's `default` (prefilled, one-click acceptable); no default otherwise. [required]
Only fields the agent genuinely cannot proceed without. One to four. Secrets never go here.

## Researchable context (do not ask; figure it out and state the assumption)
- <field>: what the agent looks up, and what it assumes when the lookup is inconclusive. Never
  a question and never an enum. The platform prompt forbids asking for a detail the agent can
  look up or default, so this section names the lookup and the fallback assumption instead.

## Explore first (read before proposing)
- Which read tools to discover_tools and wire.
- One test_run passing the uncommitted tools in delta.set.parameters.agent.tools (the FULL
  tools list), to see the real repo or workspace. Show the user a concrete example before
  committing the full setup.

## Defaults / priors table (situation to proposed setup)
| Situation | Trigger | Tools | Behavior default |
|---|---|---|---|
| <situation> | <trigger> | <reads> + <write> | <what it does> |

## Connections
Which integrations must be ready. If missing, request_connection and stop. List the
tool-agnostic alternatives (Notion OR Confluence OR Google Drive).

## Instructions template (what to commit)
The numbered per-run procedure for instructions.agents_md: exact tools in order, pinned ids,
ending on the terminal action. Include the output-format shape.

## Verify
1. test_run with a blunt test message; read the verdict and the tools line, not a 200.
2. If a trigger: fire an artificial test message first; then ask the user to run the real
   trigger test (Lightning "Test event" for a subscription, Play "Run" for a schedule).

## Closing report
What the agent became, what is connected, what is scheduled, what you verified, what still
needs the user.

Every section maps to the build loop: Match to step one, Required and Researchable to request_input, Explore to discover_tools plus test_run, Defaults to the proposal, Connections to request_connection, Instructions to commit_revision, Verify to test_run and the trigger test, Report to the final step.

Three platform facts authors get wrong

These are counterintuitive and every first draft gets them backwards. State them correctly.

1. request_input HAS a real default field (#5190, shipped) — use it. A field's default prefills the form so the user can accept every proposal in one click; set one whenever the agent can propose a value. Rules: the default must match the field type (array of strings on a multi-select); an empty default (""/[]) means "no proposal" and is stripped; date/date-time fields ignore defaults — do not set them there. For a researchable choice, include a "Figure it out, use your best judgment" enum option and set it as the default. Enum options are SUGGESTIONS: every enum renders a built-in "Other…" free-text escape hatch, so keep lists short and likely, not exhaustive. Multi-pick questions use {type: "array", items: {type: "string", enum: [...]}}; options needing a sentence of explanation use oneOf: [{const, title, description}], which renders as selectable choice cards. Forms with several questions can set "x-ag-stepper": true on requestedSchema (one question at a time + review) — the tool description teaches this; playbooks do not re-state it.
2. test_run exercises uncommitted tools through its in-memory delta (delta.set.parameters.agent.tools carries the FULL tools list, lists replace wholesale). So exploration does NOT require commit-and-stop-turn. Explore the real repo or workspace with new tools before committing anything. Commit-and-stop is only a fallback for when the flow cannot carry the delta.
3. The trigger-test affordance is Lightning "Test event" (event subscriptions) or Play "Run" (schedules). It is never a flask icon. The flask is for Evaluations. Write the correct copy in every Verify section.

What a playbook NEVER contains

Add what the model lacks for this use case; omit what it already knows. Do not put in a playbook:

• The generic build loop (discover, commit, test). It lives in the build-an-agent skill body.
• The config schema (tool entries, the fixed llm/harness/runner block). It lives in the skill body and references/config-schema.md.
• Tool wire shapes or cron rules. Those live in the skill body and its other references.

A playbook that re-teaches these wastes the 1-2 KB budget and drifts from the source of truth.

Read a reference when

The canonical file format and the index.md match-table format are in the project spec at docs/design/agent-workflows/projects/agent-templates/playbook-spec.md. Read it if the skeleton above is not enough.