Playbook structure

The Playbook has a catalog at the root and one directory per plugin. Each plugin is a Kadu workspace.

kadu-kobs-<organization>/
├── .claude-plugin/
│   └── marketplace.json          ← catalog: plugin name → directory
├── kadu.yaml                     ← (optional) environments, webhooks, metadata
├── CLAUDE.md                     ← rules for whoever edits the Playbook with a coding agent
├── README.md
├── finance/                      ← plugin = "finance" workspace
│   ├── .claude-plugin/
│   │   └── plugin.json           ← plugin manifest
│   ├── .mcp.json                 ← (optional) the workspace's MCP servers
│   ├── docs/                     ← (optional) supporting material for the skills
│   └── skills/
│       ├── task-baixar-pagamentos/
│       │   └── SKILL.md          ← task (has a task: block)
│       └── fintera-listar-contas-a-receber/
│           └── SKILL.md          ← helper (no task: block)
└── <other-workspace>/
    └── ...

The catalog: .claude-plugin/marketplace.json

Lists the Playbook's plugins. The catalog's name identifies the Playbook.

{
  "name": "kadu-kobs-kobana",
  "description": "Kadu Playbook for the Kobana organization. One plugin per workspace.",
  "owner": { "name": "Kobana" },
  "metadata": { "pluginRoot": "./" },
  "plugins": [
    {
      "name": "finance",
      "source": "./finance",
      "description": "Finance workspace: settlement of accounts receivable (boleto/PIX and credit card)."
    }
  ]
}

:::warning The plugin name is the slug prefix Each plugin's name, in the catalog and in plugin.json, must be the prefix of the skill_slug of its tasks. A skill at finance/skills/task-x/ becomes the task finance:task-x, and it is through finance that each execution finds the plugin directory in the Playbook. :::

A Playbook with a single plugin can do without the catalog, as long as the plugin is in a subdirectory with its own name and has .claude-plugin/plugin.json. Prefer declaring the catalog: it makes things explicit.

plugin.json

{
  "name": "finance",
  "version": "1.0.0",
  "description": "Skills of the Finance workspace: settlement of accounts receivable and the integrations they orchestrate.",
  "author": { "name": "Kobana" }
}

.mcp.json

MCP servers that the workspace's skills use. Kadu loads the file along with the plugin. Credentials come in through an environment variable, which must be in the task's required_secrets:

{
  "mcpServers": {
    "kobana": {
      "type": "http",
      "url": "https://mcp.banking.kobana.com.br",
      "headers": { "Authorization": "Bearer ${KOBANA_MCP_TOKEN}" }
    }
  }
}

In an execution there is nobody to complete an interactive OAuth login: use servers that accept a token in the header. If the variable is not defined, the ${...} stays literal and the connection fails.

Skills

Each skill is a folder with a SKILL.md. The folder name is the skill's name and the second part of the skill_slug. Supporting files (scripts, templates, examples) sit next to the SKILL.md, and the skill references them by relative path.

---
name: task-ola-kadu
description: Demo task — greets whoever triggered it. Does not touch any external system.
user-invocable: true
task:
  label: "Olá, Kadu"
  description: "I am a demo task: I show how an execution appears in the Console."
  workspace: Demonstração
  activity: Primeiros passos
  model: tier-3
  parameters_schema: null
  required_secrets: []
---

# Olá, Kadu

Instructions the agent follows...

Key	What for
name	same as the folder name
description	one operational line about what the skill does; it is how the agent finds the skill
user-invocable	true lets the skill be called by /<plugin>:<skill>
task	the block that turns the skill into a task (The task: block)

Do not confuse description (root, short, for the agent to find the skill) with task.description (introduction text in the console, which can be long).

Integrations inside the plugin

Each workspace is self-contained. The helper skills that talk to an external system (fintera-*, pagarme-*, stone-*) live inside the plugin that uses them, with the same prefix (finance:fintera-listar-contas-a-receber). The only external dependency is the kadu plugin, which Kadu loads in every execution.

New workspace

1. Create the plugin directory with .claude-plugin/plugin.json (name = the workspace slug) and the skills/ folder.
2. Register the plugin in the root catalog (.claude-plugin/marketplace.json).
3. Write at least one skill with a task: block. The workspace is created in Kadu by the sync, from the tasks: a plugin with no task does not become a workspace.

Starter Playbook

Kobana can create the organization's Playbook already set up: catalog, README.md, CLAUDE.md and a demo plugin with the demo task demo:task-ola-kadu (Demonstração workspace, Primeiros passos activity), with no external system. It is the best starting point: replace the demo with your own tasks.