---
title: "Como criar skills no Claude Code: SKILL.md, escopo e testes"
description: "Aprenda a criar skills no Claude Code: estrutura do SKILL.md, onde salvar (global ou projeto), como escrever a description e como testar se a skill é acionada."
url: "https://williandsantos.com/videos/como-criar-skills-no-claude-code-o-que-e-onde-salvar-e-como-testar/"
language: "pt-BR"
---

Vídeo · Inteligência Artificial

# Como criar skills no Claude Code: SKILL.md, escopo e testes

Aprenda a criar skills no Claude Code: estrutura do SKILL.md, onde salvar (global ou projeto), como escrever a description e como testar se a skill é acionada.

Duração

10:07

Capítulos

13

Publicado

12 NOV

[Inscrever-se no canal →](https://www.youtube.com/@williandsantos?sub%5Fconfirmation=1) [Ler o resumo ↓](#resumo)

WDS // Vídeo [YouTube](https://www.youtube.com/watch?v=ERRArU7fF18)

[![](https://i.ytimg.com/vi/ERRArU7fF18/maxresdefault.jpg)](https://www.youtube.com/watch?v=ERRArU7fF18)

## 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](https://www.youtube.com/watch?v=ERRArU7fF18&t=0s) O que você vai ter no final
- [0:24](https://www.youtube.com/watch?v=ERRArU7fF18&t=24s) O que é uma skill
- [1:09](https://www.youtube.com/watch?v=ERRArU7fF18&t=69s) Onde a skill mora: global ou no projeto
- [1:55](https://www.youtube.com/watch?v=ERRArU7fF18&t=115s) Uma skill pronta por dentro
- [3:32](https://www.youtube.com/watch?v=ERRArU7fF18&t=212s) Criando a sua primeira skill
- [4:39](https://www.youtube.com/watch?v=ERRArU7fF18&t=279s) A description e o gancho
- [5:26](https://www.youtube.com/watch?v=ERRArU7fF18&t=326s) As instruções em Markdown
- [6:04](https://www.youtube.com/watch?v=ERRArU7fF18&t=364s) Testando pelo nome
- [6:36](https://www.youtube.com/watch?v=ERRArU7fF18&t=396s) O resultado: resumo e riscos
- [7:42](https://www.youtube.com/watch?v=ERRArU7fF18&t=462s) Testando com um pedido normal
- [8:04](https://www.youtube.com/watch?v=ERRArU7fF18&t=484s) Quando a skill não dispara
- [8:39](https://www.youtube.com/watch?v=ERRArU7fF18&t=519s) Nada de skill gigante
- [9:41](https://www.youtube.com/watch?v=ERRArU7fF18&t=581s) 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](https://williandsantos.com/cursos/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](https://williandsantos.com/blog/ia-aplicada-sistema-confiavel/): 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](https://williandsantos.com/blog/revisao-humana-e-parte-do-workflow/): 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](https://williandsantos.com/cursos/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.

[Entrar na lista de espera →](https://williandsantos.com/cursos/video-builder-ia/#inscricao)

// 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 →](https://www.youtube.com/@williandsantos?sub%5Fconfirmation=1)

Próximo vídeo 

## [Codex vs Claude Code: como usar o Codex no VS Code e qual escolher](https://williandsantos.com/videos/por-que-uso-as-duas-codex-vs-claude-code-no-vs-code/)

![](https://williandsantos.com/assets/author/avatar-128.webp)

## Willian D. Santos

Desenvolvedor, builder e founder construindo sistemas e produtos em público.

[Sobre mim →](https://williandsantos.com/sobre/) [Artigos →](https://williandsantos.com/autor/willian-d-santos/)

Tags 

claude code skills criar skill claude code skill md frontmatter claude code tutorial comandos personalizados claude code

Continue assistindo 

## Mais vídeos sobre o tema

[Ver todos os vídeos →](https://williandsantos.com/videos/)

Vídeo 12 min

### [Criar software com IA ou assinar: como decidir o que compensa](https://williandsantos.com/videos/vale-a-pena-trocar-tudo-por-ia-a-matematica-por-tras-da-decisao/)

Criar software com IA saiu mais barato, mas manter, hospedar e proteger custa. Veja os custos que ficam fora da conta e como decidir entre construir ou assinar.

YouTube [Assistir →](https://williandsantos.com/videos/vale-a-pena-trocar-tudo-por-ia-a-matematica-por-tras-da-decisao/)

Vídeo 13 min

### [Claude Code no Windows: como instalar e criar seu primeiro projeto](https://williandsantos.com/videos/claude-code-do-zero-no-windows-instalacao-e-primeiro-projeto/)

Aprenda como instalar o Claude Code no Windows pelo app desktop, escolher o plano, criar o primeiro ambiente e configurar permissões e o CLAUDE.md com segurança.

YouTube [Assistir →](https://williandsantos.com/videos/claude-code-do-zero-no-windows-instalacao-e-primeiro-projeto/)

Vídeo 17 min

### [Como criar um agente de IA no Claude Code (passo a passo)](https://williandsantos.com/videos/o-jeito-certo-de-criar-agentes-no-claude-code/)

Aprenda a criar um agente de IA no Claude Code com a pasta .claude/agents: quando usar, quais ferramentas liberar, como testar e os erros mais comuns.

YouTube [Assistir →](https://williandsantos.com/videos/o-jeito-certo-de-criar-agentes-no-claude-code/)

Leia também 

## Artigos sobre o mesmo tema

[Ver o blog →](https://williandsantos.com/blog/)

[Inteligência Artificial](https://williandsantos.com/blog/categoria/inteligencia-artificial/) 20 de nov. de 2026

### [Edição de vídeo com IA: como funciona do bruto ao publicado](https://williandsantos.com/blog/edicao-de-video-com-ia/)

Entenda a edição de vídeo com IA, do vídeo bruto ao publicado: o que a IA faz em cada etapa, o que continua sendo sua decisão e como começar.

16 min de leitura [Ler →](https://williandsantos.com/blog/edicao-de-video-com-ia/)

[Inteligência Artificial](https://williandsantos.com/blog/categoria/inteligencia-artificial/) 09 de set. de 2026

### [IA aplicada: como montar um sistema de IA confiável](https://williandsantos.com/blog/ia-aplicada-sistema-confiavel/)

Como levar a IA do teste no chat para o processo real: tarefa delimitada, contexto, avaliação, travas e monitoramento, com passo a passo e erros comuns.

9 min de leitura [Ler →](https://williandsantos.com/blog/ia-aplicada-sistema-confiavel/)

[Inteligência Artificial](https://williandsantos.com/blog/categoria/inteligencia-artificial/) 02 de set. de 2026

### [Revisão humana em automação com IA: quando e como fazer](https://williandsantos.com/blog/revisao-humana-e-parte-do-workflow/)

Como desenhar a revisão humana em automações com IA: onde colocar a etapa, quem revisa, quais critérios usar e como evitar que vire gargalo ou carimbo.

8 min de leitura [Ler →](https://williandsantos.com/blog/revisao-humana-e-parte-do-workflow/)
