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.
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.
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.
- 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
| To do this |
Read |
| Get the prompting rules for procedure, priors, forms, and verification |
references/prompting-checklist.md |
| Copy from a complete, spec-conforming example |
references/worked-example.md |
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.
1---2name: write-template-playbooks3description: >-4 Write a template playbook for the build-an-agent skill: a 1-2 KB per-use-case file that5 teaches the builder agent to configure one kind of Agenta agent (changelog writer, issue6 triager, support router, and so on). Use when the ask is "write a template playbook", "add7 an agent template", "author a playbook for the build-an-agent skill", or "write the <X>8 playbook". Encodes the file format, the prompting checklist, and the platform facts authors9 get wrong.10allowed-tools: Read, Edit, Write, Grep, Glob, Bash11user-invocable: true12metadata:13 source: https://skillmd.com/skills/agenta-ai/write-template-playbooks14---1516# Write a template playbook1718A playbook is one markdown file under `references/agent-templates/<key>.md` in the19build-an-agent skill. The builder agent reads the one that matches the user's ask, then follows20it to configure that specific agent. Your job: encode the use-case thinking so a Sonnet-class21model can execute it. You get one inventory row as input (name, one-line pitch, integrations,22trigger). Turn it into a spec-conforming playbook.2324Keep each playbook **1 to 2 KB**. An over-comprehensive playbook hurts: the agent cannot25extract what is relevant. Write a coherent, moderately detailed unit with a working26instructions template.2728## The skeleton2930Fill this in. Omit any section the use case does not need (a no-tool template drops Explore and31Connections; a no-trigger template drops the trigger half of Verify).3233```markdown34# <Template name> playbook3536## Match37One line: when this playbook applies. The card key plus the shape of the ask, including38free-text asks that match no card.3940## Required context (ask via one request_input form)41- <field>: why the agent cannot proceed without it. When the agent can propose a value, set42 it as the field's `default` (prefilled, one-click acceptable); no default otherwise. [required]43Only fields the agent genuinely cannot proceed without. One to four. Secrets never go here.4445## Researchable context (do not ask; figure it out and state the assumption)46- <field>: what the agent looks up, and what it assumes when the lookup is inconclusive. Never47 a question and never an enum. The platform prompt forbids asking for a detail the agent can48 look up or default, so this section names the lookup and the fallback assumption instead.4950## Explore first (read before proposing)51- Which read tools to discover_tools and wire.52- One test_run passing the uncommitted tools in delta.set.parameters.agent.tools (the FULL53 tools list), to see the real repo or workspace. Show the user a concrete example before54 committing the full setup.5556## Defaults / priors table (situation to proposed setup)57| Situation | Trigger | Tools | Behavior default |58|---|---|---|---|59| <situation> | <trigger> | <reads> + <write> | <what it does> |6061## Connections62Which integrations must be ready. If missing, request_connection and stop. List the63tool-agnostic alternatives (Notion OR Confluence OR Google Drive).6465## Instructions template (what to commit)66The numbered per-run procedure for instructions.agents_md: exact tools in order, pinned ids,67ending on the terminal action. Include the output-format shape.6869## Verify701. test_run with a blunt test message; read the verdict and the tools line, not a 200.712. If a trigger: fire an artificial test message first; then ask the user to run the real72 trigger test (Lightning "Test event" for a subscription, Play "Run" for a schedule).7374## Closing report75What the agent became, what is connected, what is scheduled, what you verified, what still76needs the user.77```7879Every section maps to the build loop: Match to step one, Required and Researchable to80`request_input`, Explore to `discover_tools` plus `test_run`, Defaults to the proposal,81Connections to `request_connection`, Instructions to `commit_revision`, Verify to `test_run`82and the trigger test, Report to the final step.8384## Three platform facts authors get wrong8586These are counterintuitive and every first draft gets them backwards. State them correctly.87881. **`request_input` HAS a real `default` field (#5190, shipped) — use it.** A field's89 `default` prefills the form so the user can accept every proposal in one click; set one90 whenever the agent can propose a value. Rules: the default must match the field type91 (array of strings on a multi-select); an empty default (`""`/`[]`) means "no proposal" and92 is stripped; **date/date-time fields ignore defaults** — do not set them there. For a93 researchable choice, include a "Figure it out, use your best judgment" enum option and set94 it as the `default`. Enum options are SUGGESTIONS: every enum renders a built-in "Other…"95 free-text escape hatch, so keep lists short and likely, not exhaustive. Multi-pick96 questions use `{type: "array", items: {type: "string", enum: [...]}}`; options needing a97 sentence of explanation use `oneOf: [{const, title, description}]`, which renders as98 selectable choice cards. Forms with several questions can set `"x-ag-stepper": true` on99 requestedSchema (one question at a time + review) — the tool description teaches this;100 playbooks do not re-state it.1012. **`test_run` exercises uncommitted tools** through its in-memory delta102 (`delta.set.parameters.agent.tools` carries the FULL tools list, lists replace wholesale).103 So exploration does NOT require commit-and-stop-turn. Explore the real repo or workspace104 with new tools before committing anything. Commit-and-stop is only a fallback for when the105 flow cannot carry the delta.1063. **The trigger-test affordance is Lightning "Test event"** (event subscriptions) or Play107 "Run" (schedules). It is never a flask icon. The flask is for Evaluations. Write the correct108 copy in every Verify section.109110## What a playbook NEVER contains111112Add what the model lacks for this use case; omit what it already knows. Do not put in a113playbook:114115- The generic build loop (discover, commit, test). It lives in the build-an-agent skill body.116- The config schema (tool entries, the fixed `llm`/`harness`/`runner` block). It lives in117 the skill body and `references/config-schema.md`.118- Tool wire shapes or cron rules. Those live in the skill body and its other references.119120A playbook that re-teaches these wastes the 1-2 KB budget and drifts from the source of truth.121122## Read a reference when123124| To do this | Read |125|---|---|126| Get the prompting rules for procedure, priors, forms, and verification | `references/prompting-checklist.md` |127| Copy from a complete, spec-conforming example | `references/worked-example.md` |128129The canonical file format and the index.md match-table format are in the project spec at130`docs/design/agent-workflows/projects/agent-templates/playbook-spec.md`. Read it if the131skeleton above is not enough.