Claude Code Skills: Quando um Prompt Completo Merece Virar um Único Comando
Algumas semanas depois de começar a usar Claude Code a sério, percebi que estava digitando o mesmo parágrafo no início de cada 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 lembrava três mensagens depois por que o modelo continuava produzindo código que não passava na revisão do plugin.
A solução se chama Skill. Ela pega esse parágrafo, arquiva sob um comando de barra, e deixa você invocá-lo por nome. /wp-context em vez de seis linhas. Claude Code lê o arquivo da skill, aplica as instruções, e você faz o trabalho pesado com o resto do seu prompt.
A maioria dos textos sobre Skills se concentra em 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 Skills. É sobre isso que este post trata.
O que uma Claude Code Skill realmente é
Um pouco de base técnica para que o resto do post faça sentido.
Uma Skill é um arquivo markdown com frontmatter YAML que fica em .claude/skills/ (nível de projeto, compartilhado com seu time via git) ou ~/.claude/skills/ (pessoal, disponível em qualquer lugar). O nome do diretório se torna o comando de barra. Então ~/.claude/skills/wp-context/SKILL.md te dá /wp-context.
Um SKILL.md mínimo se parece com isto:
---
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 início de uma sessão, e Claude Code carrega essas instruções. Esse é todo o mecanismo. A complexidade vem de allowed-tools, disable-model-invocation, gatilho autônomo via o campo description, e alguns outros controles. Vale a pena ler a documentação uma vez. A parte interessante é o que você coloca dentro.
A primeira pergunta: Realmente é repetido?
Quando você começa a aprender sobre Skills, a primeira tentação é transformar cada prompt em uma Skill. Resista a isso como você deveria resistir ao Lado Escuro.
Uma Skill é um investimento no longo prazo. Você a escreve, testa, atualiza quando o codebase muda, depura quando para de funcionar. Como qualquer abstração, se paga apenas quando o custo de escrever e mantê-la é menor do que o custo de digitar o prompt toda vez.
Se digito um conjunto de prompts três vezes em uma semana, provavelmente vale a pena uma Skill. Duas vezes em um mês, não vale. Você precisa medir o esforço e os ganhos ao criar uma Skill.
A maioria das minhas Skills veio de um momento específico: peguei-me copiando um prompt de um chat anterior para um novo chat pela terceira ou quarta vez. Esse é o sinal. Não "este prompt é impressionante". Não "este prompt seria útil em teoria". Só: estou colando essa coisa de novo.
O que acabou sendo promovido, na minha própria configuração: o parágrafo de contexto WordPress. Uma checklist de auditoria de segurança de plugin que escrevi sobre em meu post de workflows com Claude Code. Um gerador de script WP-CLI com meus sinalizadores padrão (--dry-run, --verbose, em lotes de 200, log CSV). Um formatador de mensagem de commit que segue conventional commits e as convenções de escopo específicas do time.
O que deliberadamente não promovi: nada que faço uma vez por trimestre, nada específico de cliente que não se aplicará ao próximo cliente, nada que ainda estou iterando. Skills devem ser estáveis. Prompts ainda encontrando sua forma não pertencem a um arquivo ainda.
A segunda pergunta: Quem mais precisa disso?
É aqui que Skills ficam interessantes além de produtividade pessoal.
Skills no nível de projeto vivem em .claude/skills/ e são commitadas junto com o código. Cada desenvolvedor no time obtém os mesmos comandos de barra. A auditoria de segurança de plugin não está rodando diferente na minha máquina versus na máquina do dev júnior. Mesmo arquivo, versionado, revisado em PRs.
Uma Skill commitada no seu repositório é infraestrutura de time. Ela codifica "como fazemos as coisas aqui" em um lugar que a IA consegue realmente ler. Onboarding deixa de ser um wiki que ninguém lê. Vira git clone e Claude Code do novo dev já sabe as convenções.
Para meu trabalho consultivo, isso importa ainda mais. Quando entrego um plugin para o time interno de um cliente, deixo as Skills no repositório. Os desenvolvedores do cliente herdam meus padrões sem ter que lê-los, perguntar sobre eles, ou argumentar sobre eles em revisão de código. A Skill é o padrão.
E, tenha em mente, oferecer Skills no GitHub é uma boa forma de seu nome ser conhecido. Talvez, empacotando um bom (como, realmente bom) conjunto de skills e vendendo possa ser lucrativo.
A terceira pergunta: Qual nível de automação?
Skills têm um interruptor que a maioria dos tutoriais ignora. Por padrão, uma Skill pode ser invocada manualmente (/skill-name) E acionada autonomamente por Claude Code se a descrição corresponder ao que ela está trabalhando.
Para algumas tarefas, isto é bom. O modelo acionando-as por si só apenas acelera as coisas.
Para outras tarefas, acionamento autônomo é perigoso. Qualquer coisa com efeitos colaterais: deploys, enviando mensagens, publicando releases, e modificando dados de produção. Você absolutamente não quer que Claude Code decida que o código está pronto e acione /deploy porque a descrição diz "deploy the application to production."
O frontmatter lida com isto com disable-model-invocation: true. Quando definido, a Skill pode apenas ser acionada por você, manualmente, propositalmente. A diretiva allowed-tools é o guarda-chuva correspondente: uma Skill de auditoria de segurança deveria ter allowed-tools: Read, Grep, Glob e fisicamente não consegue modificar nada, independentemente de quão confiante o modelo quer.
Qualquer coisa que toca produção recebe invocação somente manual e uma allowlist de ferramentas. Sempre.
Nunca faça over-skilling
Vi desenvolvedores (incluindo eu mesmo, por um breve momento) tentar transformar cada workflow em uma Skill, ou instalar várias Skills disponíveis online. O resultado é um diretório de skills com trinta e sete arquivos, metade intocada em meses, e um menu de comando de barra que demora mais para rolar do que digitar o prompt teria levado.
Há também um custo de contexto. Descrições de Skills carregam no contexto do Claude Code para o modelo saber o que está disponível. Muitas, e descrições ficam truncadas. O modelo perde o gatilho que você cuidadosamente escreveu. Preenchendo o orçamento com Skills marginais aperta os que realmente importam.
Uma Skill ganha seu lugar sendo usada regularmente o suficiente para que você notaria se quebrasse. Qualquer outra coisa é bagunça que finge ser produtividade.
A questão do CLAUDE.md
CLAUDE.md é contexto sempre ativo: carrega no início de cada sessão naquele projeto.
Skills são contexto sob demanda: carregam quando invocadas.
A regra: se se aplica a cada sessão neste projeto, coloque em CLAUDE.md. Se importa às vezes mas não sempre, faça uma Skill.
WordPress Coding Standards para um repositório de plugin? CLAUDE.md. O padrão sempre se aplica.
Uma auditoria de segurança pré-handoff? Skill. Você a executa antes dos handoffs de cliente, não em cada sessão. Carregá-la como contexto sempre ativo desperdiça tokens em cada interação onde não se aplica.
A maioria das pessoas acertam isto ao contrário. Eles colocam instruções específicas de workflow em CLAUDE.md, onde polui cada sessão, e mantêm padrões gerais como Skills que você precisa se lembrar de invocar. O custo aparece como comportamento inconsistente.
O que eu construiria primeiro
Se você está começando do zero, construa uma única Skill. O candidato certo é um prompt que você digitou pelo menos três vezes esta semana.
Para a maioria dos desenvolvedores WordPress, isso provavelmente é o padrão de auditoria de segurança do meu post de quatro workflows. Para outros, é um formatador de mensagem de commit, uma checklist de revisão de código, ou um pré-voo de deployment. A escolha específica importa menos do que escolher algo chato e de alta frequência.
Use por duas semanas. Se você chega por ela sem pensar, construa a segunda. Se você esquece que ela existe, a resposta para "Este prompt vale a pena promover?" é não.
Skills multiplicam produtividade quando codificam algo que você realmente faz. Elas a drenam quando codificam algo que você gostaria de fazer mas realmente não faz.
Se seu time está no estágio onde ferramentas de IA funcionam para indivíduos mas não ainda para o time inteiro, Skills como infraestrutura compartilhada é uma das correções mais limpas que conheço. Esse é exatamente o tipo de trabalho que faço. Mande uma mensagem.