Como funcionam as skills do Claude Code por dentro (e o que faz o modelo decidir carregar uma)

Fala aí, beleza? Skill não é plugin mágico, nem prompt salvo, nem configuração escondida: é uma pasta com um arquivo SKILL.md dentro, e o modelo decide se lê ou não

Se você chegou pelo termo genérico "skill", criou a pasta, escreveu instrução boa e viu o Claude simplesmente ignorar tudo, respira: o problema quase nunca está no conteúdo que você escreveu

Está no gatilho de ativação, que é uma parte bem pequena do arquivo

Então bora destrinchar o mecanismo por dentro, camada por camada, até ficar óbvio por que uma skill sobe e outra fica dormindo pra sempre 😀

(e se a sua dúvida ainda for a diferença entre skills, comandos e subagentes, esse é outro papo, aqui a gente foca no funcionamento da skill)

Anatomia de uma skill: a pasta, o SKILL.md e o que é opcional

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Uma skill é uma pasta

Dentro dela, o único componente obrigatório é um arquivo chamado SKILL.md

Esse arquivo tem duas partes bem separadas: um frontmatter YAML no topo e as instruções em Markdown logo abaixo

O resto é opcional, e é aí que mora a confusão de quem acha que precisa de uma estrutura enorme pra começar

minha-skill/
  SKILL.md        (obrigatório)
  scripts/        (opcional)
  references/     (opcional)
  assets/         (opcional)

A especificação prevê diretórios opcionais pra scripts, references e assets

"Mas pra que isso, se as instruções já estão no SKILL.md?"

Porque nem tudo precisa estar na cara do modelo o tempo todo

O SKILL.md é o que o Claude lê quando decide usar a skill, e os arquivos extras são material de apoio, puxados só quando a instrução mandar

Se você já mexeu com NPM ou composer, a lógica é familiar: um arquivo pequeno descreve a coisa, e o peso de verdade fica em arquivos separados

Os campos do frontmatter: name, description e os extras do Claude Code

O frontmatter exige no mínimo dois campos: name e description

E cada um tem regra própria, que não é decorativa:

Na prática, o topo do arquivo fica assim:

---
name: revisor-de-migration
description: Revisa arquivos de migration de banco procurando alteração destrutiva e falta de rollback. Use quando o usuário pedir revisão de migration ou for aplicar mudança de schema.
---

# Revisor de migration

Instruções em Markdown daqui pra baixo...

Repara que o --- de abertura é a PRIMEIRA linha do arquivo

Isso não é frescura de formatação: o Claude Code só lê o frontmatter quando o delimitador de abertura está ali na linha 1

Uma linha em branco antes, um título solto, um comentário, e o frontmatter deixa de existir pro Claude Code

Quando usar allowed-tools e disable-model-invocation:

allowed-tools faz sentido quando a skill é de análise e você não quer que ela saia executando coisa que não precisa

É um guardrail (limite) simples, e limite explícito é sempre melhor que torcida

Já disable-model-invocation: true serve pra skill que você quer no repertório mas NÃO quer que o modelo puxe sozinho

Com ele ligado, o carregamento automático some, e a skill vira uma coisa que você chama na mão quando decidir

Divulgação progressiva: os três níveis que economizam contexto

Agora o porquê antes do como

Skills usam divulgação progressiva (progressive disclosure), em três níveis:

Ou seja: na inicialização, apenas o name e a description de cada skill instalada entram no system prompt do agente

O conteúdo completo NÃO é carregado de saída

E isso é o ponto mais importante do desenho todo: a janela de contexto fica limpa até a skill ser realmente útil

Pensa no custo do contrário

Se cada skill instalada despejasse o arquivo inteiro no começo da conversa, dez skills já comeriam um pedaço absurdo de contexto antes de você digitar a primeira palavra

Com os três níveis, o que fica sempre ligado é só um cartãozinho de apresentação

Por que o Claude decide usar (ou ignorar) uma skill

Aqui está o coração da coisa

Na hora de decidir, o modelo enxerga só o nível 1: name e description

O corpo do SKILL.md, aquele texto lindo que você caprichou, NÃO participa da decisão

Ele só é lido depois, quando o Claude já julgou a skill relevante e foi buscar o arquivo no sistema de arquivos pra trazer as instruções pra janela de contexto

Por isso a description é o sinal primário de ativação

E a documentação é direta na recomendação: ela deve dizer o que a skill faz e quando ela deve ser usada

O quê + quando, na prática:

Description vaga:

description: Ajuda com banco de dados

O modelo não tem sinal nenhum pra agir

"Ajuda" quando? Em qual situação? Com qual tipo de pedido? A skill vira invisível

Description com o "o quê" e o "quando":

description: Revisa arquivos de migration de banco procurando alteração destrutiva e falta de rollback. Use quando o usuário pedir revisão de migration ou for aplicar mudança de schema.

Agora existe um mapa entre o pedido do usuário e a skill

A ativação deixa de ser sorte e vira previsível

A regrinha mental é essa: escreva a description pensando em quem vai ler ela sem ter lido o resto do arquivo, porque é exatamente o que acontece

Skill criada mas o Claude não carrega: causas prováveis

O sintoma é sempre igual: a pasta existe, o arquivo existe, e o Claude segue a vida como se nada estivesse ali

As causas prováveis, essas sim, são poucas e verificáveis

Bora na ordem, da mais comum pra menos:

1. Description genérica ou sem o "quando": se o texto não descreve a situação de uso, o modelo não tem gatilho pra ativar. Reescreva com o "o quê" e o "quando" e teste de novo

2. O --- não é a primeira linha do arquivo: sem o delimitador de abertura na linha 1, o Claude Code não lê o frontmatter, e sem frontmatter não existe name nem description pra entrar no system prompt. O erro comum aqui é deixar uma linha em branco ou um título Markdown antes do bloco

3. name fora do padrão: o campo aceita apenas letras minúsculas, números e hífens, com máximo de 64 caracteres. Maiúscula, espaço, acento ou underline já quebram a regra

4. disable-model-invocation: true ligado: nesse caso está tudo funcionando como projetado, o carregamento automático é que está bloqueado de propósito. Vale ler o frontmatter linha por linha antes de suspeitar de qualquer outra coisa

5. Pasta no lugar errado: skill fora dos diretórios que o Claude Code lê não é skill, é arquivo Markdown perdido no disco (o próximo tópico resolve isso)

Como separar problema de ativação de problema de conteúdo:

Esse é o truque que economiza tempo

Além da ativação automática pelo modelo, você pode chamar uma skill explicitamente digitando /<name> no Claude Code

Então faça o teste:

• se a chamada manual funciona e a automática não, o problema está no frontmatter (description, name, disable-model-invocation)
• se nem a manual funciona, o problema é antes disso: arquivo, delimitador ou localização da pasta

Revise o frontmatter ANTES de mexer em qualquer outra coisa

É onde mora quase todo defeito de ativação

Onde as skills ficam: pessoais, de projeto e distribuídas como plugin

No Claude Code existem dois escopos, e escolher errado é fonte silenciosa de frustração

A decisão é bem direta

Skill que reflete o SEU jeito de trabalhar (padrão de commit, estilo de revisão, atalho pessoal) vai em ~/.claude/skills

Skill que reflete regra DAQUELE código (convenção do time, fluxo de deploy do projeto, formato de teste) vai em .claude/skills e entra no repo junto com o resto

E quando é pra distribuir?

Skills também podem ser distribuídas como plugins no Claude Code

O fluxo tem dois passos: você adiciona um marketplace e depois instala o plugin

/plugin marketplace add <fonte>
/plugin install <plugin>@<marketplace>

É o caminho pra quando a skill deixa de ser sua e passa a ser de mais gente

Para onde ir depois: a spec aberta e o repositório da Anthropic

Um detalhe que muita gente perde: Agent Skills é uma especificação ABERTA, publicada e mantida em site próprio

O agentskills.io tem página de specification, de skill creation e de integração por outros agentes

Ou seja, o formato pasta + SKILL.md não é um detalhe interno de um produto só, é um padrão documentado publicamente

Quem quiser entender melhor onde uma skill roda de verdade tem esse desdobramento inteiro pra explorar

E pra ver estrutura real em vez de exemplo de blog, a Anthropic mantém um repositório público de Agent Skills no GitHub

Lá dentro tem inclusive a skill-creator

Abrir esse arquivo e ler o frontmatter dele vale mais que qualquer template genérico, porque é skill de verdade, escrita por quem definiu o formato 🙂

Conclusão: o resumo do mecanismo (e o próximo passo)

A cadeia inteira, do começo ao fim:

• skill é uma pasta com um SKILL.md dentro, frontmatter YAML no topo e Markdown abaixo
• no startup, só name e description entram no system prompt
• a description é o gatilho: é com ela que o modelo decide se aquela skill serve
• decidiu que serve, aí o SKILL.md completo é lido do disco e vai pro contexto
• arquivos extras da pasta só entram quando forem realmente necessários

Sabendo disso, a ordem de prioridade quando você escreve uma skill se inverte em relação ao instinto: a description vem primeiro, não por último

O próximo passo concreto é pequeno

Cria uma pasta em ~/.claude/skills com um SKILL.md, --- na primeira linha, name no padrão minúsculo com hífen e uma description que diga o que a skill faz E quando usar

Depois chama com /<name> pra confirmar que o conteúdo funciona, antes de ficar esperando a ativação automática acontecer

Separar as duas coisas é o que transforma "não funciona" em "achei o problema"

Bora escrever a sua primeira? até o próximo post!