Sumário · 11 seções0% lido
Resumo
Uma skill no Claude Code é uma pasta com um arquivo SKILL.md. O cabeçalho (frontmatter) traz nome e descrição, e é a descrição que o Claude usa para decidir quando chamar a skill. Salve em ~/.claude/skills para uso global ou em .claude/skills dentro do projeto, e teste chamando pelo /nome e também em linguagem natural.
O que o vídeo mostra
O vídeo mostra uma skill pronta do estúdio de edição do Willian, que edita Reels com scripts em Python. Depois ele cria do zero, ao vivo, uma skill que resume as mudanças do Git ainda não commitadas e aponta riscos. Você vê por que uma descrição vaga não funciona, como escrever o gancho e as duas formas de acionar a skill.
- 0:00 O que você vai ter no final
- 0:24 O que é uma skill
- 1:09 Onde a skill mora: global ou no projeto
- 1:55 Uma skill pronta por dentro
- 3:32 Criando a sua primeira skill
- 4:39 A description e o gancho
- 5:26 As instruções em Markdown
- 6:04 Testando pelo nome
- 6:36 O resultado: resumo e riscos
- 7:42 Testando com um pedido normal
- 8:04 Quando a skill não dispara
- 8:39 Nada de skill gigante
- 9:41 Ficou com dúvida?
O que é uma skill no Claude Code e do que ela é feita?
Uma skill é uma pasta com um arquivo principal chamado SKILL.md. Dentro desse arquivo ficam duas partes: o frontmatter, que é o bloco entre três tracinhos no topo, e as instruções em Markdown logo abaixo.
O frontmatter leva o nome e a descrição. A descrição é o que o Claude lê para decidir se aquela skill serve para o pedido que você fez. Já as instruções só são lidas depois que ele decide usar a skill.
Na mesma pasta você pode colocar arquivos complementares e scripts. No estúdio do Willian, por exemplo, há scripts em Python que cortam, decupam e montam os Reels. A skill funciona como um pacote: instruções mais os arquivos de que a tarefa precisa.
Essa divisão tem uma consequência prática. O Claude mantém no contexto só o frontmatter de cada skill. O corpo do SKILL.md e os arquivos extras são carregados quando a skill é usada. Por isso você pode ter várias skills instaladas sem encher o contexto de texto que não está sendo usado.
Onde salvar uma skill: global ou só no projeto?
O local define o escopo. Para a skill valer em qualquer projeto, salve a pasta em ~/.claude/skills, na instalação do Claude no seu sistema, seja Windows, Linux ou Mac. Para valer só em um projeto, crie .claude/skills dentro dele e coloque a pasta lá.
Skill de projeto só é vista por aquele projeto. Se mais tarde você perceber que ela serve para tudo, basta copiar a pasta para o diretório global.
Um critério simples para decidir:
- Global: tarefas que você repete em qualquer lugar, como revisar um diff, escrever mensagem de commit ou padronizar um formato de resposta.
- Projeto: tarefas que dependem de regras, arquivos ou scripts daquele projeto específico.
- Na dúvida, comece no projeto. É mais seguro testar ali e promover depois para global.
Como escrever a description para o Claude chamar a skill?
A descrição é a parte mais importante da skill. Se ela for vaga, o Claude não reconhece quando usar. No vídeo, o Willian parte de algo subjetivo, evolui para algo descritivo e só então funciona, quando acrescenta o que ele chama de gancho.
O gancho diz duas coisas: o que a skill faz e em que situações ela deve ser usada. No exemplo do vídeo, a descrição diz que a skill resume as mudanças e aponta os riscos, e que deve ser usada quando o usuário perguntar o que mudou, pedir uma mensagem de commit ou pedir a revisão de um diff.
Na prática, escreva a descrição pensando em como você realmente pede a tarefa. Use as mesmas palavras que você digitaria no chat. Se você costuma dizer "o que mudou?", essa frase deve estar lá.
- Comece pela ação: o que a skill entrega.
- Liste os gatilhos: perguntas e pedidos que devem ativá-la.
- Seja específico sobre o escopo, para ela não disparar em tarefas parecidas mas diferentes.
- Evite descrições genéricas como "ajuda com código".
Como criar a skill do zero, passo a passo?
O exemplo do vídeo é uma skill local chamada resumir-mudancas. Crie a pasta com esse nome dentro de .claude/skills e, nela, o arquivo SKILL.md.
No topo, abra o frontmatter com três tracinhos, preencha name (igual ao nome da pasta) e description (com o gancho), e feche com mais três tracinhos. Abaixo, escreva as instruções em Markdown: títulos e passos simples, incluindo o comando que o Claude deve executar. No vídeo, o comando consulta as mudanças atuais do Git.
Escreva as instruções como se fosse explicar a tarefa para uma pessoa nova no projeto. Diga o objetivo, o que olhar, o formato da resposta e o que fazer em caso de dúvida. Quanto mais claro o formato de saída, mais previsível o resultado.
Depois de salvar, abra uma nova sessão. No vídeo, o Willian atualiza e abre uma sessão nova antes de testar, para garantir que a skill foi carregada.
Como testar se a skill funciona de verdade?
Existem dois jeitos de acionar uma skill, e vale testar os dois. O primeiro é digitar / e o nome da skill. As skills nativas do Claude aparecem junto com as suas, e ao executar ele lê o arquivo e segue as instruções. No vídeo, o resultado trouxe o resumo das mudanças e os riscos, incluindo um problema real de rodízio de layouts que o Willian queria investigar.
O segundo é pedir em linguagem natural, com palavras próximas às da description. Esse teste é o mais revelador. Se a skill não for acionada, a causa mais provável é uma descrição genérica demais, sem gancho claro.
Quando o teste em linguagem natural falhar, ajuste a descrição, não as instruções. Reescreva os gatilhos com frases mais parecidas com o seu pedido, salve e teste de novo em uma sessão nova.
Por que manter cada skill pequena e específica?
Uma skill que tenta cobrir um fluxo inteiro e complexo tende a ficar enorme, confusa e difícil de acionar na hora certa. Quando ela é carregada, entra muito texto no contexto, o que aumenta o gasto de tokens e a chance de a IA se perder.
O caminho mostrado no vídeo é quebrar por atividade. O estúdio do Willian tem uma skill para cada etapa: decupagem, criação de motion, montagem de Reels e assim por diante. Cada uma faz uma coisa só.
Um bom sinal de que a skill está grande demais é quando a descrição precisa de muitos "e também" para explicar o que ela faz. Nesse caso, divida em duas ou mais.
Para aplicar
- Liste as instruções que você mais repete para a IA e escolha uma para virar skill.
- Decida o escopo: global em ~/.claude/skills ou só no projeto em .claude/skills.
- Crie a pasta e o SKILL.md com name igual ao nome da pasta.
- Escreva a description com o que a skill faz e os pedidos que devem ativá-la, usando suas próprias palavras.
- Redija as instruções em Markdown, com o comando a executar e o formato esperado da resposta.
- Abra uma nova sessão e teste primeiro com /nome-da-skill.
- Teste de novo pedindo em linguagem natural e, se falhar, reescreva a description antes de mexer no resto.
Perguntas frequentes
Preciso de scripts para criar uma skill?
Não. O mínimo é uma pasta com um SKILL.md contendo nome, descrição e instruções. Scripts e arquivos complementares só entram quando a tarefa realmente precisa deles.
Posso transformar uma skill de projeto em global depois?
Sim. Basta copiar a pasta da skill para ~/.claude/skills, na instalação do Claude no seu sistema. A partir daí ela fica disponível em qualquer projeto.
Minha skill não é acionada quando peço em linguagem natural. O que fazer?
Quase sempre o problema é a description genérica. Reescreva com um gancho explícito: o que a skill faz e em quais pedidos ela deve ser usada, com palavras parecidas com as que você usa. Salve e teste em uma sessão nova.
Ter muitas skills deixa o Claude mais lento ou mais caro?
Pouco, porque o Claude mantém no contexto só o frontmatter de cada skill. O conteúdo completo é lido apenas quando a skill é usada. O que pesa é uma skill única e gigante.
O nome da skill precisa ser igual ao da pasta?
No exemplo do vídeo, o Willian repete o nome da pasta no campo name. Seguir esse padrão evita confusão e facilita chamar a skill com /nome.
Para continuar
- Video Builder IA: O vídeo usa como exemplo um estúdio de edição de vídeo operado com skills; o curso é o próximo passo para quem quer construir produção de vídeo com IA.
- IA aplicada: como montar um sistema de IA confiável: Ajuda a pensar em como montar um sistema de IA confiável, o que complementa o uso de skills no dia a dia.
- Revisão humana em automação com IA: quando e como fazer: Mostra quando e como manter revisão humana em fluxos com IA, útil para revisar o que suas skills produzem.
// Curso · WDS Builders
Video Builder IA
Você grava o seu vídeo e dirige um agente de IA que transcreve, corta, legenda, anima e renderiza. Nada avança sem a sua aprovação. Do bruto ao vídeo publicado.
// Canal no YouTube
Inscreva-se no canal
IA aplicada, automação e os bastidores do que estou construindo, mostrados na prática.
Inscrever-se no canal →







