Umas semanas depois de começar a usar o Claude Code a sério, percebi que estava digitando o mesmo parágrafo no começo de toda sessão de plugin WordPress. "Apply WordPress Coding Standards. Use the existing autoloader. Don't modify files outside the directory I specify. Run phpcs after every change." Toda vez. Às vezes eu esquecia uma linha e só lembrava três mensagens depois, quando entendia por que o modelo continuava gerando código que não passava na revisão do plugin.
A solução tem nome: Skill. Ela pega esse parágrafo, guarda sob um comando de barra e deixa você chamar pelo nome. /wp-context em vez de seis linhas. O Claude Code lê o arquivo da skill, aplica as instruções, e o resto do seu prompt fica livre pro trabalho de verdade.
A maioria dos textos sobre Skills fala de como construir uma. A mecânica não é complicada, e a documentação oficial cobre bem. A pergunta mais difícil é quais prompts merecem virar Skill. É disso que este post trata.
O que é uma Skill do Claude Code
Um pouco de base técnica, pra o resto fazer sentido.
Uma Skill é um arquivo markdown com frontmatter YAML que fica em .claude/skills/ (no projeto, compartilhado com o time pelo git) ou em ~/.claude/skills/ (pessoal, disponível em qualquer lugar). O nome da pasta vira o comando de barra. Então ~/.claude/skills/wp-context/SKILL.md te dá o /wp-context.
Um SKILL.md mínimo é assim:
---
name: wp-context
description: Apply WordPress Coding Standards and project conventions for plugin development.
---
When working in this codebase:
- Apply WordPress Coding Standards strictly
- Use the existing PSR-4 autoloader, do not introduce a new one
- Run phpcs after every code change
- Stop after each change and wait for review before continuing
Digite /wp-context no começo da sessão e o Claude Code carrega essas instruções. O mecanismo é só isso. A complexidade vem do allowed-tools, do disable-model-invocation, do disparo automático pelo campo description e de mais alguns controles. Vale ler a documentação uma vez. A parte interessante é o que vai dentro.
A primeira pergunta: isso se repete mesmo?
Quando você começa a aprender sobre Skills, a primeira tentação é transformar todo prompt em Skill. Resista, como você resistiria ao Lado Sombrio.
Uma Skill é um investimento de longo prazo. Você escreve, testa, atualiza quando o código muda, depura quando para de funcionar. Como qualquer abstração, ela só se paga quando o custo de escrever e manter é menor que o custo de digitar o prompt toda vez.
Se eu digito um conjunto de prompts três vezes numa semana, provavelmente vale uma Skill. Duas vezes num mês, não vale. Você precisa pesar o esforço e o ganho antes de criar uma.
A maioria das minhas Skills nasceu de um momento específico: eu me peguei copiando um prompt de um chat antigo pra um chat novo pela terceira ou quarta vez. Esse é o sinal. Não é "este prompt é impressionante". Não é "este prompt seria útil em teoria". É só: estou colando isso de novo.
O que acabou virando Skill na minha configuração: o parágrafo de contexto de WordPress. Um checklist de auditoria de segurança de plugin, que descrevi no meu post sobre fluxos com Claude Code. Um gerador de script WP-CLI com as minhas flags padrão (--dry-run, --verbose, lotes de 200, log em CSV). Um formatador de mensagem de commit que segue conventional commits e as convenções de escopo do time.
O que eu deixei de fora de propósito: qualquer coisa que faço uma vez por trimestre, qualquer coisa específica de um cliente que não vai servir pro próximo, qualquer coisa que ainda estou ajustando. Skill tem que ser estável. Prompt que ainda está achando o próprio formato não merece virar arquivo.
A segunda pergunta: quem mais precisa disso?
É aqui que as Skills ficam interessantes pra além da produtividade pessoal.
As Skills de projeto moram em .claude/skills/ e vão pro commit junto com o código. Todo desenvolvedor do time ganha os mesmos comandos de barra. A auditoria de segurança do plugin não roda de um jeito na minha máquina e de outro na do dev júnior. Mesmo arquivo, versionado, revisado em PR.
Uma Skill no seu repositório é infraestrutura do time. Ela registra "como a gente faz as coisas aqui" num lugar que a IA consegue ler de verdade. O onboarding deixa de ser uma wiki que ninguém lê. Vira git clone, e o Claude Code do dev novo já conhece as convenções.
No meu trabalho de consultoria, isso pesa ainda mais. Quando entrego um plugin pro time interno de um cliente, deixo as Skills no repositório. Os desenvolvedores do cliente herdam os meus padrões sem precisar ler, perguntar ou discutir sobre eles em revisão de código. A Skill é o padrão.
E tenha em mente: publicar Skills no GitHub é um bom jeito de o seu nome ficar conhecido. Talvez montar um conjunto bom (bom de verdade) de skills e vender até dê dinheiro.
A terceira pergunta: quanto de automação?
As Skills têm um interruptor que a maioria dos tutoriais ignora. Por padrão, uma Skill pode ser chamada na mão (/nome-da-skill) E disparada sozinha pelo Claude Code, se a descrição combinar com o que ele está fazendo.
Em algumas tarefas, isso é ótimo. O modelo disparar sozinho só acelera as coisas.
Em outras, o disparo automático é perigoso, e onde fica essa linha em cada sistema é a primeira pergunta de qualquer revisão de arquitetura de agentes de IA. Qualquer coisa com efeito colateral: deploy, envio de mensagem, publicação de release, alteração de dado em produção. Você não quer, de jeito nenhum, que o Claude Code decida que o código está pronto e dispare /deploy porque a descrição diz "deploy the application to production".
O frontmatter resolve isso com disable-model-invocation: true. Com essa opção, a Skill só pode ser disparada por você, na mão, de propósito. A diretiva allowed-tools é a proteção que vem junto: uma Skill de auditoria de segurança deveria ter allowed-tools: Read, Grep, Glob e fisicamente não conseguir alterar nada, por mais confiante que o modelo esteja.
Tudo o que mexe em produção recebe chamada só manual e uma lista restrita de ferramentas. Sempre.
Não exagere nas Skills
Já vi desenvolvedores (eu mesmo, por um tempinho) tentarem transformar todo fluxo em Skill, ou instalarem um monte de Skills achadas por aí. O resultado é uma pasta de skills com trinta e sete arquivos, metade sem uso há meses, e um menu de comandos de barra que demora mais pra rolar do que digitar o prompt teria demorado.
E tem o custo de contexto. As descrições das Skills entram no contexto do Claude Code pro modelo saber o que está disponível. Com Skills demais, as descrições são cortadas. O modelo perde o gatilho que você escreveu com todo o cuidado. Encher esse orçamento com Skills que quase não servem aperta as que importam.
Uma Skill merece o lugar quando é usada com frequência suficiente pra você perceber se ela quebrar. O resto é bagunça fingindo ser produtividade.
A questão do CLAUDE.md
O CLAUDE.md é contexto sempre ligado: carrega no começo de toda sessão daquele projeto.
As Skills são contexto sob demanda: carregam quando você chama.
A regra: se vale pra toda sessão deste projeto, vai no CLAUDE.md. Se importa às vezes, mas não sempre, vira Skill.
WordPress Coding Standards num repositório de plugin? CLAUDE.md. O padrão vale sempre.
Uma auditoria de segurança antes de entregar pro cliente? Skill. Você roda antes das entregas, não em toda sessão. Carregar isso como contexto sempre ligado desperdiça tokens em toda interação em que não se aplica.
A maioria das pessoas faz ao contrário. Põe instrução específica de um fluxo no CLAUDE.md, onde polui toda sessão, e deixa os padrões gerais como Skills que você precisa lembrar de chamar. O preço aparece como comportamento inconsistente.
O que eu construiria primeiro
Se você está começando do zero, construa uma Skill só. A candidata certa é um prompt que você digitou pelo menos três vezes nesta semana.
Pra maioria dos desenvolvedores WordPress, provavelmente vai ser o padrão de auditoria de segurança do meu post dos quatro fluxos. Pra outros, é um formatador de mensagem de commit, um checklist de revisão de código ou uma checagem antes do deploy. A escolha específica importa menos do que escolher algo chato e frequente.
Use por duas semanas. Se você chama sem nem pensar, construa a segunda. Se você esquece que ela existe, a resposta pra "esse prompt merecia virar Skill?" é não.
Skills multiplicam a produtividade quando registram algo que você faz de verdade. E drenam a produtividade quando registram algo que você gostaria de fazer, mas não faz.
Se o seu time está naquele ponto em que as ferramentas de IA funcionam pra cada pessoa, mas ainda não pro time inteiro, usar Skills como infraestrutura compartilhada é uma das correções mais limpas que eu conheço. Decidir o que um agente pode disparar sozinho é trabalho de arquitetura de IA. Me manda uma mensagem.