Run Playbooks as Claude Code Routines

Claude Code Routines run Claude Code sessions autonomously on Anthropic-managed cloud infrastructure — on a schedule, by HTTP POST, or in response to GitHub events. PLAYBOOK.md files work cleanly as the “prompt” for a routine. This guide shows the zero-code recipe.

When to reach for this

Nightly or weekly reports — schedule a routine to execute an analytics / drift / summary playbook.
On-demand triage — fire a routine from your monitoring or alerting system, passing alert context as the text body.
Repository automation — trigger on pull_request.opened or release.published to run a review or notes playbook.

Compared to running playbooks locally or via the MCP server in an interactive session, routines add autonomous cloud execution, persistent triggers, and a shareable run history — at the cost of losing interactive @elicit pauses (see Limitations).

Three-step setup

1. Commit your playbook

Place your .playbook.md in a repo the routine will clone. Recommended layout:

your-repo/
├── playbooks/
│   └── my-workflow.playbook.md
└── .claude/
    └── skills/
        └── playbook-run/
            └── SKILL.md

2. Commit the `playbook-run` skill

Claude Code cloud sessions automatically load skills committed to the cloned repo. Commit the published skill so your routine’s run session knows the full PLAYBOOK.md execution algorithm — context accumulation, directive processing, branching, autonomous-mode defaults — without inline instructions.

mkdir -p .claude/skills/playbook-run
curl -o .claude/skills/playbook-run/SKILL.md \
  https://raw.githubusercontent.com/PLAYBOOK-MD/playbook-integrations/main/skills/playbook-run/SKILL.md
git add .claude/skills/playbook-run/SKILL.md
git commit -m "chore: add playbook-run skill for Claude Code sessions"

3. Create the routine

At claude.ai/code/routines, click New routine:

Repository — the repo from step 1.
Connectors — attach any MCPs referenced by @tool or @prompt(mcp:…) in the playbook.
Environment — the default environment is fine for most playbooks; add env vars if your playbook references them.
Prompt — use a template from the Prompt templates section below.
Trigger — schedule, API, and/or GitHub event (one routine can combine multiple triggers).

That’s it. On each fire, the routine clones the repo, loads the skill, reads the playbook, and executes it step by step.

Prompt templates

Scheduled trigger

Bake input values directly into the prompt — scheduled triggers don’t pass a per-run body.

Execute the workflow defined in ./playbooks/my-workflow.playbook.md per the
PLAYBOOK.md specification. Use the `playbook-run` skill from this repository.

Inputs:
  topic: "Q2 product launch"
  audience: "executive"
  word_count: 1500

If an @elicit directive is encountered, use autonomous-mode defaults:
confirm -> "yes"; select -> first option; input -> "".

Write the final artifact to ./out/{{yyyy-mm-dd}}.md and push to a claude/
branch with a descriptive commit message.

API trigger

API triggers receive a text body on each /fire. Marshal inputs and elicit overrides into a structured payload.

Execute the workflow defined in ./playbooks/my-workflow.playbook.md per the
PLAYBOOK.md specification. Use the `playbook-run` skill from this repository.

The POST body ({{text}}) is a YAML document with:
  inputs:
    topic: string
    audience: string
    word_count: number
  elicit:
    <step_number>: <response>   # optional overrides

Parse {{text}}, apply any elicit overrides (use defaults otherwise), and
execute the playbook. Write the final artifact to ./out/<run-id>.md.

Call it with:

curl -X POST https://api.anthropic.com/v1/claude_code/routines/<ID>/fire \
  -H "Authorization: Bearer $ROUTINE_TOKEN" \
  -H "anthropic-beta: experimental-cc-routine-2026-04-01" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"text": "inputs:\n  topic: AI safety\n  audience: technical\n  word_count: 1500\n"}'

GitHub trigger

The routine form lets you subscribe to pull_request or release events with filters. Use event context directly in the prompt.

Execute the workflow defined in ./playbooks/review-pr.playbook.md per the
PLAYBOOK.md specification. Use the `playbook-run` skill from this repository.

The triggering event is a pull_request. Inputs:
  pr_number: {{pr.number}}
  pr_title:  {{pr.title}}
  base_branch: {{pr.base.ref}}

Post the final artifact as a PR review comment via the GitHub connector.

Compatibility matrix

Every feature of the PLAYBOOK.md spec, and how it behaves in a routine:

Feature	Routine support
Title / Description / `## SYSTEM`	Full
Typed `## INPUTS`	Full — via prompt (schedule) or `text` body (API)
`{{var}}` interpolation	Full
Sequential steps + context accumulation	Full
`## ARTIFACTS` (all types)	Full — specify destination path in the prompt
Branching `if/elif/else`	Full
`@output` (basic / typed / enum)	Full
`@output(var, extract:"field")`	Best-effort — pure-LLM JSON parsing; occasional fidelity loss. See the skill for mitigations
`@prompt(file:…)`	Full — repo is cloned
`@prompt(library:…)`	Needs a prompt-library MCP connector attached to the routine
`@prompt(mcp:server/name)`	Full — attach the connector
`@prompt({{var}})` dynamic	Full
`@tool(connection, tool, args)`	Full — attach the connector
`@elicit(input\|confirm\|select)`	Autonomous defaults (see below); overrides via the `text` payload
Breakpoints	Not supported (warning, not error)

`@elicit` in autonomous runs {#elicit-in-autonomous-runs}

Routines can’t pause for human input. The playbook-run skill applies these defaults when no override is supplied:

@elicit(confirm, "…") → "yes"
@elicit(select, "…", "A", "B", "C") → "A" (first option)
@elicit(input, "…") → ""

Overrides

API triggers — include an elicit block in the /fire text payload, keyed by step number:

inputs:
  topic: "AI safety"
elicit:
  3: "yes"
  4: "Performance"

Scheduled triggers — override inline in the prompt, e.g. “For the @elicit(confirm) in step 3, use \"no\".”.

Recommendations for routine-targeted playbooks

Avoid @elicit when you can — express the same gate as an input with a default.
If you keep @elicit, make sure the first select option is the sensible default.
Cross-check with the gallery’s “Ready for Claude Code Routines” list for patterns that work.

End-to-end example

The Weekly Docs Drift playbook in the gallery is built for a weekly schedule trigger. Four steps, branches on an input (severity_threshold), no elicitation, markdown artifact.

End-to-end:

Fork or copy the playbook into your repo at ./playbooks/weekly-docs-drift.playbook.md.
Commit the playbook-run skill (see step 2 above).
Create a routine pointing at that repo with the scheduled-trigger prompt template. Inputs: repo_path: ., days: 7, docs_root: docs, severity_threshold: medium.
Set a weekly schedule (e.g. Monday 09:00 your timezone).
Each Monday, the routine fires, clones the repo, reads the playbook, executes it, and writes ./out/<date>.md on a claude/weekly-docs-drift branch.

Limitations

No interactive pauses. @elicit cannot block for a real human; answers must be pre-committed (via defaults or payload). Breakpoints are ignored with a warning.
@output(extract) isn’t deterministic. Pure-LLM extraction occasionally misses the field. Mitigate with explicit JSON-emission instructions in the step prompt, or prefer enum-typed @output for high-stakes branching.
No programmatic routine creation. The /fire endpoint is the only public routine API. Routines are created in the web UI, desktop app, or the /schedule CLI.
One text body per fire. API triggers accept one freeform string. Structure it yourself (YAML / JSON / k=v) and parse it in the prompt.

Proposed spec extension

A future extension may add an optional default:"…" argument to @elicit so playbooks can express autonomous-mode fallbacks declaratively:

@elicit(confirm, "Proceed to next phase?", default:"yes")
@elicit(select, "Pick a focus", "Cost", "Perf", "DX", default:"Cost")

Track the proposal at playbook-spec#2.