El bloque `task:`

Una skill se convierte en tarea cuando declara el bloque task: en el frontmatter del SKILL.md. Haz tarea solo de lo que alguien necesita lanzar: un paso reutilizable por otras skills es auxiliar, y una buena tarea suele ser la orquestación de varias auxiliares.

---
name: task-meu-processo
description: O que a skill faz, em uma linha (usado na busca)
user-invocable: true
task:
  label: "Meu Processo"
  description: "Texto de apresentação do agente ao usuário."
  workspace: Financeiro
  activity: Baixa de Recebimentos
  model: tier-3
  parameters_schema: null
  parameters_sensitive: false
  accepts_input_files: false
  generates_output_files: false
  systems:
    - Kobana
  features:
    - O que a tarefa cobre
  required_secrets:
    - KOBANA_ACCESS_TOKEN
  endpoint:                 # opcional
    enabled: true
    auth: bearer
  schedules:                # opcional: uma programación por entorno
    - environment: Produção
      cron: "0 9 * * 1-5"
      timezone: America/Sao_Paulo
  executor:                 # opcional: override de ejecutor y modelo, o `inherit`
    cli: claude_code
    model: claude-opus-4-8
  metadata:                 # opcional: objeto libre
    dono: financeiro
  dependencies:             # opcional
    apt: [ffmpeg]
    services: [postgres]
---

Campo por campo

Campo	Tipo	Efecto
`label`	string	Nombre en la consola. Sin él, la tarea nace con el `skill_slug` como nombre.
`description`	string	Texto de presentación del agente en la pantalla de la tarea.
`workspace`	string	Nombre del workspace cuando la sincronización lo crea. La tarea siempre queda en el workspace del plugin. Ver la trampa del nombre.
`activity`	string	Obligatorio para que se cree la tarea. Agrupador dentro del workspace, emparejado por el nombre exacto.
`model`	string	Slug de un nivel (`tier-3`), y no de un modelo de IA. El nivel define precio, ejecutor y modelo.
`parameters_schema`	JSON Schema o `null`	Valida los parámetros antes de crear la ejecución. No es decorativo.
`parameters_sensitive`	booleano	`true` cifra los parámetros guardados y los oculta en la interfaz. Úsalo cuando el lanzamiento lleva datos personales.
`accepts_input_files`	booleano	`true` acepta adjuntos en el lanzamiento; las rutas llegan en `$INPUT_FILES`.
`generates_output_files`	booleano	`true` publica todo lo que la skill guarde en `$OUTPUT_FILES_DIR`.
`systems`	lista de strings	Solo para mostrar: los sistemas externos que toca la tarea.
`features`	lista de strings	Solo para mostrar: lo que entrega la tarea.
`required_secrets`	lista de strings	Lista de permitidos: solo lo que está aquí llega a la ejecución. Ver Secrets.
`endpoint`	`{ enabled, auth }`	Lanzamiento por `POST /run-task/{task_id}`. Ver Programación, endpoint y ejecutor.
`schedules`	lista	Programaciones de la tarea, una por entorno.
`executor`	`inherit` o `{ cli, model }`	Override de ejecutor y modelo por encima del nivel.
`metadata`	objeto	Se guarda completo en el `custom_metadata` de la tarea (aparece en la API y en los webhooks).
`conversational`	booleano	`true` permite que la persona pida ajustes después de que termina la ejecución, en una nueva ronda que continúa la anterior. Funciona con los dos ejecutores. Ver Tareas conversacionales.
`dependencies`	`{ apt, services }`	Paquetes del sistema y bases de datos que Kadu instala antes de la ejecución. Solo nombres de la lista de Kadu. Ver `dependencies`.

:::danger Un tipo incorrecto se descarta en silencio La sincronización solo acepta string donde espera string, booleano donde espera booleano y lista de strings en las listas. parameters_sensitive: "true" (con comillas) pasa a ser "no declarado", sin error en ningún lugar. Y "no declarado", en una tarea que ya existe, significa "no tocar": el campo conserva el valor anterior y el cambio no entra. Revisa "Tareas actualizadas" después del merge. :::

`model`: el slug de un nivel, no de un modelo

task.model apunta a un nivel registrado en Kadu. El nivel lleva el precio, el ejecutor y el modelo de IA. Niveles del registro inicial:

Nivel	Ejecutor	Modelo de IA
`tier-1`	goose	`openrouter/openai/gpt-4.1-mini`
`tier-2`	goose	`openrouter/google/gemini-3.5-flash`
`tier-3`	claude_code	`claude-sonnet-4-6`
`tier-4`	claude_code	`claude-opus-4-8`
`tier-5`	claude_code	`claude-fable-5`

Los niveles pueden cambiar. Confirma con Kobana antes de elegir un nivel nuevo.

Escribir un id de modelo (claude-sonnet-4-6) no rompe la sincronización, pero no se aplica: la tarea nueva nace en el nivel de menor orden, la existente queda como está, y el resultado avisa model "…" não é um tier ativo. Sin model, el efecto es el mismo, sin aviso.

Elige según el trabajo: lectura de código, planificación y revisión piden tier-4; orquestación con decisión pide tier-3. tier-1 y tier-2 cambian el ejecutor a Goose: úsalos solo con una skill probada en él, porque los helpers y el wrapper de Goose son otros.

`parameters_schema`: validado de verdad

El schema se compila con Ajv (strict: false, con ajv-formats) y se ejecuta contra los parámetros antes de crear la ejecución. Un schema bien escrito rechaza un lanzamiento errado sin gastar una ejecución. La consola también arma el formulario de lanzamiento a partir de él.

  parameters_schema:
    type: object
    additionalProperties: false      # rechaza parámetros que no previste
    required:
      - repo_url
    properties:
      repo_url:
        type: string
        minLength: 3
        description: "owner/repo ou URL completa"
      priority:
        type: integer
        enum: [0, 1, 2, 3, 4]
        default: 0

additionalProperties: false convierte un error de tipeo en un error de lanzamiento, en lugar de un parámetro ignorado.
required solo para lo que de hecho bloquea la ejecución.
default es documentación para quien lanza: no completa el valor. Aplica el valor predeterminado en el cuerpo de la skill (jq -r '.priority // 0').
null cuando la tarea no recibe ningún parámetro.

`dependencies`: paquetes y bases de datos de la ejecución

El agente se ejecuta sin permisos de administrador. La tarea que necesita un paquete del sistema o una base de datos lo declara, y Kadu lo instala antes de que empiece la ejecución:

  dependencies:
    apt: [ffmpeg, poppler-utils]
    services: [postgres]

Solo nombres de la lista que mantiene Kobana: PDF, OCR, documentos, hojas de cálculo, imágenes, audio y video, archivos, clientes de base de datos y los servicios postgres, mysql, mariadb, redis y valkey. La lista completa, las reglas y qué hacer cuando falta algo están en Dependencias.

La trampa del nombre de `workspace` y `activity`

El emparejamiento es por el nombre exacto: Desenvolvimento, desenvolvimento y Desenvolvimento (con espacio) son tres nombres distintos.

	Efecto en la sincronización
`workspace`	no decide nada para una tarea existente: el workspace es el del plugin. El nombre solo bautiza el workspace la primera vez que se crea.
`activity`	emparejada por el nombre exacto dentro del workspace del plugin. Un nombre que no existe crea una actividad nueva y mueve la tarea a ella.

Un error de tipeo en activity: no falla: aparece una actividad "Baixa de recebimentos" junto a "Baixa de Recebimentos", con la tarea dentro de la nueva. La sincronización solo crea actividades, nunca renombra ni borra, así que la duplicada queda hasta que alguien la elimine.

Copia el nombre de la actividad que ya existe, en lugar de tipearlo de memoria. Para renombrar una actividad, renómbrala primero en Kadu y después en el frontmatter de todas las skills que la usan. En el orden inverso, la sincronización crea la nueva y las tareas se reparten entre las dos.

Ejemplo real

La tarea de smoke del repositorio de Kobana declara parámetros, archivos de entrada y de salida, un secret y el endpoint:

task:
  label: "Testar orquestração"
  description: "Sou a task de teste da plataforma. Passo por cada aba da execução e leio o que você anexar no disparo."
  workspace: Kadu
  activity: Teste
  model: tier-3
  parameters_schema:
    type: object
    additionalProperties: false
    properties:
      eco:
        type: string
        maxLength: 200
        description: "Texto devolvido no Resultado — prova que o parâmetro chegou à execução"
      falhar:
        type: boolean
        default: false
        description: "true encerra no passo 6 com erro, para exercitar o caminho de falha"
  parameters_sensitive: false
  accepts_input_files: true
  generates_output_files: true
  systems:
    - Kadu
  features:
    - "Histórico: um evento em cada nível — thinking, info, success, warning e error"
    - "Pendências: cria duas, com payload"
  required_secrets:
    - KADU_SMOKE_SECRET
  endpoint:
    enabled: true
    auth: bearer

Campo por campo​

model: el slug de un nivel, no de un modelo​

parameters_schema: validado de verdad​

dependencies: paquetes y bases de datos de la ejecución​

La trampa del nombre de workspace y activity​

Ejemplo real​