Playbooks

A Playbook is a markdown + YAML guide that an agent reads on demand — not on every turn — for procedural knowledge that's too long for the system prompt and too declarative for a code-shaped Operation. Think: "how we draft a proposal," "how we triage a meeting," "how to handle a refund escalation."

Why agents need them

The system prompt is for identity and rules. Operations are for typed LLM calls with schemas. Playbooks fill the gap between: structured procedures the agent should follow when it recognizes the situation, mounted into the agent's virtual filesystem at /playbooks/<slug>/SKILL.md. The agent loads them lazily — the prompt stays small, the procedure is there when needed.

How they're authored

Author one playbook per directory at workspace/<org>/playbooks/<slug>/:

workspace/<org>/playbooks/proposal-drafting/
├── SKILL.md           ← the playbook body (markdown)
├── REFERENCE.html     ← optional sibling resource
├── COMPONENTS.md      ← optional sibling resource
└── EXAMPLES/
    └── sample.md

SKILL.md carries YAML frontmatter validated by PlaybookManifestSchema:

---
slug: proposal-drafting
name: "Proposal drafting playbook"
description: "Step-by-step procedure for drafting client proposals from a discovery call."
tags: [proposal, sales]
license: CC-BY-4.0
---

# When to use this playbook

The agent should read this playbook when …

How they mount

Per-agent tag filters decide which playbooks an agent sees. The mounting rule:

• A playbook with no tags mounts into every agent's virtual FS.
• A playbook with tags mounts only when the agent's tag filter intersects.

This lets one tenant ship dozens of playbooks while keeping each agent's working set narrow. See vocion-core/packages/core/src/services/playbooks/mount.ts for the algorithm.

Dashboard surface

/dashboard/playbooks lists every playbook in the active project. Click one to see its rendered markdown body plus the mount scope (tags or "mounts everywhere"). Authoring stays on disk — the dashboard is read-only in v0.5.

Related

• Agents — how playbooks attach to a specific agent's virtual FS
• Learnings — for rules-as-data rather than narrative procedures
• Operations — for typed LLM calls when you need a schema not a procedure