Skills do Claude Code Explicadas: Guia Completo (2026)

verificado com a documentação oficial em code.claude.com/docs/en/skills (acessada em 2026-08-09).

O que são as skills do Claude Code?

Se você já usa o Claude Code há algum tempo, provavelmente já desejou que ele simplesmente lembrasse como você gosta que uma tarefa repetitiva seja feita — "quando revisar código, siga esta checklist" ou "quando otimizar uma imagem, execute exatamente estes comandos". É esse o problema que as skills resolvem.

As skills do Claude Code são pacotes de instruções reutilizáveis e invocáveis pelo modelo — cada uma é uma pasta com um arquivo SKILL.md que diz ao Claude quando usá-la e como fazer a tarefa. Pense em uma skill como um cartão plastificado de "como fazemos este trabalho" preso na parede: o Claude lê os títulos para saber que cartões existem e só pega um e lê os detalhes quando uma tarefa exige.

Toda skill tem duas partes centrais:

• O frontmatter description — uma linha curta que diz o que a skill faz e quando disparar. É a parte que o Claude sempre "vê".
• O corpo em markdown — os passos detalhados, as convenções e os exemplos. Isso só carrega quando a skill é de fato invocada.

As skills não são uma invenção exclusiva do Claude. Elas seguem o padrão aberto Agent Skills (agentskills.io), o que significa que o mesmo formato SKILL.md funciona em diferentes superfícies do Claude e, em princípio, em outras ferramentas que adotem o padrão. Escreva uma skill uma vez e você pode reutilizá-la entre projetos, compartilhá-la com colegas ou instalar um pacote inteiro delas já pronto.

Uma mudança de 2026 que vale destacar de cara: os comandos de barra personalizados foram unificados com as skills. Os antigos arquivos .claude/commands/*.md ainda funcionam, mas agora um SKILL.md faz os dois papéis — o Claude pode invocá-lo automaticamente pela descrição, e ele também cria um comando /skill-name correspondente. Se você ler um tutorial escrito no começo de 2025 que trata "comandos" e "skills" como dois sistemas separados, esse é o modelo anterior à unificação.

Como as skills do Claude Code funcionam (divulgação progressiva)

Esta é a parte mais importante para entender por que as skills valem a pena, em vez de serem só "um jeito arrumado de guardar um prompt". O mecanismo se chama divulgação progressiva.

Quando o Claude Code inicia, ele não carrega o conteúdo completo de cada skill na janela de contexto. Em vez disso, carrega apenas a curta description de cada skill — o suficiente para saber "existe uma skill de code-review, uma skill de deploy, uma skill de otimização de imagens". Quando uma tarefa combina com uma dessas descrições, o Claude então lê o corpo completo daquela skill e o segue. Arquivos de apoio (um template, um documento de referência, um script) só carregam quando a skill os referencia explicitamente.

Aqui vai a intuição sobre custo de tokens. Se você despejar todas as convenções no seu CLAUDE.md, tudo fica no contexto a cada turno — incluindo os 90% de orientações que você raramente precisa, e você paga tokens por isso a cada turno. Com as skills, o "custo sempre ligado" é só algumas linhas de description por skill; o corpo pesado só entra no contexto no momento em que é preciso. É assim que as skills deixam você manter uma grande biblioteca de instruções sem inchar a janela de contexto.

Uma skill é ativada de uma entre duas formas:

• Automaticamente — o Claude compara o seu pedido com a description de cada skill e decide qual invocar. Você não faz nada além de descrever a tarefa; a skill só precisa de uma descrição clara.
• Manualmente com /skill-name — você chama uma skill específica diretamente, por exemplo /code-review. Prático quando você quer forçar o Claude por um fluxo exato.

Como o Claude conta com a description para a seleção automática, a qualidade dessa única linha decide se a skill dispara no momento certo. Uma descrição vaga como "ajuda com imagens" faz o Claude hesitar; uma rica em gatilhos como "use ao converter PNG para WebP e comprimir abaixo de 200KB" dispara quase sempre.

Skills vs comandos, subagents, hooks e MCP

É aqui que quem está começando se enrola — o Claude Code tem toda uma família de conceitos que soam parecidos. Aqui vai uma comparação rápida, uma ou duas linhas cada, para você situá-los:

A distinção-chave: uma skill é markdown mais scripts que molda como o Claude trabalha, enquanto o MCP é um protocolo de ferramentas que dá ao Claude novas capacidades de sistemas externos. Eles se complementam — uma skill pode descrever como usar bem uma ferramenta conectada por MCP. Se você quer o detalhamento completo de onde cada conceito começa e termina, escrevi um aprofundamento dedicado: skills vs subagents vs hooks vs MCP.

Onde as skills ficam (pessoal, projeto, plugin, empresa)

Onde você coloca a pasta da skill decide o alcance dela. O Claude Code procura skills em vários lugares, em ordem de prioridade:

Use skills pessoais para os seus próprios hábitos em todo tipo de trabalho, e skills de projeto para convenções que pertencem a um repositório específico (faça commit de .claude/skills/ e todo mundo no time as recebe). Um detalhe bacana: o Claude Code detecta mudanças nos seus arquivos de skill ao vivo — edite um SKILL.md e ele pega a nova versão sem reiniciar, o que deixa a iteração numa skill bem rápida.

Anatomia de um arquivo SKILL.md

No nível de arquivo, uma skill é surpreendentemente simples: é só uma pasta nomeada com o slug da skill, contendo um SKILL.md obrigatório. Você pode adicionar arquivos de apoio opcionais — templates, scripts, exemplos — para a skill referenciar quando roda:

~/.claude/skills/optimize-web-image/
├── SKILL.md (required)
├── template.md (optional - output template)
├── examples/ (optional - reference examples)
└── scripts/convert.sh (optional - helper script)

O próprio SKILL.md é um frontmatter YAML seguido de um corpo em markdown. Aqui vai uma skill real e executável:

---
name: optimize-web-image
description: Convert a PNG to WebP and compress under 200KB. Use when the user needs to optimize an image for the web.
allowed-tools: Bash, Read
---

# Optimize web image

When asked to optimize an image:

1. Run `cwebp -q 80 input.png -o output.webp`.
2. Check the output file size. If it is still over 200KB,
 drop quality to `-q 70` and run again.
3. Report the new file path and its final size.

É isso. O frontmatter diz ao Claude quando usar a skill; o corpo diz como. Aqui estão os campos de frontmatter que você mais vai usar (veja a documentação oficial para a lista completa):

Uma regra prática: mantenha o SKILL.md abaixo de umas 500 linhas. Assim que uma skill é invocada, o corpo dela entra no contexto e fica lá pela sessão inteira, então um corpo inchado custa tokens — mova material de referência longo para arquivos de apoio e aponte para eles só quando necessário.

Crie a sua primeira skill em 5 minutos (passo a passo)

Vamos construir uma skill pequena, mas de verdade útil: summarize-changes, que transforma o seu git diff recente em um resumo em linguagem simples. Três passos.

1. Crie a pasta (escopo pessoal, para funcionar em todos os projetos):

   mkdir -p ~/.claude/skills/summarize-changes

2. Escreva o SKILL.md em ~/.claude/skills/summarize-changes/SKILL.md:

   ---
   name: summarize-changes
   description: Summarize the current git changes in plain English, grouped by area. Use when the user asks what changed or wants a PR summary.
   allowed-tools: Bash, Read
   ---
   
   # Summarize changes
   
   1. Run `git diff --stat` and `git diff` for uncommitted changes.
   2. Group edits by area (feature, fix, docs, tests, chore).
   3. Write 3-6 bullet points in plain English - what changed and why
    it matters - short enough to paste into a pull request.

3. Teste de duas formas. Abra o Claude Code em um repositório com algumas edições não commitadas e digite o comando diretamente — /summarize-changes — ou apenas peça de forma natural: "resuma o que eu mudei". Se a sua description for clara, o pedido natural dispara a skill sem você nomeá-la.

Como o Claude Code detecta os arquivos de skill ao vivo, você não precisa reiniciar — a skill fica disponível no instante em que você salva o arquivo.

Uma skill em ação (exemplo real + opinião honesta)

A skill summarize-changes acima é uma que eu mesma mantenho na minha pasta pessoal, e é uma boa ilustração de quando uma skill se justifica — e quando não.

Antes: no fim de uma sessão eu pedia ao Claude "escreva uma descrição de PR para mim" e recebia algo genérico, apoiado nas mensagens de commit e sem o porquê. Depois: com a skill, as instruções o obrigam a ler o diff de verdade e agrupar por área, então o resumo reflete o que realmente mudou, não o que rotulei nos meus commits. A saída é consistente toda vez, porque os passos vivem na skill e não na minha memória de como escrevi da última vez.

O que não funcionou no começo: a minha description inicial era só "summarize git changes", e às vezes o Claude a ignorava e respondia pelo histórico de commits. Adicionar o gatilho concreto — "use quando o usuário perguntar o que mudou ou quiser um resumo de PR" — corrigiu a invocação automática. Essa é a lição honesta: uma skill vale só o que vale a descrição dela, e você deve esperar iterar nessa única linha algumas vezes.

A outra ressalva honesta: este é um trabalho pequeno e no formato de tarefa, que é exatamente para o que servem as skills. Se eu tivesse tentado codificar todo o estilo de código do meu repositório em uma skill, esse seria o lugar errado — estilo que se aplica a todo turno pertence ao CLAUDE.md, não a uma skill que só carrega na invocação.

Avançado: contexto dinâmico e rodar uma skill como subagent

Dois recursos deixam as skills mais poderosas quando você já está confortável com o básico.

Injeção de contexto dinâmico. Você pode embutir um comando de shell no seu SKILL.md usando a sintaxe ` !`command` `, e o Claude Code o executa e injeta a saída antes de o Claude ler o corpo da skill. Isso significa que a skill pode agir sobre o estado ao vivo, e não sobre texto estático:

---
name: summarize-changes
description: Summarize the current git diff in plain English.
---

# Summarize changes

Here is the current diff:

!`git diff HEAD`

Summarize the changes above, grouped by area, in 3-6 bullets.

A linha ` !`git diff HEAD` ` é executada quando a skill carrega, então o Claude já vê o diff real inline — sem precisar de uma chamada de ferramenta separada.

Rodar uma skill como subagent. Defina context: fork no frontmatter e a skill roda em um subagent isolado, com sua própria janela de contexto, devolvendo só o resultado para a sua sessão principal:

---
name: summarize-changes
description: Summarize the current git diff in an isolated subagent.
context: fork
---

Isso é ideal para trabalhos pesados em tokens — revisar um diff enorme, varrer muitos arquivos — porque o trabalho intermediário volumoso fica no contexto forkado e nunca bagunça a sua conversa principal. Se você quer entender como skills forkadas se relacionam com subagents completos, essa fronteira é coberta na comparação skills vs subagents vs hooks vs MCP.

Não construa tudo — pacotes de skills prontos

Escrever skills à mão é ótimo quando você quer moldar um fluxo exato. Mas se você só quer uma biblioteca sólida para trabalhos comuns — frontend, backend, banco de dados, DevOps, revisão de código — não precisa escrever cada SKILL.md você mesma. Você pode instalar um pacote de skills selecionado.

Uma opção popular é o AgentKit, um pacote de skills pronto para o Claude Code (instalado pela sua CLI ak) que traz mais de 108 skills prontas. (AgentKit aqui é o kit para o Claude Code — CLI ak, em agentkit.best — não o AgentKit da OpenAI.) O Engineer Kit dele está listado por US$ 99, com atualizações vitalícias e garantia de reembolso; a página não menciona nenhuma cobrança recorrente. Se você prefere comparar algumas opções antes, a minha seleção dos melhores kits de Claude Code em 2026 coloca elas lado a lado. Você também pode conhecer o pacote de skills AgentKit (20% de desconto pelo link) e julgar por conta própria.

Escreva as suas próprias skills primeiro se as suas necessidades forem pequenas; um kit só compensa quando você quer pular a construção de uma grande biblioteca do zero.

Boas práticas e limitações

As skills são práticas, mas não são "instale e está perfeito". Aqui vai o retrato honesto:

• As descrições estão sempre no contexto. A descrição de uma linha de cada skill fica na janela de contexto o tempo todo. Esse custo é minúsculo por skill, mas instalar dezenas de skills que se sobrepõem soma e pode dificultar para o Claude escolher a certa — mantenha nomes e descrições distintos.
• O modelo pode ignorar uma skill. Se uma skill não dispara sozinha, a descrição quase sempre está vaga demais. Reforce-a com um gatilho concreto ("use quando…"), ou simplesmente chame-a manualmente com /skill-name.
• Uma skill invocada persiste entre turnos. A divulgação progressiva economiza tokens na parte "ainda não usada", mas, uma vez que uma skill carrega, o corpo dela fica no contexto pela sessão. Mantenha os corpos curtos e mova material de referência longo para arquivos de apoio.
• Proteja as ações com efeitos colaterais. Para skills que fazem deploy, apagam ou escrevem em produção, defina disable-model-invocation para o Claude não poder dispará-las por conta própria — você as invoca de propósito.
• Não faça de tudo uma skill. Convenções que se aplicam a todo turno (o estilo geral de código do seu repositório) ainda pertencem ao CLAUDE.md; as skills são para fluxos por tarefa. Escolher o lugar certo é o que mantém os tokens eficientes. Você também pode usar a ferramenta skill-creator para avaliar a taxa de acerto de uma skill em relação ao custo de tokens antes de se comprometer com ela.

Perguntas frequentes

As skills do Claude Code são gratuitas?

Sim — as skills são um recurso nativo do Claude Code, então usá-las e escrever as suas não custa nada além do seu plano atual do Claude Code (por exemplo, o Pro a US$ 20/mês). Um custo só aparece se você optar por comprar um pacote de skills pronto de terceiros.

Skills vs MCP — qual é a diferença?

Uma skill é uma instrução em markdown (mais scripts opcionais) que molda como o Claude faz uma tarefa. O MCP é um protocolo que conecta o Claude a ferramentas e dados externos. As skills mudam o comportamento; o MCP adiciona capacidades. Eles trabalham juntos — uma skill pode descrever como usar bem uma ferramenta conectada por MCP.

Onde eu coloco uma skill?

Coloque skills pessoais em ~/.claude/skills/ (disponíveis em toda a sua máquina) e skills de projeto em .claude/skills/ dentro de um repositório (faça commit para compartilhar com o time). Cada skill é a sua própria pasta contendo um SKILL.md.

O Claude pode invocar uma skill automaticamente?

Sim. O Claude compara o seu pedido com a description de cada skill e invoca a que melhor combina — você não precisa nomeá-la. Você também pode chamar uma manualmente com /skill-name ou definir disable-model-invocation para exigir a invocação manual.

As skills funcionam também no app e na API do Claude?

Sim. As skills seguem o padrão aberto Agent Skills, então também funcionam nos apps do Claude (Pro, Max, Team, Enterprise) e via Developer Platform / Skills API. O Claude Code adiciona extras específicos do terminal, como controle de invocação, execução em subagent e injeção de contexto dinâmico.

Como uma skill difere do CLAUDE.md?

O CLAUDE.md guarda convenções que se aplicam a todo turno e fica no contexto o tempo todo. Uma skill guarda instruções para uma tarefa específica e, graças à divulgação progressiva, só carrega o corpo completo quando é invocada. Use o CLAUDE.md para regras sempre ligadas e as skills para fluxos por tarefa.

Conclusão e próximos passos

As skills do Claude Code são um jeito limpo de ensinar um trabalho ao Claude, uma tarefa por vez: uma pasta, um SKILL.md, disparado automaticamente ou com /skill-name, e mantido barato pela divulgação progressiva. Daqui, leia o detalhamento completo de skills vs subagents vs hooks vs MCP para situar toda a família de conceitos, releia o que é o Claude Code se você ainda está se ambientando, e, se prefere começar de uma biblioteca pronta em vez de um arquivo em branco, experimente o pacote de skills AgentKit (20% de desconto pelo link) antes de escrever a sua do zero.