O bloco `task:`

Uma skill vira tarefa quando declara o bloco task: no frontmatter do SKILL.md. Faça tarefa só do que alguém precisa disparar: um passo reutilizável por outras skills é auxiliar, e uma tarefa boa costuma ser a orquestração de várias 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: um agendamento por ambiente
    - environment: Produção
      cron: "0 9 * * 1-5"
      timezone: America/Sao_Paulo
  executor:                 # opcional: override de executor e modelo, ou `inherit`
    cli: claude_code
    model: claude-opus-4-8
  metadata:                 # opcional: objeto livre
    dono: financeiro
  dependencies:             # opcional: pacotes e serviços da lista do Kadu
    apt: [ffmpeg]
    services: [postgres]
---

Campo a campo

Campo	Tipo	Efeito
`label`	string	Nome no console. Sem ele, a tarefa nasce com o `skill_slug` como nome.
`description`	string	Texto de apresentação do agente na tela da tarefa.
`workspace`	string	Nome do workspace quando a sincronização o cria. A tarefa sempre fica no workspace do plugin. Ver a armadilha do nome.
`activity`	string	Obrigatório para a tarefa ser criada. Agrupador dentro do workspace, casado pelo nome exato.
`model`	string	Slug de um nível (`tier-3`), e não de um modelo de IA. O nível define preço, executor e modelo.
`parameters_schema`	JSON Schema ou `null`	Valida os parâmetros antes de criar a execução. Não é decorativo.
`parameters_sensitive`	booleano	`true` cifra os parâmetros guardados e os esconde na interface. Use quando o disparo carrega dado pessoal.
`accepts_input_files`	booleano	`true` aceita anexos no disparo; os caminhos chegam em `$INPUT_FILES`.
`generates_output_files`	booleano	`true` publica tudo o que a skill salvar em `$OUTPUT_FILES_DIR`.
`systems`	lista de strings	Só exibição: os sistemas externos que a tarefa toca.
`features`	lista de strings	Só exibição: o que a tarefa entrega.
`required_secrets`	lista de strings	Lista de permissão: só o que está aqui chega à execução. Ver Secrets.
`endpoint`	`{ enabled, auth }`	Disparo por `POST /run-task/{task_id}`. Ver Agendamento, endpoint e executor.
`schedules`	lista	Agendamentos da tarefa, um por ambiente.
`executor`	`inherit` ou `{ cli, model }`	Override de executor e modelo por cima do nível.
`metadata`	objeto	Gravado inteiro no `custom_metadata` da tarefa (aparece na API e nos webhooks).
`conversational`	booleano	`true` deixa a pessoa pedir ajustes depois que a execução termina, numa nova rodada que continua a anterior. Funciona com os dois executores. Ver Tarefas conversacionais.
`dependencies`	`{ apt, services }`	Pacotes do sistema e bancos que o Kadu instala antes da execução. Só nomes da lista do Kadu. Ver `dependencies`.

:::danger Tipo errado é descartado em silêncio A sincronização só aceita string onde espera string, booleano onde espera booleano e lista de strings nas listas. parameters_sensitive: "true" (com aspas) vira "não declarado", sem erro em lugar nenhum. E "não declarado", numa tarefa que já existe, quer dizer "não mexa": o campo fica com o valor antigo e a mudança não entra. Confira em "Tarefas atualizadas" depois do merge. :::

`model`: o slug de um nível, não de um modelo

task.model aponta para um nível cadastrado no Kadu. O nível carrega o preço, o executor e o modelo de IA. Níveis do cadastro inicial:

Nível	Executor	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`

Os níveis podem mudar. Confirme com a Kobana antes de escolher um nível novo.

Escrever um id de modelo (claude-sonnet-4-6) não quebra a sincronização, mas não é aplicado: a tarefa nova nasce no nível de menor ordem, a existente fica como está, e o resultado avisa model "…" não é um tier ativo. Sem model, o efeito é o mesmo, sem aviso.

Escolha pelo trabalho: leitura de código, planejamento e revisão pedem tier-4; orquestração com decisão pede tier-3. tier-1 e tier-2 trocam o executor para Goose: use só com uma skill testada nele, porque os helpers e o wrapper do Goose são outros.

`parameters_schema`: validado de verdade

O schema é compilado com Ajv (strict: false, com ajv-formats) e roda contra os parâmetros antes de criar a execução. Um schema bem escrito recusa disparo errado sem gastar uma execução. O console também monta o formulário do disparo a partir dele.

  parameters_schema:
    type: object
    additionalProperties: false      # recusa parâmetro que você não previu
    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 transforma erro de digitação em erro de disparo, em vez de parâmetro ignorado.
required só para o que de fato bloqueia a execução.
default é documentação para quem dispara: não preenche o valor. Aplique o padrão no corpo da skill (jq -r '.priority // 0').
null quando a tarefa não recebe parâmetro nenhum.

`dependencies`: pacotes e bancos da execução

O agente roda sem permissão de administrador. A tarefa que precisa de pacote do sistema ou de banco de dados declara, e o Kadu instala antes de a execução começar:

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

Só nomes da lista mantida pela Kobana: PDF, OCR, documentos, planilhas, imagens, áudio e vídeo, arquivos, clientes de banco e os serviços postgres, mysql, mariadb, redis e valkey. A lista completa, as regras e o que fazer quando falta algo estão em Dependências.

A armadilha do nome de `workspace` e `activity`

O casamento é pelo nome exato: Desenvolvimento, desenvolvimento e Desenvolvimento (com espaço) são três nomes diferentes.

	Efeito na sincronização
`workspace`	não decide nada para tarefa existente: o workspace é o do plugin. O nome só batiza o workspace na primeira vez que ele é criado.
`activity`	casada pelo nome exato dentro do workspace do plugin. Um nome que não existe cria uma atividade nova e move a tarefa para ela.

Um erro de digitação em activity: não falha: aparece uma atividade "Baixa de recebimentos" ao lado de "Baixa de Recebimentos", com a tarefa dentro da nova. A sincronização só cria atividade, nunca renomeia nem apaga, então a duplicada fica até alguém removê-la.

Copie o nome da atividade que já existe, em vez de digitar de memória. Para renomear uma atividade, renomeie primeiro no Kadu e depois no frontmatter de todas as skills que a usam. Na ordem inversa, a sincronização cria a nova e as tarefas se espalham entre as duas.

Exemplo real

A tarefa de smoke do repositório da Kobana declara parâmetros, arquivos de entrada e de saída, um secret e o 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 a campo​

model: o slug de um nível, não de um modelo​

parameters_schema: validado de verdade​

dependencies: pacotes e bancos da execução​

A armadilha do nome de workspace e activity​

Exemplo real​