criar-skill

Criar uma skill

A pessoa pediu pra você automatizar um processo. O caminho tem 4 passos: triar se aquilo vira skill mesmo, escrever a skill, testar o disparo com ela e plantar na pasta dela. Leia esta skill inteira antes de propor qualquer coisa.

Passo 1: triagem (nem todo pedido vira skill)

Vira skill só o workflow repetível com gatilho próprio: um processo com passos e resultado, que a pessoa vai invocar de novo e que se reconhece numa frase ("processa a retro", "monta o report do comitê"). Pedido que não passa nesse filtro tem outro destino:

• Preferência que vale em toda interação (tom, formato de resposta, vocabulário): 1 linha no CLAUDE.md.
• Regra situacional de um tema ou tipo de arquivo ("quando mexer em nota de reunião, faça X"): arquivo de regra que só carrega quando o trabalho toca aqueles arquivos, e o CLAUDE.md continua leve (a mecânica está na camada de implementação, adiante).
• Disciplina de um passo de execução que 2 ou mais skills precisam ("antes de escrever a nota, aplique isto"): módulo compartilhado em .claude/skills/_shared/{nome}.md (mecânica na camada de implementação, adiante). Se só uma skill precisa, é arquivo na pasta daquela skill. E .claude/rules/ não substitui o módulo: regra com paths: dispara quando um arquivo é tocado, e disciplina de "antes de escrever" tem que carregar no meio da execução, antes de o arquivo existir.
• Ajuste em skill que já existe (semente plantada ou skill criada antes): edição direta daquela skill. Skill nova com gatilho vizinho de uma existente disputa o disparo com ela.

Diga qual destino o pedido tem e por quê, e siga pro passo 2 só com a confirmação da pessoa.

Passo 2: escrever a skill

Skill é instrução pra agente, e as restrições que valem pra qualquer instrução valem aqui: contexto é finito, instrução longa degrada qualquer modelo, gatilho vago não dispara em agente nenhum. As regras de autoria saem dessas restrições:

• description em 3ª pessoa: o QUE + QUANDO. O que a skill faz, quando usar (com os termos que a própria pessoa usaria pra pedir) e quando NÃO usar, apontando o destino certo. A description decide o disparo e o corpo só é lido depois: gatilho vago não dispara.
• Corpo é guia leve que confia no julgamento do modelo. Objetivo, etapas e as decisões de formato da pessoa, sem prescrever o que o agente resolve sozinho: instrução longa degrada a execução inteira. Regra rígida só em passo frágil ou destrutivo (sobrescrever, apagar, mandar algo pra fora), e sempre com o porquê: regra sem porquê quebra no primeiro caso que ela não previu, e o porquê é o que orienta o caso novo.
• Progressive disclosure. Corpo curto; template longo, tabela de referência ou detalhe que só serve em parte das execuções vai pra arquivo separado na mesma pasta da skill, que o corpo aponta. O detalhe só deve ocupar contexto quando a execução precisa dele.
• Artefato tem alvo em número. Skill que gera arquivo declara a mira ("nota de até 25 linhas", "1 linha por item"); sem número o output cresce a cada execução.
• Sem exemplos de uso engessados. Diálogo pronto e output modelo constrangem a exploração: o agente passa a imitar o exemplo em vez de resolver o caso real.
• A skill codifica a opinião e o jeito DA PESSOA. O formato de pauta dela, o vocabulário dela, o que ela considera pronto. Processo genérico que serviria pra qualquer um não carrega opinião e não precisa de skill.