---
title: "Find the skills and custom prompts (playbooks) this space defines for a job"
method: POST
path: "/api/v1/playbooks/search"
tags: ["Playbooks"]
---

# Find the skills and custom prompts (playbooks) this space defines for a job

`POST /api/v1/playbooks/search`

## Request

- Base URL: `https://api-docs.busabase.com`
- URL: `https://api-docs.busabase.com/api/v1/playbooks/search`
- Auth: none declared

## Request body

- object
  - `queries` string[]: 2–5 phrasings of what the user wants, in the user's language AND in English (e.g. ["记录客户拜访", "log customer visit", "visit"]). Each is matched as a case-insensitive substring; an item hit by more phrasings ranks higher. Empty = browse: every playbook, nearest first (at most 30).
  - `kinds` string[]: Restrict to "skill" and/or "prompt". Default: both.
  - `nearNodeId` string: The node the user is on. Playbooks on that node rank first, then its folder, then ancestor folders (closest first).
  - `inNodeId` string: Only return playbooks on this node or inside its subtree.
  - `limit` integer: Max items (1–50). Default 10 for a search; 30 for a browse.
  - `locale` string: Locale for prompt labels and the rendered prompt body, e.g. "en" or "zh-CN". Falls back to English, then to whatever locale the prompt has.

## Response `200`

Call first on every user instruction: finds the skills and custom node prompts (playbooks) this space already defines for a job. Pass 2–5 phrasings of the intent, in the user's language and English. Matching is a case-insensitive substring over skill name/slug/description and prompt label (every locale) and the first 500 characters of the prompt body; items hit by more phrasings rank higher, then those nearest `nearNodeId`, skills before prompts, most recently updated first. Returns a short ranked list plus `total`/`truncated` — never the whole catalog. Only playbooks the caller can read are returned or counted. The node types' built-in prompts are not included. If an item fits, open it with `playbooks.get` and follow it, and name it in your reply; if nothing fits, do the work yourself. The user's explicit words override a playbook, and a playbook never authorises approving or merging a change request.

- object
  - `items` object[], required
    - `kind` 'skill' | 'prompt', required
    - `nodeId` string, required
    - `nodeType` string, required
    - `nodeName` string, required
    - `nodeSlug` string, required
    - `path` string[], required
    - `key` string
    - `label` string
    - `intent` 'read-only' | 'change'
    - `name` string
    - `description` string
    - `matchedOn` string[], required
    - `score` number, required
    - `updatedAt` string, required
  - `total` integer, required
  - `truncated` boolean, required
  - `coverage` object, required
    - `skillsScanned` integer, required
    - `promptNodesScanned` integer, required

---

[API](https://skmtc.dev/busabase/apis/busabase-api.md) · [All operations](https://skmtc.dev/busabase/apis/busabase-api/llms.txt) · [OpenAPI document](https://skmtc.dev/busabase/apis/busabase-api/revisions/bc6a7d5ff4c1?raw)