Authoring Lionagi Playbooks
A playbook is a .playbook.yaml file that defines a reusable, parametric agent
workflow. Install it in ~/.lionagi/playbooks/ on the machine the MCP server runs
on — that filesystem step is the same whichever interface runs the playbook.
To run it, call the mcp__plugin_orchestrate_lion__request tool with play.submit. Ask for
the fingerprint first, naming the playbook — play.submit's schema depends on which playbook
you name, because a playbook's own declared arguments are resolved into it:
{"help": {"verb": "play.submit", "playbook": "hello"}}
{"ops": [{"op": "play.submit", "args": {"playbook": "hello", "prompt": "what is a monad?"}, "schema_fingerprint": "<from the help call above>"}]}
The fingerprint is a sibling of args, never a key inside it. Omit it and the op is
refused with stale_schema and no run starts; nest it inside args and it is not read, so
the same refusal repeats and the failure reads as idempotent.
If you're working inside a lionagi checkout, the CLI equivalent is
li play <name> "<prompt>", which expands to li o flow -p <name> "<prompt>".
Minimum Viable Playbook
name: hello
description: Greet and answer a question.
model: claude-code/sonnet-4-6
prompt: |
You are a patient teacher. Explain the following topic in plain language,
with one concrete example.
Run it with play.submit:
{"ops": [{"op": "play.submit", "args": {"playbook": "hello", "prompt": "what is a monad?"}, "schema_fingerprint": "<from help={\"verb\": \"play.submit\", \"playbook\": \"hello\"}>"}]}
Inside a lionagi checkout: li play hello "what is a monad?"
The positional text is appended to the prompt with a blank line because the
template contains no {input} placeholder. That is the only behaviour difference
from a template that declares {input} explicitly.
Authoring Checklist
- Filename:
<name>.playbook.yaml - Location:
~/.lionagi/playbooks/ -
name:equals the filename stem — nothing validates the two against each other, and the CLI resolves by filename, so a mismatch is silent rather than an error -
description:is one clear sentence - Choose routing deliberately:
model:andagent:are optional; when both are omitted, flow uses its default orchestrator configuration. Ifagent:is set, verify that profile exists on the machine running the MCP server -
prompt:references only declaredargskeys and optional{input} - Every
argsentry declarestype,default, andhelp. A suppliedtypeis validated; omitting these fields yieldsstr, null, and a generated help line respectively - No dashed keys inside
args: -
team_modeandteam_attachare not both set -
workersis 1–32 if set;max_opsis 0–50 if set - If reactive follow-ups are enabled with a nonzero
max_ops, leave room below the cap; the initial plan and spawned assignments share the same budget - Dry-run check:
play.submitwithdry_run: trueplans without executing (callhelp=truefirst to confirm the argument name for your published server version) - Help check (lionagi checkout only):
li play <name> --helpalways lists fields fromargs:;argument-hintcontrols the usage line and can define fallback flags when noargs:block exists. Over MCP, qualified playbook help resolves the custom arguments
Companion Files
| File | Contents |
|---|---|
field-reference.md |
Complete field table, args schema, template interpolation rules, team semantics, reserved names, pitfalls, source code reference |
examples.md |
Three annotated example playbooks (minimal, audit, pr-review) plus the examples directory index |
patterns.md |
Orchestration patterns and advanced composition strategies |