Estructura del Playbook

El Playbook tiene un catálogo en la raíz y un directorio por plugin. Cada plugin es un workspace de Kadu.

kadu-kobs-<organización>/
├── .claude-plugin/
│   └── marketplace.json          ← catálogo: nombre del plugin → directorio
├── kadu.yaml                     ← (opcional) entornos, webhooks, metadatos
├── CLAUDE.md                     ← reglas para quien edita el Playbook con un agente de código
├── README.md
├── finance/                      ← plugin = workspace "finance"
│   ├── .claude-plugin/
│   │   └── plugin.json           ← manifiesto del plugin
│   ├── .mcp.json                 ← (opcional) servidores MCP del workspace
│   ├── docs/                     ← (opcional) material de apoyo de las skills
│   └── skills/
│       ├── task-baixar-pagamentos/
│       │   └── SKILL.md          ← tarea (tiene bloque task:)
│       └── fintera-listar-contas-a-receber/
│           └── SKILL.md          ← auxiliar (sin bloque task:)
└── <otro-workspace>/
    └── ...

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

Lista los plugins del Playbook. El name del catálogo identifica el 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 El nombre del plugin es el prefijo del slug El name de cada plugin, en el marketplace.json y en el plugin.json, tiene que ser el prefijo del skill_slug de sus tareas. Una skill en finance/skills/task-x/ se convierte en la tarea finance:task-x, y es por finance que cada ejecución encuentra el directorio del plugin en el Playbook. :::

Un Playbook con un único plugin puede prescindir del catálogo, siempre que el plugin esté en un subdirectorio con su propio nombre y tenga .claude-plugin/plugin.json. Prefiere declarar el catálogo: queda 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 usan las skills del workspace. Kadu carga el archivo junto con el plugin. Las credenciales entran por variable de entorno, que debe estar en required_secrets de la tarea:

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

En una ejecución no hay nadie que complete un inicio de sesión OAuth interactivo: usa servidores que acepten token en el header. Si la variable no está definida, el ${...} queda literal y la conexión falla.

Skills

Cada skill es una carpeta con un SKILL.md. El nombre de la carpeta es el nombre de la skill y la segunda parte del skill_slug. Los archivos de apoyo (scripts, plantillas, ejemplos) quedan junto al SKILL.md, y la skill los referencia por la ruta relativa.

---
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...

Clave	Para qué
name	igual al nombre de la carpeta
description	una línea operativa sobre lo que hace la skill; es por ella que el agente encuentra la skill
user-invocable	true permite llamar a la skill con /<plugin>:<skill>
task	el bloque que convierte la skill en tarea (El bloque task:)

No confundas description (raíz, corta, para que el agente encuentre la skill) con task.description (texto de presentación en la consola, puede ser largo).

Integraciones dentro del plugin

Cada workspace es autocontenido. Las skills auxiliares que hablan con un sistema externo (fintera-*, pagarme-*, stone-*) viven dentro del plugin que las usa, con el mismo prefijo (finance:fintera-listar-contas-a-receber). La única dependencia externa es el plugin kadu, que Kadu carga en toda ejecución.

Nuevo workspace

1. Crea el directorio del plugin con .claude-plugin/plugin.json (name = el slug del workspace) y la carpeta skills/.
2. Registra el plugin en el catálogo de la raíz (.claude-plugin/marketplace.json).
3. Escribe al menos una skill con bloque task:. El workspace se crea en Kadu mediante la sincronización, a partir de las tareas: un plugin sin tareas no se convierte en workspace.

Playbook inicial

Kobana puede crear el Playbook de la organización ya armado: catálogo, README.md, CLAUDE.md y un plugin demo con la tarea de demostración demo:task-ola-kadu (workspace Demonstração, actividad Primeiros passos), sin sistema externo. Es el mejor punto de partida: cambia la demostración por tus tareas.