Boas práticas

O valor de uma skill está no que ela sabe e um modelo não adivinharia: o endpoint certo, o campo que vem nulo, a regra de negócio que não está escrita em lugar nenhum. As práticas abaixo vêm das skills que a Kobana roda em produção.

Ao escrever uma skill

Verifique antes de afirmar. Rode o comando, chame a API, leia o arquivo. Toda tabela de campos, enum e mensagem de erro no corpo de uma skill deve ter saído de uma execução real, e não de memória. Quando uma checagem contraria o que você ia escrever, o achado é a checagem.

Nomeie o caso concreto. "O MCP da Kobana responde 401 a um token pessoal de uso API REST: o KOBANA_MCP_TOKEN precisa ser um token de uso MCP" vale mais que "verifique o token". O agente segue melhor um exemplo do que uma regra geral.

Explique o porquê de cada proibição. Uma tabela de guardrails com o motivo ao lado de cada regra. Regra sem motivo é ignorada na primeira pressa, pelo agente e por quem edita a skill depois.

Não faça	Por quê
Perguntar ao usuário durante a execução	não há usuário: a execução trava até o limite de 60 minutos
Chamar log_http_call em cada requisição de um scanner	milhares de linhas afogam a aba Logs e escondem as chamadas de integração
Ler configuração com ${VAR:-padrão} fora de required_secrets	o padrão vale sempre, e ninguém consegue mudar o valor pelo Kadu

Escreva para os dois modos. Uma skill útil no Claude Code roda em local (com uma pessoa respondendo) e em task (no Kadu, sem ninguém). Em task, não pergunte: registre uma pendência e siga. Detecte o modo por GITHUB_ACTIONS (O corpo da tarefa).

Termine com uma tabela de erros comuns: sintoma → causa → onde está a solução. É a parte que mais economiza tempo de quem diagnostica.

Parâmetro declarado tem que ser lido e usado. Um parâmetro no parameters_schema que nenhum passo consulta é um bug, e não documentação.

Uma tarefa orquestra; auxiliares fazem. Separe o acesso a cada sistema externo em skills auxiliares pequenas (fintera-listar-contas-a-receber, nfeio-buscar-nota-fiscal) e deixe a tarefa decidir a ordem e o que fazer com cada resultado. As auxiliares são reaproveitadas por outras tarefas e testadas sozinhas no Claude Code.

Ao mudar uma skill que já é tarefa

• Mude o frontmatter, nunca o nome da pasta. Renomear cria outra tarefa.
• Atualize a documentação do repositório no mesmo commit: a tabela de tarefas do workspace no README.md e a contagem de tarefas. Um README desatualizado é o primeiro lugar onde a próxima pessoa se perde.
• Confira os avisos da sincronização depois do merge, pelo botão Sincronizar. Um item inválido (cron, nome de ambiente) descarta a lista inteira, e só o aviso conta isso.
• Configuração da tarefa muda no repositório, não no console. Agendamentos, endpoint, executor e metadata declarados no bloco task:, e ambientes no kadu.yaml, voltam ao declarado a cada push.

Ao manter o Playbook

• main é produção. Trabalhe em branch, valide no sandbox de CI e trate o merge como um deploy (Sincronização).
• Adicione arquivos por caminho explícito. git add -A pega o .execution-result.json que uma execução local deixa na raiz e o .env de teste. Mantenha os dois no .gitignore.
• Mantenha um CLAUDE.md na raiz com as regras do repositório: como as skills são escritas, o que não pode ir para o git, a ordem para provisionar um secret. É o que o Claude Code lê antes de editar.

Idioma

Escreva as skills, os eventos e o resultado no idioma de quem vai ler. Os eventos e o resultado de uma execução devem seguir $LOCALE, o idioma de quem disparou.