Como criar skills no Claude Code: o guia completo de Agent Skills

Uma skill não é um prompt melhor. É outra categoria de coisa: um módulo com nome, referências e comportamento próprios, que persiste em todas as sessões sem encostar no seu system prompt.

Uso treze skills no Claude Code. Elas cobrem design de oferta (o método do Alex Hormozi, destilado em 13 referências e uns 80KB de decisões), estratégia de SEO (a do Neil Patel), arquitetura de funil (a do Russell Brunson), clareza de explicação (a do Feynman), revisão de roteiro (a do Arthur Miller), contrarianismo financeiro (o do Michael Burry) e uma suíte lifeos que construí para o meu segundo cérebro: revisões semanais, registro de decisões, planejamento de projetos. Nenhuma delas mora no meu system prompt. Carregam quando precisam e somem quando não.

Este artigo cobre o sistema completo. Os artigos linkados aprofundam cada parte; vou apontar para eles em vez de duplicar o detalhe aqui.

O que são skills do Claude?

Uma skill do Claude é um módulo de comportamento reutilizável que o Claude Code carrega sob demanda. Ela vive no próprio diretório, tem um arquivo roteador SKILL.md e arquivos de referência opcionais, e é ativada pela descrição, não por um system prompt fixo. Skills resolvem a dívida de prompt longo: o acúmulo de instruções que incham o system prompt e deixam toda sessão mais lenta, sejam elas relevantes ou não.

O artigo o que são skills do Claude cobre a base conceitual em detalhe. A versão curta: uma skill é um diretório com um nome, uma descrição e um corpo de instruções que só carrega quando a descrição bate com a tarefa. A documentação oficial está em code.claude.com/docs/en/skills.

A dívida de prompt longo cobra imposto de toda sessão

Antes das skills, comportamento persistente morava no system prompt. Uma instrução para tom. Uma para formato de saída. Uma para convenções de código. Uma para cada persona que você queria. Depois de alguns meses, eram 4.000 tokens de instruções carregando em toda sessão, inclusive nas que nunca usavam metade delas.

A dívida de prompt longo cresce de dois jeitos. Primeiro, cada instrução nova custa tokens para sempre, relevante ou não para a tarefa. Segundo, o modelo presta atenção em tudo ao mesmo tempo, o que significa que presta atenção na coisa errada mais ou menos metade das vezes. Skills quebram esse acoplamento. Um comportamento entra no contexto só quando a tarefa pede e sai limpo quando não pede. Você para de pagar por capacidades que não está usando.

Skills vs prompts, memória, MCP e subagents

Uma skill é um módulo persistente e reutilizável que carrega sob demanda e sobrevive entre sessões. Um prompt é uma instrução de sessão que zera quando a conversa acaba. Memória é contexto armazenado sem estrutura executável por trás. MCP é um provedor de ferramentas do lado do servidor, não um módulo de comportamento. Cada um resolve um problema diferente. Confundir os quatro é pegar a ferramenta errada.

As comparações que mais confundem são skills vs MCP e skills vs memória. As duas têm artigos próprios: Skills do Claude vs MCP e subagents cobre a distinção entre ferramenta e comportamento; Skill vs prompt vs memória tem uma árvore de decisão para o resto. Use esses quando a escolha não for óbvia.

Prompts e memória

1. 01Escopo de sessão: zera quando a conversa acaba
2. 02Só contexto, sem estrutura executável nem diretório
3. 03Carrega tudo em toda sessão, relevante ou não
4. 04Sem roteamento interno para arquivos de referência
5. 05Vira dívida de prompt longo conforme você adiciona instruções

Skills do Claude

1. 01Persistente: mesmo comportamento em toda sessão
2. 02Modular: SKILL.md, references/, scripts/, assets/
3. 03Carrega sob demanda, não por padrão em toda sessão
4. 04O mapa de carregamento leva o modelo à referência certa
5. 05Adiciona capacidades sem mexer no system prompt

MCP está mais perto de uma ferramenta do que de um módulo de comportamento. Ele fornece capacidades do lado do servidor: busca na web, acesso a banco de dados, APIs externas. Uma skill fornece um jeito de pensar e executar que persiste entre sessões. Dá para rodar os dois ao mesmo tempo. Não disputam nada.

Subagents são outra divisão: um orquestrador delega uma subtarefa a um subagent, que roda de forma independente. Uma skill roda dentro de um único agente e não cria uma execução separada. Se o seu caso envolve frentes paralelas e agentes independentes, o padrão é de subagent. Se envolve o mesmo agente rodando um comportamento especializado em tarefas recorrentes, é uma skill.

Anatomia de uma skill: SKILL.md, frontmatter, references/, scripts/, assets/

Um diretório de skill tem quatro camadas. Os metadados (nome e descrição) identificam e disparam a skill. O corpo do SKILL.md guarda o mapa de roteamento e as instruções de comportamento. O subdiretório references/ guarda arquivos de conhecimento destilado que carregam sob demanda. scripts/ guarda ferramentas executáveis. assets/ guarda o que a skill produz. O guia de estrutura e frontmatter do SKILL.md cobre cada campo por completo; esta seção te dá o mapa.

Anatomia do diretório de uma skill

• alex-hormozi/skill de persona
  • SKILL.mdroteador// < 500 linhas, o mapa de carregamento mora aqui
  • references/// carrega sob demanda, não por padrão
    • 00-canon.md// princípios centrais de oferta
    • 01-value-equation.md// preço e valor percebido
    • 02-grand-slam-offer.md// construção da oferta
    • 04-pricing-and-guarantees.md// preço, reversão de risco
    • 08-retention-and-ltv.md// retenção e lifetime value
    • 11-decision-checklist.md// veredito final da oferta
  • scripts/// executáveis: bash, python etc.
    • score-offer.py// pontuação numérica
  • assets/// o que a skill produz
    • offer-analysis.md// saída da última execução

Mantenha o SKILL.md abaixo de 500 linhas. Quando passa disso, o corpo assumiu um trabalho que pertence a references/. Um SKILL.md inchado é dívida de prompt longo numa embalagem mais bonita. Mesmo problema. O excesso vai para um arquivo de referência com um nome que reflita a decisão que ele apoia.

O diretório references/ é onde mora o conhecimento da skill. Esses arquivos não carregam sozinhos. O modelo só os lê quando o SKILL.md manda explicitamente. Essa distinção é o design inteiro.

Progressive disclosure: como uma skill carrega de fato

O Claude Code carrega skills em três níveis. O nível um está sempre no contexto: nome e descrição de toda skill instalada. O nível dois carrega quando a skill dispara: o corpo completo do SKILL.md. O nível três carrega só quando o SKILL.md manda: arquivos individuais de references/. Nada no nível três carrega sozinho. Quem decide é o modelo, a partir das instruções que você escreveu. Erre essas instruções e o modelo pula as referências por completo.

A Anthropic chama essa arquitetura de progressive disclosure. Contexto é caro, e a maior parte dele é irrelevante para qualquer tarefa específica. Você paga o custo do nível um (algumas centenas de caracteres por skill) em toda sessão. Paga o do nível dois só quando a skill dispara. Paga o do nível três só quando uma referência específica é necessária para a tarefa em mãos.

Progressive disclosure: três níveis de carregamento

1. L1

   Sempre no contexto: nome e descrição

   O nome e a descrição de toda skill instalada ficam no contexto em toda sessão. É isso que o Claude varre para decidir se uma skill é relevante. Mantenha as descrições enxutas e assertivas: elas são varridas, não lidas. Nome + descrição + when_to_use somados têm um teto de uns 1.536 caracteres na listagem de skills.

   +
2. L2

   Carrega no disparo: o corpo do SKILL.md

   O corpo completo do SKILL.md carrega quando a descrição bate. Essa camada tem as instruções de comportamento da skill, os modos de saída e (o mais importante) o mapa de carregamento que leva o modelo aos arquivos de referência certos. Abaixo de 500 linhas. Se passar, extraia o excesso.

   ## Loading map
   
   | File                              | When to load                    |
   | --------------------------------- | ------------------------------- |
   | references/01-value-equation.md   | Pricing or perceived value      |
   | references/04-pricing.md          | Price, guarantee, risk reversal |
   | references/11-decision-checklist  | Final verdict on an offer       |

   +
3. L3

   Carrega sob demanda: arquivos de referência

   Arquivos individuais de references/ carregam só quando o SKILL.md manda o modelo lê-los. Nada aqui é automático. O mapa de carregamento garante a escolha certa. Escreva como restrição, não como sugestão.

O problema no nível três é que opcional não é obrigatório. Se o SKILL.md diz “você pode consultar references/pricing.md”, o modelo trata como uma sugestão que pode pular. Se o SKILL.md diz “para qualquer pergunta sobre preço, leia references/04-pricing-and-guarantees.md antes de escrever uma única palavra da resposta”, ele se comporta como restrição. A diferença de redação importa. Escreva instruções de carregamento como requisitos.

A descrição decide tudo

A descrição é o principal mecanismo de disparo de uma skill. Junto com when_to_use, é a única coisa que o Claude lê antes de decidir se ativa a skill. Uma skill com descrição fraca não dispara. Fica instalada na biblioteca, invisível, enquanto o Claude responde pelos pesos em vez das suas referências.

A documentação da Anthropic dá nome a essa falha: undertriggering. Skills ativam menos do que deveriam porque as descrições são passivas demais. “Ajuda com análise de oferta” é passiva. “Use esta skill sempre que avaliar uma oferta, modelo de preço, garantia, value stack, funil de aquisição ou taxa de retenção. Carregue-a antes de escrever qualquer resposta sobre qualquer um desses temas” é assertiva. Descrições devem ser um pouco insistentes. Assertivas sobre quando usar a skill, precisas sobre o que ela faz.

Uma segunda falha é usar a descrição para instruções. Instruções ficam no SKILL.md. O único trabalho da descrição é puxar a skill para o contexto quando a tarefa bate. Depois que ela dispara, o SKILL.md assume. Misturar os dois espreme as duas funções e nenhuma sai bem.

Escreva a descrição como se estivesse dizendo ao Claude exatamente quando usar esta skill. É exatamente isso que você está fazendo. Nomeie os tipos de tarefa, os formatos de entrada e os domínios de decisão que a skill cobre. Se você construiu uma skill de avaliação de oferta, liste as palavras que devem dispará-la: oferta, preço, garantia, value stack, conversão, funil de aquisição, retenção. Não faça o modelo deduzir o escopo.

Escrevendo referências: divida por decisão, não por fonte

Referências são o que separa uma skill de uma fantasia. São o conhecimento destilado que o modelo lê em vez de improvisar pelos pesos. O princípio que rege a estrutura delas: divida por decisão, não por fonte. Um arquivo chamado book-1-chapter-4.md é um arquivo morto. Um arquivo chamado pricing-and-guarantees.md é uma ferramenta de decisão.

A pergunta que o modelo recebe nunca chega etiquetada pela fonte. Chega como um problema: um preço que não converte, uma garantia que soa fraca, uma oferta que o cliente não quer. A referência que deve responder é a organizada em torno dessa decisão, não a organizada em torno de onde a informação veio.

Minha biblioteca de skills em uso

13+

skills instaladaspersonas e ferramentas de sistema

13

referências em uma skillHormozi, um arquivo por domínio de decisão

80KB

conhecimento destiladolivros, palestras e playbooks em uma skill de persona

0

linhas no system promptnenhuma skill mora no system prompt

Na minha skill do Hormozi, os 13 arquivos de referência mapeiam 13 domínios de decisão: princípios canônicos, a Value Equation, a construção da Grand Slam Offer, preço e garantias, geração de leads, fechamento e vendas, retenção e LTV, o modelo de conteúdo para aquisição e um checklist final de decisão. Quando chega uma pergunta de preço, o mapa de carregamento aponta para 04-pricing-and-guarantees.md. Quando chega uma de retenção, aponta para 08-retention-and-ltv.md. O modelo não precisa descobrir qual parte do corpus é relevante. O mapa faz isso. A mesma estrutura vale para toda skill da biblioteca: neil-patel, russell-brunson, gary-vaynerchuk, feynman, arthur-miller, michael-burry e a suíte lifeos.

Destilar não é comprimir. É reconstruir. Jogar três livros num diretório de referências te dá uma fantasia maior, não um método. Destilar significa extrair, com as suas palavras, os princípios que sustentam o peso, os frameworks que se repetem, os critérios de decisão que separam aprovado de reprovado, os exemplos que tornam a orientação abstrata concreta e as frases de calibração que denunciam quando a skill se afastou do método. Você lê muito; guarda só o que decide.

Skills de persona: batizar uma skill com o nome de um especialista

Uma skill de persona leva o nome de um especialista reconhecível e sustenta esse nome com referências destiladas. O nome ativa uma região mais densa do conhecimento do modelo. “Alex Hormozi” aponta para livros, palestras, frameworks e frases nos dados de treino, onde “especialista em marketing” aponta para uma média. Mas o nome sozinho é teatro. Quem carrega o método são as referências.

Zheng et al. (arXiv:2311.10054, Findings of EMNLP 2024) testaram 162 personas em quatro famílias de modelos e concluíram que um rótulo de persona puro no system prompt não melhora a precisão factual. A própria conclusão do paper se inverteu entre versões: de “melhora consistentemente” em novembro de 2023 para “não melhora” em outubro de 2024, depois que os autores ampliaram o teste. Um nome sem método por baixo é ruído. Um nome com 13 referências divididas por decisão e um mapa de carregamento é outra máquina.

O tratamento completo (por que o nome compensa dentro de uma skill quando falha como rótulo isolado, como destilar um corpus, como evitar a falha silenciosa em que a skill roda inteira pelos pesos do modelo em vez das suas referências) está em Skills de persona no Claude Code: por que nomear um especialista vence o role prompting. A versão curta: use uma persona quando existe um corpus público real. Use um nome funcional (security-reviewer, api-contract-auditor, migration-planner) quando a skill é técnica e interna e o trabalho depende dos seus próprios checklists, não do método de uma figura pública.

Exemplos reais: minha biblioteca de skills

Uso um roteador SKILL.md por domínio, cada um um módulo independente com contrato, referências e saída esperada próprios. As personas cobrem design de oferta (Hormozi), arquitetura de funil e value ladder (Brunson), conteúdo orgânico e estratégia de distribuição (Gary Vaynerchuk), SEO e estratégia de palavras-chave (Neil Patel), clareza de explicação e ensino por primeiros princípios (Feynman), estrutura dramática e revisão de roteiro (Arthur Miller) e análise macro contrária (Michael Burry). As skills lifeos cobrem captura de tarefas, revisão semanal, registro de decisões e planejamento de projetos; usam um método destilado meu, não o de uma figura pública.

Nenhuma tenta fazer tudo. Cada uma tem um trabalho de uma frase. Quando o trabalho não cabe numa frase, o escopo é amplo demais para construir uma skill confiável em volta dele. O artigo Exemplos de skills do Claude: implementações reais de uma biblioteca em uso mostra layouts de arquivo concretos, estruturas de referência e trechos reais de SKILL.md, incluindo o formato do mapa de carregamento, as restrições de modo de saída e como o checklist de decisão tira o modelo do “depende” genérico e o força a dar um veredito real.

As skills mais usadas têm descrições assertivas, mapas de carregamento enxutos e referências ancoradas em decisões. As que rendem menos são aquelas em que fui gentil demais com a descrição ou deixei as referências crescerem por fonte em vez de por decisão. Corrigir segue o mesmo padrão toda vez.

Como testar e iterar uma skill

Testar uma skill é verificar que ela carregou as referências e usou, não só que a saída pareceu plausível. A falha na superfície parece ok: voz certa, energia certa, resposta confiante. Mas se o modelo rodou inteiro pelos pesos em vez dos seus arquivos, suas referências não contribuíram com nada. Você destilou 80KB de método que a skill ignorou.

A abordagem sistemática para pegar e diagnosticar essa falha está em Como testar skills do Claude Code: um framework de avaliação. O padrão central é comparação e citação: dê a mesma entrada real antes e depois de instalar a skill, veja se o framework específico das referências apareceu na resposta e confirme que o modelo consegue dizer qual referência mandou ele fazer o quê.

Checagens mínimas de qualidade de uma skill

• ✓Obrigatório:
  Use uma entrada real, não um exemplo de brinquedo.Uma skill que só funciona com prompts artificiais não está pronta para produção.
• ✓Obrigatório:
  Compare a saída antes e depois de instalar a skill.Se a saída é a mesma, a skill não está acrescentando nada.
• ✓Obrigatório:
  Veja se o framework específico de references/ apareceu.Value Equation, RAISE, Grand Slam Offer: o framework é o sinal.
• ✓Obrigatório:
  Rode a mesma entrada duas vezes em sessões diferentes.Saída consistente significa que a skill carregou, não improvisou.
• ✓Obrigatório:
  Teste o mapa de carregamento direto: faça uma pergunta de preço e confirme que ele carregou a referência de preço.O mapa de carregamento é o ponto de falha mais provável.
• ✓Obrigatório:
  Procure o "depende" genérico.Uma skill que carregou as referências não fica em cima do muro como um assistente genérico. Resposta em cima do muro é sinal de que as referências foram puladas.
• •Opcional:
  Peça ao modelo para explicar o raciocínio e citar a fonte.Se ele não consegue nomear a referência, não usou.

Iterar segue o mesmo caminho de diagnóstico. Quando uma skill responde errado, rastreie a falha camada por camada: a descrição disparou? O SKILL.md carregou? O mapa de carregamento apontou para a referência certa? Essa referência tinha o que a tarefa precisava? Cada camada tem um modo de falha distinto, e todos parecem idênticos de fora: uma resposta errada ou genérica. É a estrutura em camadas que te deixa rastrear a causa.

Quando construir uma skill, e quando um prompt basta

Construa uma skill quando o comportamento se repete entre sessões e precisa de saída consistente e ancorada em referências. O sinal mais claro: se você está copiando e colando o mesmo bloco de instruções em várias sessões, esse bloco é uma skill esperando para ser construída. O segundo sinal: se você quer que um conhecimento destilado específico (não só tom, mas frameworks e critérios de decisão de verdade) apareça de forma confiável na saída, esse conhecimento pertence a referências, e referências pertencem a uma skill.

Fique no prompt quando a tarefa é pontual, as instruções mudam a cada execução ou o comportamento não precisa de referências. Só um ajuste temporário de contexto. Prompts são rápidos de escrever e de graça para descartar. Skills pedem investimento: destilação, roteamento, testes. Só construa a skill quando o investimento se paga em muitas sessões.

A decisão mais difícil é entre uma skill e uma ferramenta MCP, ou entre uma skill e memória. Essas têm nuances que não cabem numa regra única. Skill vs prompt vs memória: quando usar cada um tem uma árvore de decisão completa e os casos específicos em que cada um ganha.

O guia prático: parta para uma skill quando se pegar recriando o mesmo comportamento do zero, quando precisar de um comportamento que carregue sozinho sem configuração manual ou quando tiver feito um trabalho de destilação que merece persistir em vez de evaporar no fim da sessão.

FAQ

O que são skills do Claude?+

Skills do Claude são módulos de comportamento reutilizáveis que o Claude Code carrega sob demanda. Cada skill vive no próprio diretório, com um roteador SKILL.md, arquivos de referência opcionais e uma descrição que a dispara. Elas resolvem a dívida de prompt longo mantendo as capacidades fora do system prompt até serem necessárias.

A documentação oficial está em code.claude.com/docs/en/skills.

Como eu crio uma skill no Claude Code?+

Crie um diretório para a skill. Adicione um arquivo SKILL.md com name, description, when_to_use e as instruções de comportamento. Adicione um subdiretório references/ com um arquivo por domínio de decisão. Escreva um mapa de carregamento no SKILL.md que diga ao Claude qual referência ler para cada tipo de pergunta.

A descrição é o gatilho. Escreva de forma assertiva para a skill disparar nas entradas certas, não tímida a ponto de ser pulada.

O que vai no SKILL.md?+

O SKILL.md contém o nome da skill, a descrição, o campo when_to_use, as instruções principais de comportamento, as restrições de modo de saída e o mapa de carregamento que leva o modelo a arquivos de referência específicos. Mantenha abaixo de 500 linhas. O que passar disso vai para um arquivo de referência.

O mapa de carregamento é a parte mais importante. Ele deve nomear arquivos específicos e os tipos de pergunta que exigem cada um. Não sugerir: exigir.

O que é progressive disclosure no contexto das skills do Claude?+

Progressive disclosure é o modelo de carregamento em três níveis que a Anthropic usa para skills. O nível um (nome e descrição) está sempre no contexto. O nível dois (corpo do SKILL.md) carrega quando a descrição bate. O nível três (arquivos de referência individuais) carrega só quando o SKILL.md manda explicitamente o modelo lê-los.

Nada no nível três é automático. O mapa de carregamento é como você faz o modelo buscar o arquivo certo em vez de improvisar pelos pesos.

Por que o campo description importa tanto?+

Porque é a única parte da skill que o Claude lê antes de decidir se a ativa. Uma descrição passiva ou vaga faz a skill disparar menos do que deveria (undertriggering). Ela perde, em silêncio, os casos para os quais foi construída.

Descrições devem nomear de forma assertiva os tipos de tarefa, entradas e domínios de decisão exatos que devem disparar a skill. Escreva como se estivesse dizendo ao Claude exatamente quando usar essa ferramenta, porque é isso que você está fazendo.

Qual a diferença entre uma skill do Claude e uma ferramenta MCP?+

Uma ferramenta MCP fornece capacidades do lado do servidor: acesso à web, bancos de dados, APIs externas. Uma skill do Claude fornece um módulo de comportamento: um jeito de pensar e executar, com referências destiladas, que persiste entre sessões. Dá para usar os dois ao mesmo tempo. Eles não disputam o mesmo espaço.

A comparação detalhada, incluindo onde entram os subagents, está no artigo sobre skills vs MCP e subagents.

Skills de persona funcionam mesmo? Achei que role prompting tinha sido desmentido.+

Role prompting puro não funciona de forma confiável. Zheng et al. (arXiv:2311.10054, Findings of EMNLP 2024) testaram 162 personas em quatro famílias de modelos e não encontraram ganho de precisão factual só com um rótulo de persona. A conclusão do paper se inverteu entre a v1 e a v3 do mesmo estudo.

Uma skill de persona é outra arquitetura. O nome ativa um aglomerado mais denso no conhecimento do modelo, mas quem carrega o método são as referências destiladas. Sem referências, você tem uma fantasia. Com 13 referências divididas por decisão e um mapa de carregamento, você tem uma skill que usa de forma consistente os frameworks reais do especialista em vez de improvisar a voz.

Quantas referências uma skill deve ter?+

Tantas quantas forem as decisões distintas a apoiar, e nenhuma a mais. Minha skill do Hormozi tem 13 porque há 13 domínios de decisão identificáveis em design de oferta. Uma skill mais enxuta pode começar com 3 a 5 arquivos bem destilados.

A regra: um arquivo por decisão, não um arquivo por fonte. Um arquivo chamado 'book-2.md' é um arquivo morto. Um arquivo chamado 'pricing-and-guarantees.md' é uma ferramenta de decisão.

Quando devo usar uma skill em vez de um prompt?+

Use uma skill quando o comportamento se repete entre sessões, você tem conhecimento destilado que pertence a referências e quer saída consistente sem recriar o contexto manualmente toda vez.

Fique no prompt quando a tarefa é pontual, as instruções mudam a cada execução ou o comportamento não precisa de referências. O sinal mais claro para construir uma skill: você está copiando o mesmo bloco de instruções em várias sessões.