Skills do Claude Code: o que são, como criar e as melhores em português

O que é uma skill do Claude Code?

Uma skill é uma pasta com um arquivo chamado SKILL.md, que abre com um cabeçalho curto dizendo o nome e quando usar, e depois traz as instruções em texto comum. Quando você pede algo que bate com essa descrição, o Claude Code lê o arquivo inteiro e segue o procedimento que está ali, sem você repetir nada. A pasta pode levar arquivos de apoio, tipo modelo de saída, checklist e exemplo, que ele só abre quando precisa. Não tem código de aplicação envolvido, é texto que o agente lê antes de trabalhar.

A ideia resolve um problema que todo mundo que usa agente conhece: explicar a mesma coisa em toda conversa nova. Sem skill, você cola o mesmo bloco de instrução, esquece um detalhe e o resultado muda de uma sessão para outra. Com skill, o procedimento fica escrito uma vez e vale para todos os projetos da máquina, ou só para um repositório, conforme a pasta onde ela mora. O formato segue o padrão aberto Agent Skills, e a documentação oficial de skills do Claude Code explica cada campo.

No meu caso, skill virou o jeito de transformar processo em ferramenta. Tudo que eu faço mais de três vezes do mesmo jeito, revisar segurança antes de subir, montar direção visual de página, escrever contrato, virou skill, e hoje o que muda o resultado entre um projeto e outro é muito mais o acervo de skills do que o modelo. Comecei com duas ou três, escritas na correria para parar de repetir instrução, e fui refinando cada uma toda vez que o agente errava do mesmo jeito.

Skill, CLAUDE.md, subagente, MCP e slash command: qual é a diferença?

As cinco peças personalizam o agente, só que cada uma entra no contexto num momento diferente, e confundir isso é o que faz o CLAUDE.md inchar e a skill não disparar. O CLAUDE.md é memória fixa, carregada em toda sessão. A skill é procedimento sob demanda. O subagente é outro Claude com contexto separado, que faz o trabalho barulhento e devolve só o resumo. O MCP é conexão com sistema de fora, e o slash command é o atalho que você digita, que hoje virou uma forma de chamar skill.

A regra que eu uso para decidir é perguntar o que está faltando. Se o agente não sabe uma convenção do projeto, tipo como rodar o teste, isso vai no CLAUDE.md. Se ele não sabe executar um procedimento do jeito certo, é skill. Se a tarefa suja o contexto com log gigante ou leitura de documentação, é subagente. Se ele não alcança um dado, é MCP. Os posts sobre subagentes no Claude Code e sobre MCP no Claude Code aprofundam as duas peças que aqui só aparecem de passagem.

Sobre slash command vale uma nota, porque muita gente ainda cria arquivo em .claude/commands. Esse formato continua funcionando, e um arquivo lá ou uma pasta de skill criam o mesmo comando /nome. A diferença é que a skill aceita arquivos de apoio, controle de quem pode acionar e carregamento automático pela descrição, então para qualquer coisa nova eu uso skill. Command solto eu só mantenho quando é um prompt curto, sem referência nenhuma, que eu nunca quero que o agente acione sozinho.

Como o Claude Code decide carregar uma skill

O mecanismo tem nome na documentação, divulgação progressiva, e entender ele muda o jeito de escrever skill. No começo da sessão, o Claude Code coloca no contexto só o nome e a descrição de cada skill instalada, não o conteúdo. Quando o seu pedido parece com alguma descrição, o modelo decide abrir aquela skill, e aí o SKILL.md inteiro entra na conversa e fica lá como instrução até o fim da sessão. Os arquivos de apoio só são lidos se o SKILL.md mandar ler.

Isso tem duas consequências práticas. A primeira é que a descrição é o gatilho, então descrição vaga faz a skill nunca disparar ou disparar na hora errada, e o corpo perfeito não salva nada. A segunda é que cada skill instalada custa um pouco de contexto o tempo todo, porque a descrição está sempre lá, e a documentação corta a descrição em 1.536 caracteres na listagem. Com dezenas de skills, descrição comprida em todas vira um peso que você paga em toda sessão, mesmo sem usar nenhuma.

Dá para controlar quem aciona pelo frontmatter. Com disable-model-invocation: true, a skill some do contexto do modelo e só roda quando você digita /nome, o que eu uso em tudo que publica, manda mensagem ou mexe em infraestrutura. Com user-invocable: false acontece o contrário, ela sai do menu de barra e fica só para o agente. Na minha máquina, 25 skills têm o disparo automático desligado, justamente as que falam com gente de verdade ou gastam crédito, e o resto fica livre para o agente decidir.

Como criar a sua primeira skill em cinco passos

O exemplo abaixo é uma skill inventada para esta aula, pequena de propósito: ela escreve a mensagem de commit em português a partir do que está preparado no Git. Escolhi esse caso porque todo mundo que usa agente faz commit várias vezes por dia, o resultado é fácil de julgar e não depende de nenhuma ferramenta além do próprio Git. Se você prefere pedir para o agente escrever a skill por você, o tutorial de criar skill conversando com o Claude Code mostra esse caminho, e os passos abaixo são o que acontece por baixo.

1. Escolhe uma tarefa que você já repetiu três vezes. Se você não consegue descrever o resultado bom em duas frases, ainda não é skill, é tarefa para explorar primeiro.
2. Cria a pasta no lugar certo. Para valer em todos os projetos da máquina, a pasta é ~/.claude/skills/mensagem-de-commit/. Para valer só num repositório e ir junto no Git para o time, é .claude/skills/mensagem-de-commit/ na raiz dele. O nome da pasta vira o comando.
3. Escreve o SKILL.md com frontmatter. Entre as duas linhas de três hífens vão o nome e a descrição, que diz o que a skill faz e quando usar. Depois vêm as instruções numeradas e um exemplo bom e um ruim, como no arquivo logo abaixo.
4. Testa os dois caminhos de disparo. Abre uma sessão nova e pede em linguagem natural, tipo "fecha essa tarefa com commit", para ver se ele aciona sozinho. Depois digita /mensagem-de-commit para conferir o disparo manual.
5. Compara com e sem a skill. No menu /skills dá para desligar a skill por um tempo e rodar o mesmo pedido, e é a diferença entre as duas saídas que prova que ela faz algo. Se não mudou nada, a instrução está genérica demais.

---
name: mensagem-de-commit
description: Escreve a mensagem de commit em português a partir do diff preparado. Use quando eu pedir para commitar, pedir mensagem de commit ou fechar uma tarefa com commit.
---

# Mensagem de commit

1. Leia o diff com git diff --cached. Se estiver vazio, avise e pare.
2. Escreva um título de até 72 caracteres, no imperativo, em português.
3. No corpo, explique o porquê da mudança em até três linhas, sem repetir o diff.
4. Nunca liste arquivo por arquivo nem invente número de tarefa que não existe.

Exemplo bom: "Corrige cálculo de frete para CEP sem número"
Exemplo ruim: "ajustes"

Repara que o frontmatter tem só dois campos. Na documentação do Claude Code todos são opcionais e só a descrição é recomendada, e no Codex nome e descrição são obrigatórios, então escrevendo os dois você fica compatível com as duas ferramentas desde o primeiro arquivo. As instruções são numeradas e curtas, e o exemplo ruim vale tanto quanto o bom, porque mostra para o modelo o que ele costuma fazer quando ninguém fala nada. Essa skill cabe em vinte linhas, e muita skill útil não passa muito disso.

Onde a skill fica e como saber se ela está funcionando?

A pasta pessoal, em ~/.claude/skills, vale para todos os projetos da sua máquina, e é onde ficam as minhas skills de processo, que eu uso em qualquer repositório. A pasta de projeto, em .claude/skills dentro do repositório, vale só ali e vai para o Git, então todo mundo do time recebe a mesma skill no próximo pull. Existe ainda a skill que vem dentro de plugin, com o nome do plugin na frente do comando, e a skill distribuída pela empresa em configuração gerenciada, que são casos de time grande.

Para testar, o sinal mais honesto é a sessão nova. Numa conversa antiga, o contexto já tem tanta instrução acumulada que fica difícil saber se o acerto veio da skill ou do histórico. Eu abro sessão limpa, faço três pedidos diferentes, um caso simples, um com informação faltando e um fora do padrão, e comparo as saídas. Se o comportamento muda muito de um para outro, a instrução ainda tem ambiguidade. Se a skill não dispara no pedido natural, o problema quase sempre está na descrição, não no corpo.

Para quem quer ir além do teste na mão, a Anthropic mantém um plugin chamado skill-creator, que cria casos de teste, roda cada pedido com e sem a skill em subagentes isolados e dá nota para a saída. Ele é bom para skill que vai ser usada por muita gente, porque transforma "parece melhor" em comparação medida. Para a primeira skill eu não começaria por ele, porque o teste na mão ensina a escrever descrição, e é essa habilidade que você vai usar em todas as próximas.

Boas práticas: descrição que dispara certo, tamanho e instrução versus referência

A descrição precisa responder duas perguntas: o que a skill faz e em que situação ela deve entrar. Descrição tipo "ajuda com SEO" quase não dispara, porque o pedido real é "revisa o title dessa página" e o modelo não liga uma coisa à outra. Eu escrevo com os verbos e os termos que eu mesmo digito quando preciso dela, e nas skills que devem entrar sempre que o assunto aparece eu deixo essa ordem explícita. Das skills( )instaladas na minha máquina, 40 têm essa ordem escrita na descrição, e é o que faz o disparo ficar previsível.

A documentação recomenda manter o SKILL.md abaixo de 500 linhas e mover material de consulta para arquivos de apoio. Nas skills instaladas na minha máquina, a mediana é de 128 linhas por SKILL.md e a maior tem 665, que é justamente uma que eu preciso quebrar. Tamanho importa por um motivo que pouca gente sabe: quando a sessão compacta, o Claude Code recoloca as skills em uso limitadas aos primeiros 5.000 tokens de cada uma, então o que está no fim de um arquivo enorme pode sumir no meio do trabalho.

A divisão que funciona para mim é esta. No SKILL.md fica a instrução, a ordem dos passos, as regras que não se negociam e o critério de pronto. Nos arquivos de apoio fica a referência, tabela de valores, exemplo longo e lista de casos, e o SKILL.md diz quando abrir cada um. Assim o agente lê o essencial sempre e só busca o detalhe quando a tarefa pede, a mesma lógica da divulgação progressiva aplicada dentro da própria skill. Script vai em pasta própria, porque script é executado, não lido.

Dá para escrever skill em português?

Dá, e todas as minhas estão em português. O modelo lê a instrução no idioma em que ela foi escrita e responde no idioma do pedido, então uma skill em português funciona igual para quem pede em português, e o disparo pela descrição também. O cuidado é só com o termo técnico: se você pede "revisa o SEO" e a descrição fala só em "otimização para buscadores", a ligação fica mais fraca. Eu coloco na descrição as duas formas, a palavra em inglês que todo mundo usa e a expressão em português.

A vantagem de escrever na sua língua é maior do que parece. A skill é o registro do seu processo, e processo escrito em inglês por quem pensa em português costuma perder nuance, tipo a regra fiscal brasileira, o jeito de falar com cliente daqui ou a convenção do seu time. As skills de contabilidade e de contrato do catálogo só fazem sentido em português, porque o assunto delas é lei brasileira. Nome da pasta e frontmatter eu mantenho sem acento e sem espaço, porque o nome vira comando.

Skills no Codex: o que muda?

Pouca coisa, porque o Codex adotou o mesmo padrão aberto. A skill é a mesma pasta com SKILL.md, e a diferença principal é o endereço: o Codex lê .agents/skills dentro do repositório, ~/.agents/skills na pasta do usuário e /etc/codex/skills na configuração de administrador, além das skills que já vêm com ele. No Codex, nome e descrição são obrigatórios no frontmatter, segundo a documentação de skills da OpenAI, o que é mais um motivo para sempre escrever os dois.

O disparo manual muda de símbolo. No Claude Code você digita /nome, e no Codex você digita $nome ou abre o menu /skills. O disparo automático existe nos dois, pela descrição, e o Codex também usa divulgação progressiva, com a lista inicial limitada a 2% da janela de contexto ou 8.000 caracteres. Só o Codex tem um arquivo opcional, agents/openai.yaml, para nome de exibição, ícone, dependência de ferramenta e para desligar o disparo implícito, que faz o papel do disable-model-invocation do Claude Code.

No meu uso, as skills vivem em duas árvores reais, não em link: ~/.claude/skills é a fonte da verdade e ~/.agents/skills é o espelho que o Codex lê. Hoje são 95 no Claude Code e 82 no Codex, e a diferença é proposital, são as que só fazem sentido no Claude Code ou que eu só uso nele. A regra que eu sigo é editar sempre no Claude primeiro e espelhar logo em seguida, porque skill com contrato diferente em cada lado faz o mesmo processo julgar diferente conforme quem executou, e eu aprendi isso do jeito caro.

Uma diferença que eu senti na prática é que o Codex é mais conservador para acionar skill sozinho. Por isso eu deixei uma regra no AGENTS.md global dele dizendo para ler a skill sempre que a tarefa cair no assunto da descrição, sem esperar eu digitar o nome. Com isso os dois agentes passaram a julgar igual, o que importa muito no meu fluxo, porque um escreve e o outro revisa, como eu mostro em Claude Code e Codex juntos, e a revisão só vale se os dois seguem o mesmo processo.

Como eu organizo as minhas skills no dia a dia

Eu organizo por área, do mesmo jeito que está na loja: pesquisa, design, marketing, software e método. Cada skill cobre um assunto inteiro, não uma tarefa pequena, então em vez de ter uma skill para meta description e outra para title, existe uma de SEO com as referências separadas por tema. Quando duas skills começam a disputar o mesmo pedido, eu fundo as duas, e já juntei três skills de design numa só porque o agente ficava em dúvida sobre qual abrir e às vezes abria as três.

A segunda regra é o gatilho escrito conforme o risco. Skill de processo, tipo checklist de segurança ou direção visual, fica com disparo automático, porque eu quero que ela entre sem eu lembrar. Skill que fala com gente de verdade, publica em rede social, manda WhatsApp ou mexe em servidor, só roda quando eu peço pelo nome, e isso está escrito na descrição e no frontmatter. Quando um agente orquestra outro, eu ainda passo no prompt a lista das skills proibidas naquela tarefa, e a proibição vence a descrição.

A terceira é revisão de tempos em tempos. Skill parada envelhece junto com a ferramenta embaixo dela, e o sintoma é sutil: ela continua disparando, só que manda o agente fazer algo que a versão nova já faz melhor sozinha. Eu passo o acervo inteiro procurando skill que ninguém aciona, descrição duplicada e referência vencida. Tenho até uma skill só para essa auditoria, que aponta o que está mudo, repetido ou gastando contexto demais, e ela vem de bônus no pack.

Quando vale criar a sua skill e quando vale usar uma pronta?

Vale criar quando o processo é seu. Convenção do seu time, formato de relatório do seu cliente, o jeito que a sua empresa responde lead, nada disso existe pronto, e ninguém escreve melhor do que quem executa todo dia. Também vale criar quando a tarefa é pequena e o resultado é fácil de julgar, como a skill de commit do exemplo, porque em meia hora você tem uma versão boa e ainda aprende o formato no caminho, o que vai servir para todas as outras.

Vale usar pronta quando o conhecimento é de especialista e não é seu. Checklist de segurança de SaaS, estrutura de campanha de anúncio, regra de LGPD, contrato de software: escrever uma skill boa sobre isso exige saber o assunto antes, e a skill ruim nesse caso é pior do que nenhuma, porque o agente segue com confiança uma instrução errada. O critério que eu uso é perguntar quanto custa o erro. Se o erro é um commit mal escrito, cria a sua. Se o erro é um vazamento de dado, usa a de quem já apanhou daquilo.

E vale olhar com cuidado qualquer skill de repositório que você não conhece. Skill é instrução que o agente segue com as permissões que você deu a ele, inclusive rodar comando e ler arquivo, então instalar skill de terceiro sem ler é o mesmo que rodar script de terceiro sem ler. Antes de instalar qualquer uma, a minha ou de outra pessoa, lê o SKILL.md inteiro e os scripts que vierem junto. Se não entendeu o que um trecho faz, pede para o próprio agente explicar antes de liberar.

As skills gratuitas que eu abri no GitHub

Cinco skills minhas estão abertas, com licença MIT, e dá para instalar hoje sem pagar nada. Três são de publicação, para LinkedIn, Threads e X pela API oficial de cada rede, uma é de Google Ads e a outra é a copy-thief, de copy para página de vendas. As de publicação servem também como exemplo de skill que integra API com a credencial fora do repositório. A tabela sai do mesmo catálogo que alimenta a loja, com o link direto para cada repositório.

Para instalar, segue o README de cada repositório, que diz a pasta certa: ~/.claude/skills no Claude Code ou ~/.agents/skills no Codex. Outro caminho é mandar o link para o próprio agente e pedir para ele instalar, lendo o que vai ser copiado antes. As de publicação precisam da sua credencial da rede social, e o README explica onde gerar. Como são abertas, elas são o melhor lugar para ver como eu escrevo uma skill por dentro, antes de decidir se vale criar a sua ou comprar pronta.

O catálogo pago por área, com preço

As 25 skills pagas estão divididas em cinco áreas, e cada uma tem página própria na loja, com a dor que resolve, o que precisa instalado e exemplos de pedido. A tabela abaixo é o resumo, com nome, promessa e preço tirados do mesmo arquivo que alimenta a loja. As de R$ 97 são as premium e as outras custam R$ 57, com pagamento único e 12 meses de atualização. Todas rodam no Claude Code e no Codex, e as duas de método pedem os dois instalados, porque a ideia delas é um revisar o outro.

Eu não descrevo aqui como cada skill funciona por dentro, e isso é de propósito. A página de cada uma mostra o problema, o resultado e o que ela exige da sua máquina, que é o que você precisa para decidir. Se a sua dúvida é se uma skill serve para o seu caso, o caminho mais rápido é abrir a página dela e ler os exemplos de pedido, que são as frases que eu digito para acionar cada uma. Se ficar dúvida, a loja de skills tem as perguntas que as pessoas fazem antes de comprar.

O Pack de Skills compensa? A conta com os preços do catálogo

A conta é simples. As 25 skills compradas uma a uma somam R$ 1.665, sendo 19 de R$ 57 e 6 de R$ 97. O Pack de Skills custa R$ 497, cerca de 30% do avulso, e ainda leva 9 bônus que não são vendidos separados, mais as skills novas dos 12 meses seguintes. No pior caso, comprando só skill de R$ 57, o pack se paga na nona. Se a sua lista tem premium, ele se paga antes, a partir da sexta.

Na prática, o pack compensa quando a sua lista passa de 8 skills, porque aí ele sai mais barato mesmo sem contar os bônus, e a economia sobre o avulso chega a R$ 1.168. Se você só precisa de uma coisa, tipo contrato ou transcrição, compra avulsa e pronto. E se comprou avulsa e depois quis tudo, o valor pago é abatido do pack, então começar pequeno não te faz perder dinheiro. Os bônus incluem plano revisado pelo outro modelo, documentação de projeto e a auditoria de acervo que eu citei antes.

Os erros que fazem uma skill não funcionar

O primeiro é descrição genérica, que eu já comentei e repito porque é disparado o mais comum. O segundo é skill grande demais, tentando cobrir três assuntos, que dispara em pedido que não tem nada a ver e enche o contexto com instrução inútil. O terceiro é duplicar no CLAUDE.md o que já está na skill, e aí as duas versões divergem com o tempo e o agente segue a errada. Instrução de procedimento mora num lugar só, e o CLAUDE.md no máximo aponta para a skill, como eu explico no guia completo de Claude Code.

O quarto é escrever regra sem motivo. "Nunca use X" funciona pior do que "não use X porque quebra Y", porque o modelo generaliza a partir do motivo e acerta o caso que você não previu. O quinto é não testar em sessão nova e concluir que a skill funciona porque funcionou na conversa em que ela foi escrita, com todo o contexto da criação ainda ali. E o sexto é esquecer que a skill executa com as suas permissões, então skill que roda comando destrutivo precisa de disparo manual e de confirmação escrita no próprio texto.

Perguntas frequentes sobre skills do Claude Code

Nomes e preços conferidos em 15/09/2026 no catálogo da loja, e o funcionamento das skills na documentação oficial da Anthropic e da OpenAI. Página atualizada em 15/09/2026. Quando eu atualizo, a data muda junto.