Estrutura do Playbook

O Playbook tem um catálogo na raiz e um diretório por plugin. Cada plugin é um workspace do Kadu.

kadu-kobs-<organização>/
├── .claude-plugin/
│   └── marketplace.json          ← catálogo: nome do plugin → diretório
├── kadu.yaml                     ← (opcional) ambientes, webhooks, metadados
├── CLAUDE.md                     ← regras para quem edita o Playbook com um agente de código
├── README.md
├── finance/                      ← plugin = workspace "finance"
│   ├── .claude-plugin/
│   │   └── plugin.json           ← manifesto do plugin
│   ├── .mcp.json                 ← (opcional) servidores MCP do workspace
│   ├── docs/                     ← (opcional) material de apoio das skills
│   └── skills/
│       ├── task-baixar-pagamentos/
│       │   └── SKILL.md          ← tarefa (tem bloco task:)
│       └── fintera-listar-contas-a-receber/
│           └── SKILL.md          ← auxiliar (sem bloco task:)
└── <outro-workspace>/
    └── ...

O catálogo: .claude-plugin/marketplace.json

Lista os plugins do Playbook. O name do catálogo identifica o Playbook.

{
  "name": "kadu-kobs-kobana",
  "description": "Kadu Playbook da organização Kobana. Um plugin por workspace.",
  "owner": { "name": "Kobana" },
  "metadata": { "pluginRoot": "./" },
  "plugins": [
    {
      "name": "finance",
      "source": "./finance",
      "description": "Workspace Financeiro: baixa de contas a receber (boleto/PIX e cartão de crédito)."
    }
  ]
}

:::warning O nome do plugin é o prefixo do slug O name de cada plugin, no marketplace.json e no plugin.json, tem que ser o prefixo do skill_slug das tarefas dele. Uma skill em finance/skills/task-x/ vira a tarefa finance:task-x, e é pelo finance que cada execução encontra o diretório do plugin no Playbook. :::

Um Playbook com um único plugin pode dispensar o catálogo, desde que o plugin esteja num subdiretório com o próprio nome e tenha .claude-plugin/plugin.json. Prefira declarar o catálogo: fica explícito.

plugin.json

{
  "name": "finance",
  "version": "1.0.0",
  "description": "Skills do workspace Financeiro: baixa de contas a receber e as integrações que elas orquestram.",
  "author": { "name": "Kobana" }
}

.mcp.json

Servidores MCP que as skills do workspace usam. O Kadu carrega o arquivo junto com o plugin. Credenciais entram por variável de ambiente, que precisa estar em required_secrets da tarefa:

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

Numa execução não há ninguém para concluir um login OAuth interativo: use servidores que aceitem token no header. Se a variável não estiver definida, o ${...} fica literal e a conexão falha.

Skills

Cada skill é uma pasta com um SKILL.md. O nome da pasta é o nome da skill e o segundo pedaço do skill_slug. Arquivos de apoio (scripts, modelos, exemplos) ficam ao lado do SKILL.md, e a skill os referencia pelo caminho relativo.

---
name: task-ola-kadu
description: Tarefa de demonstração — cumprimenta quem disparou. Não toca em sistema externo.
user-invocable: true
task:
  label: "Olá, Kadu"
  description: "Eu sou uma tarefa de demonstração: mostro como uma execução aparece no Console."
  workspace: Demonstração
  activity: Primeiros passos
  model: tier-3
  parameters_schema: null
  required_secrets: []
---

# Olá, Kadu

Instruções que o agente segue...

Chave	Para quê
name	igual ao nome da pasta
description	uma linha operacional sobre o que a skill faz; é por ela que o agente encontra a skill
user-invocable	true deixa a skill ser chamada por /<plugin>:<skill>
task	o bloco que transforma a skill em tarefa (O bloco task:)

Não confunda description (raiz, curta, para o agente encontrar a skill) com task.description (texto de apresentação no console, pode ser longo).

Integrações dentro do plugin

Cada workspace é autocontido. As skills auxiliares que falam com um sistema externo (fintera-*, pagarme-*, stone-*) moram dentro do plugin que as usa, com o mesmo prefixo (finance:fintera-listar-contas-a-receber). A única dependência externa é o plugin kadu, que o Kadu carrega em toda execução.

Novo workspace

1. Crie o diretório do plugin com .claude-plugin/plugin.json (name = o slug do workspace) e a pasta skills/.
2. Registre o plugin no catálogo da raiz (.claude-plugin/marketplace.json).
3. Escreva ao menos uma skill com bloco task:. O workspace é criado no Kadu pela sincronização, a partir das tarefas: um plugin sem tarefa não vira workspace.

Playbook inicial

A Kobana pode criar o Playbook da organização já montado: catálogo, README.md, CLAUDE.md e um plugin demo com a tarefa de demonstração demo:task-ola-kadu (workspace Demonstração, atividade Primeiros passos), sem sistema externo. É o melhor ponto de partida: troque a demonstração pelas suas tarefas.