Agent Playbooks

How agents find the skills and custom prompts you saved in your workspace, and how to write them so they get found.

You set a job up once, in a skill or a custom prompt: which Base it goes in, which fields to fill, what tone to use. From then on you expect every agent to do that job your way, not work out its own. Busabase calls these saved ways of working playbooks. Agents look for one at the start of every instruction. This page is for the person who writes them.

What counts as a playbook

Playbook	Where it lives	What the agent matches on
A skill	A Skill node: a `SKILL.md` plus optional `references/` and `scripts/`	The skill's `name` and the `description` in its `SKILL.md` frontmatter
A custom prompt	A node's Agent prompts → Custom scenarios	The scenario name, and the start of the prompt text

It makes no difference whether a skill came from a template or you wrote it yourself. Both are found the same way.

The built-in scenarios that every node type ships with ("Design a schema", "Bulk import", …) are not playbooks. They are the same on every node of that type, so agents already know them, and counting them would bury the ones you wrote. Your custom scenarios are listed after the built-in ones, and the built-ins always stay.

When agents look

An agent looks for a playbook at the start of every instruction, including plain questions, before it works anything out for itself. It searches the whole workspace, not only the folder you are in.

It only sees what its key can read. A playbook on a node the agent has no access to never appears in its results.

Agents connected over MCP, the CLI, or the REST API all follow this rule. So do agents you start from the dashboard.

How the agent picks one

It rephrases your request. Busabase does not interpret language itself. The agent sends two to five versions of what you asked, in your language and in English. "帮我记一下今天去见了 Acme" becomes "记录客户拜访", "log customer visit", "visit record".
Busabase matches those phrasings against every playbook's name, description, and scenario name. A playbook that several phrasings hit ranks above one that only a single stray word hits.
The nearest one wins a tie. If you are inside your Sales folder and both Sales and Ops have a "weekly report" skill, the Sales one comes first.
The agent reads it and follows it. If nothing fits, it does the work without one. It won't stall, and it won't pretend something matched.

Your own words always win. If a playbook says "write to the Leads Base" and you say "put it in Partners", the agent follows you.

A playbook is instructions, not permission

Agents treat playbook text like any other stored content. A playbook can describe how to do a job, but it can't make an agent approve or merge a change request, or give it more access than its key already has. Only what you say in the conversation can do that.

Writing playbooks agents find

Whether an agent finds your playbook depends almost entirely on how you name and describe it.

Name a custom prompt with the words people actually say. "Log a customer visit", not "Create a record in Visits". People ask for the first; the second is just the operation, and the built-in scenarios already cover it.
Make a skill's description say when to use it. "Use when logging or reviewing customer visits for the Acme account" is found. "CRM helper" is not.
Name it in every language your team uses. Agents match names in every language. The dashboard editor saves the name in the language you are viewing. To give one scenario a name in several languages at once, have an agent set it: busabase-cli nodes set-agent-prompts and the API accept { "en": "Log a customer visit", "zh-CN": "记录客户拜访" }.
Two playbooks with the same name in different folders is fine, as long as you meant it. The one nearest to where the person is working wins.
One recurring job per prompt, two to five per node. If you can't name a job someone will come back for, don't write a prompt. A vague one only gives agents a false match.

See all playbooks in one place

Open the space menu in the top-left corner and choose Playbooks. The page lists every skill and custom prompt in the space that you can read, grouped by folder. Filter with All, Skills, or Prompts. A prompt row names the node it lives on and whether it only reads (Read-only) or writes (Makes changes). Use Open prompts to edit that node's prompts without leaving the page.

To check that an agent will find a playbook, type what you would tell an agent into What would you tell an agent? and choose Find. You get the same ranked search an agent runs, with the fields each result matched on. It is a literal preview: an agent also sends its own rephrasings (and English), so it may find more than you see here. If nothing matches, rename the prompt or rewrite the skill's description with the words you just typed.

Checking what was used

When an agent follows a playbook, it says so in its reply and links to it, for example: Used playbook: Log a customer visit (Visits). If the reply names no playbook, the agent didn't find one that fit.

The change request records it too. When you review a change, the change request page and your inbox show a via playbook Log a customer visit chip. Click it to open the playbook. If you can't read the node the playbook lives on, the chip says via a playbook, without the name or a link.

A change request with no chip was written without a playbook, or by an agent that didn't say which one it used. A playbook that never shows up on any change request is one agents aren't finding.

Agents declare the playbook on each write as kind:nodeId[:key], for example prompt:<nodeId>:<key> for a custom prompt or skill:<nodeId> for a skill:

CLI: the global --playbook flag, or the BUSABASE_PLAYBOOK environment variable
MCP: the playbook argument on write tools
REST: the x-busabase-playbook header

Busabase checks the value before recording it. The playbook has to exist, and the agent's key has to be able to read it. If either check fails, the write still goes through, just without the chip. Busabase fills in the name itself, so an agent can't put its own text on the chip.

When the agent didn't use it

Name it in your instruction: "use the Log a customer visit prompt on Visits". An agent that is told which playbook to use reads it directly.
Then fix the name or description so the next request finds it without being told. Use the words you typed the first time, when the agent missed it.
Check the agent can read it. A playbook on a node its key can't read is invisible to it.

For developers: the calls

Surface	Search	Read one
CLI	`busabase-cli playbooks search --query "…" --query "…" [--near-node-id <id>] [--kinds skill,prompt] [--limit N] --output json`	`busabase-cli playbooks get --kind prompt --node-id <id> --key <key>` or `--kind skill --node-id <id>`
MCP	`playbooks_search`	`playbooks_get`
REST	`POST /api/v1/playbooks/search`	`GET /api/v1/playbooks/{kind}/{nodeId}?key=`

A search takes queries (up to eight phrasings), plus optional nearNodeId, inNodeId, kinds, and limit. It returns a short ranked list with total, truncated, and coverage. With no queries it lists the nearest playbooks. If a result is truncated, or coverage says a kind wasn't searched (an older server), an empty list does not mean no playbooks exist. For how this differs from grep and search, see Search Everything.