Skills e Hooks no Claude Code: o que são, quando usar e como criar

Semana passada eu estava construindo skills pro meu projeto pessoal e caí numa pergunta besta que quase virou perda de tempo: "isso deveria ser uma skill ou um hook?"

Depois de errar a mão uma vez, ficou claro que são coisas bem diferentes, resolvem problemas diferentes, e confundir as duas custa caro em retrabalho. Este texto é o resumo prático que eu queria ter lido antes de começar.

O que é uma skill

Uma skill é uma pasta com um arquivo SKILL.md dentro (mais scripts ou templates opcionais). O arquivo abre com uma descrição curta, e é essa descrição que o Claude usa pra decidir se a skill é relevante pra tarefa que você pediu.

Se o pedido "casa" com a descrição, o Claude carrega o corpo inteiro do arquivo e segue o procedimento escrito ali. Se não casa, a skill nem entra no contexto, não custa token nenhum.

Isso faz da skill um tipo de conhecimento probabilístico: ela é conhecimento declarativo, o "como fazemos isso aqui", carregado sob demanda. O Claude pode seguir à risca, pode adaptar ao caso concreto, e em teoria pode até ignorar se achar que não se aplica. Por isso a especificidade da descrição importa tanto: descrição vaga significa que a skill não vai disparar quando devia, descrição específica demais significa que ela vai ficar de fora justamente quando seria útil.

Skills ficam em ~/.claude/skills/ (nível usuário) ou .claude/skills/ (nível repositório), e o Claude Code as descobre automaticamente, sem precisar registrar nada em configuração.

O que é um hook

Um hook é um script que roda em um momento fixo do ciclo de vida da sessão, por exemplo antes de uma tool ser usada (PreToolUse), depois (PostToolUse), no início da sessão, e por aí vai. Ele é configurado num JSON (.claude/settings.json), com o evento que dispara, um filtro opcional pra restringir a quais ferramentas ele se aplica, e o comando de shell que ele executa.

A diferença fundamental é que o hook roda fora do raciocínio do modelo. Ele recebe dados estruturados sobre o evento que disparou, mas não tem acesso ao histórico da conversa nem ao que o Claude está "pensando" naquele momento. Ele não decide nada, só executa a regra, sempre, sem exceção.

Isso faz do hook uma garantia determinística. Não importa se o Claude "achou" que estava tudo bem, se o gatilho aconteceu, o hook roda.

Por que a diferença importa na prática

Skill é julgamento. Ela carrega contexto e know how, mas ainda depende do Claude reconhecer a situação e decidir seguir o procedimento.

Hook é garantia. Ele não pede licença, só cumpre.

Se você usa skill pra algo que precisa ser inegociável (por exemplo, nunca fazer push sem revisão), corre o risco de o Claude, numa sessão cansada ou num contexto poluído, simplesmente não reconhecer a situação e pular a etapa. Se você usa hook pra algo que exige raciocínio (por exemplo, "como o nosso time versiona uma release"), ele não vai dar conta, porque hook não entende contexto, só executa comando.

Como criar uma skill

O mínimo é um SKILL.md com um cabeçalho de descrição e o procedimento escrito em linguagem natural, do jeito que você explicaria pra um colega novo no time. Vale a pena:

• Deixar explícito o que fazer em caso de ambiguidade (no meu caso, a regra é sempre parar e perguntar, nunca decidir sozinho por conta própria).
• Registrar que a skill é nova e vai ser ajustada com o uso real. Tratar o SKILL.md como algo vivo, versionado junto com o próprio código.
• Testar com casos reais do dia a dia, não só com o caso feliz.

Como criar um hook

O mínimo é uma entrada no settings.json apontando pro evento (PreToolUse, PostToolUse, etc.), um matcher se você quiser restringir a determinadas ferramentas, e o comando que vai rodar. O comando pode bloquear a ação (retornando um código de saída específico) ou só avisar e deixar seguir.

Vale pensar hook como a camada de enforcement da sua operação: lint antes de commit, bloqueio de escrita fora do repositório certo, checagem de pré-condição antes de uma ação irreversível.

Dois exemplos reais do meu setup

Skill de fechamento de versão. Antes, fechar uma versão era abrir a ferramenta de kanban, achar cada card de tarefa, achar o PR linkado, mergear um por um manualmente, repetitivo e fácil de esquecer card sem PR. A skill busca tudo via MCP e confirma cada merge individualmente comigo. Qualquer ambiguidade (card sem PR, conflito, PR duplicado) para e pergunta, nunca decide sozinha.

Skill de auto-revisão de PR, com um hook na ponta. A skill roda o diff contra as regras do próprio repositório, classifica cada achado por severidade, corrige o que é mecânico sozinha, e só libera abrir PR se não houver bloqueio crítico. O detalhe interessante é que, ao final, ela grava um marcador com o SHA revisado. Um hook do Claude Code lê esse marcador antes de deixar rodar o comando de abrir PR. Se o marcador não bate com o HEAD atual, o hook bloqueia.

Ou seja: a skill decide quando o código está pronto. O hook garante que ninguém, nem eu, nem o próprio Claude, pula a etapa só porque estava com pressa.

Quando usar cada um

Pergunta simples pra decidir: isso pode ser pulado sem quebrar nada crítico, ou não pode de jeito nenhum?

Se pode ser adaptado, ignorado ou seguido de forma flexível dependendo do contexto, é skill. Se precisa acontecer sempre, sem depender de o Claude lembrar ou concordar, é hook.

Na prática, as duas camadas se complementam melhor do que competem: skill carrega o conhecimento de como fazer, hook garante que a etapa obrigatória não seja pulada.