Como Eu Testo Claude Skills Antes que Elas Quebrem Meu Fluxo de Trabalho
Eu deletei uma skill na terça-feira passada que vinha funcionando perfeitamente por seis semanas.
Não porque ela parou de funcionar. Porque o Claude ficou mais inteligente. A skill estava ativamente piorando meus resultados — sobrescrevendo comportamentos que o modelo já tinha aprendido a fazer nativamente. Só percebi isso porque finalmente rodei um teste A/B adequado em vez de confiar na minha intuição.
Esse momento mudou como eu penso sobre cada skill personalizada que construo. E se você está criando skills para Claude Code baseado em feeling e palpites — enviando para produção depois de um único teste bem-sucedido — provavelmente está sentado na mesma bomba-relógio que eu estava.
Aqui está o que ninguém te conta sobre Claude Skills: elas têm data de validade. E a Anthropic acabou de lançar uma ferramenta que te ajuda a descobrir exatamente quando essa data chega.
A Skill que Me Enganou por Seis Semanas
Eu tinha construído uma skill de processamento de PDF em janeiro. Nada sofisticado — ela dizia ao Claude como extrair dados estruturados de faturas, lidar com layouts de múltiplas páginas e gerar JSON limpo. Quando testei pela primeira vez, os resultados foram dramaticamente melhores que o Claude sem modificações. Vitória fácil. Manda pra produção.
Seis semanas depois, estou investigando por que meu pipeline de faturas está mais lento do que eu lembrava. O uso de tokens tinha aumentado gradualmente. Os resultados estavam ok, mas algo parecia estranho. Não consegui identificar o problema até fazer algo que deveria ter feito semanas antes.
Rodei os mesmos prompts sem a skill.
Os resultados eram quase idênticos. Em alguns casos, melhores. O Claude tinha aprendido a lidar com PDFs de forma mais eficaz através de atualizações do modelo, e minha skill agora estava adicionando overhead desnecessário — instruções extras que o modelo já estava seguindo, restrições rígidas que impediam o uso de suas capacidades nativas aprimoradas.
Essa é a armadilha. As skills não avisam quando se tornam peso morto. Elas simplesmente ficam lá em silêncio, consumindo tokens e restringindo um modelo que as superou.
Essa descoberta me levou por uma trilha que terminou no Skill Creator da Anthropic — e honestamente, gostaria de ter encontrado isso antes.
Dois Tipos de Skills (e Por Que a Diferença Importa Mais do que Você Pensa)
Antes de te guiar pelo fluxo de trabalho do Skill Creator, existe um modelo mental que reformulou completamente como eu abordo o desenvolvimento de skills. Cada Claude Skill se encaixa em um de dois grupos, e entender em qual grupo a sua está determina tudo sobre como você a constrói, testa e mantém.
Skills de melhoria de capacidades preenchem lacunas onde o modelo atualmente tem dificuldades. Minha skill de PDF era uma dessas. Assim como skills para lidar com geração de PowerPoint, padrões de concorrência em Swift ou formatação complexa de documentos. Essas skills têm uma data natural de aposentadoria — o modelo melhora a cada atualização, e eventualmente sua skill se torna rodinhas de treinamento em uma bicicleta que o ciclista já domina.
Skills de codificação de fluxos de trabalho capturam seus processos específicos, preferências e regras de negócio. Pense em checklists de revisão de NDA, fluxos de code review específicos da sua empresa, templates de relatórios semanais que puxam dados do Jira e PostHog, triagem de sinistros de seguros com regras internas de compliance. Essas skills codificam seu conhecimento, não capacidades gerais. O modelo não vai aprender espontaneamente os requisitos de compliance da sua empresa através de uma atualização de treinamento.
Aqui está o que a maioria das pessoas não percebe: a estratégia de testes é completamente diferente para cada tipo.
Para skills de melhoria de capacidades, a pergunta crítica é "isso ainda melhora os resultados comparado com não usar nenhuma skill?" Você precisa de comparações de referência. Testes A/B. Benchmarks quantitativos. Porque no momento em que a resposta vira "não", a skill precisa ser aposentada.
Para skills de codificação de fluxos de trabalho, a pergunta crítica muda para "isso dispara de forma confiável e executa corretamente?" Você se preocupa menos se ela supera o Claude sem modificações e mais se ela dispara quando deveria, segue seu processo específico e não ativa em prompts não relacionados.
Eu estava tratando todas as minhas skills como o segundo tipo — verificando se funcionavam, nunca verificando se ainda eram necessárias. O Skill Creator corrige esse ponto cego.
Instalando o Skill Creator (Dois Minutos, Zero Drama)
Colocar o Skill Creator para funcionar é simples. Você pode pegá-lo diretamente do repositório de skills da Anthropic e colocá-lo no seu diretório ~/.claude/skills/.
mkdir -p ~/.claude/skills/skill-creator
cd ~/.claude/skills/skill-creator
# Baixar o arquivo principal da skill
gh api repos/anthropics/skills/contents/skills/skill-creator/SKILL.md \
--jq '.content' | base64 -d > SKILL.md
# Pegar os diretórios de suporte (agents, scripts, references, etc.)
# Ou clonar o repositório inteiro e copiar a pasta skill-creator
A skill vem com várias peças de suporte:
- agents/ — Agentes de avaliação, comparação e análise para avaliação automatizada
- scripts/ — Ferramentas Python para benchmarking, geração de relatórios e otimização de descrições
- eval-viewer/ — Interface de revisão baseada em HTML para examinar resultados de testes
- references/ — Documentação de schemas para as estruturas de dados de avaliação
Uma vez instalada, o Claude Code a detecta automaticamente. Você a verá listada quando verificar suas skills disponíveis. Sem configuração, sem dependências para gerenciar — simplesmente funciona.
Mas instalar é a parte fácil. O verdadeiro valor está no fluxo de trabalho que ela possibilita, e é aí que as coisas ficam genuinamente interessantes.
O Fluxo de Trabalho de Testes que Mudou Como Eu Lanço Skills
O ciclo de avaliação do Skill Creator é construído em torno de uma premissa simples: não confie na sua intuição sobre se uma skill funciona. Prove.
Aqui está o processo que agora sigo para cada skill que construo ou mantenho. Leva uns 30 minutos para uma rodada completa, e já me salvou de lançar skills defeituosas mais vezes do que me sinto confortável em admitir.
Passo 1: Escreva prompts de teste realistas.
Não exemplos genéricos de brinquedo. Prompts reais. O tipo de solicitação bagunçada e carregada de contexto que usuários reais enviam. O Skill Creator te empurra naturalmente para isso — ele quer prompts com caminhos de arquivos, contexto pessoal, nomes de empresas, valores específicos de colunas. O tipo de coisa que alguém realmente digita às 14h de uma quarta-feira quando precisa que algo seja feito.
{
"skill_name": "seo-audit",
"evals": [
{
"id": 1,
"prompt": "ok so my boss just sent me this site ramlit.com and wants a full SEO audit before our board meeting Thursday. Focus on technical stuff and whatever Google cares about now with the AI overview changes",
"expected_output": "Comprehensive SEO audit covering technical, content, and GEO factors"
}
]
}
Prompts de teste ruins: "Faça uma auditoria SEO." "Verifique esta URL." "Analise a página."
Bons prompts de teste parecem que alguém interrompeu seu fluxo de trabalho para digitar algo rapidamente. Abreviações, pistas de contexto, sinais de urgência. É isso que sua skill realmente enfrenta em produção.
Passo 2: Execute testes A/B em paralelo.
É aqui que o Skill Creator realmente brilha. Para cada prompt de teste, ele lança duas execuções de subagentes simultaneamente — uma com sua skill carregada, outra sem. Mesmo prompt, mesmas condições, disponibilidade de skill diferente.
A execução com skill recebe seu SKILL.md carregado no contexto. A execução sem skill opera apenas com as capacidades nativas do Claude. Ambas salvam suas saídas em diretórios organizados do workspace.
Passo 3: Avalie os resultados enquanto as execuções estão em progresso.
Aqui está uma boa otimização de fluxo de trabalho — enquanto os testes rodam em segundo plano, você redige seus critérios de avaliação. Que coisas específicas deveriam ser verdadeiras sobre um bom resultado? O Skill Creator as chama de "assertions" (afirmações), e são verificações objetivamente comprováveis.
Para minha skill de auditoria SEO, as assertions poderiam ser: "O resultado inclui análise de Core Web Vitals", "O resultado menciona acessibilidade para crawlers de IA", "O resultado fornece recomendações acionáveis, não apenas observações."
Passo 4: Revise tudo no visualizador de avaliação.
O Skill Creator gera uma interface de revisão em HTML — não uma parede de texto no terminal, mas um visualizador real baseado em navegador com abas para comparação qualitativa de resultados e benchmarks quantitativos. Você vê cada caso de teste lado a lado, com skill versus sem skill, e pode deixar comentários em cada um.
Foi essa parte que detectou o problema da minha skill de PDF. Quando vi os resultados com skill e sem skill lado a lado, a diferença era... nada significativo. A skill adicionava 22% mais tokens para resultados aproximadamente equivalentes.
Passo 5: Itere baseado em evidências, não em sentimentos.
Depois de revisar, você alimenta seus comentários de volta no Skill Creator. Ele lê seus comentários, analisa os dados quantitativos e te ajuda a reescrever a skill para abordar problemas específicos. Então você roda todo o ciclo novamente.
O ciclo continua até que os comentários sejam todos positivos, você não esteja fazendo progresso significativo, ou esteja satisfeito com os resultados. Para a maioria das skills, acho que duas a três iterações é o ponto ideal.
Os Números de Benchmark que Realmente Importam
O Skill Creator gera um relatório de benchmark após cada iteração, e saber em quais números prestar atenção — e quais ignorar — é metade da batalha.
Aqui está um exemplo real do benchmarking de uma das minhas skills:
| Métrica | Com Skill | Sem Skill | Delta |
|---|---|---|---|
| Taxa de Aprovação de Assertions | 87.5% | 74.0% | +13.5% |
| Tempo Médio de Conclusão | 18.2s | 23.4s | -22% mais rápido |
| Uso Médio de Tokens | 12,400 | 10,800 | +14.8% |
A melhoria na taxa de aprovação é o número principal. Se sua skill não está melhorando significativamente as taxas de aprovação nas suas assertions, ela não está justificando sua existência.
Mas olhe esse aumento no uso de tokens. Minha skill usa 14.8% mais tokens. Isso vale uma melhoria de 13.5% na qualidade do resultado? Para uma skill que rodo 50 vezes por semana, provavelmente sim. Para algo que uso uma vez por mês? A matemática muda.
O delta do tempo de conclusão também é interessante. Minha skill na verdade tornou o Claude mais rápido apesar de usar mais tokens. Isso acontece quando uma skill dá ao Claude uma direção mais clara — menos tempo explorando becos sem saída, mais tempo executando a abordagem correta.
O agente analisador vai mais fundo que esses agregados. Ele procura assertions não discriminantes (que passam independentemente da presença da skill — o que significa que estão testando capacidades base, não valor adicionado pela skill), resultados de alta variância (possivelmente testes inconsistentes) e padrões entre casos de teste que as estatísticas resumidas podem esconder.
O Truque de Otimização de Descrição que a Maioria Ignora
Algo que aprendi da pior forma: você pode construir uma skill perfeita que nunca dispara porque sua descrição não combina com como as pessoas realmente pedem ajuda.
O Skill Creator inclui um pipeline de otimização de descrição que funciona como um mini ciclo de treinamento de machine learning. É genuinamente engenhoso.
Você começa criando 20 consultas de avaliação — metade que deveria disparar sua skill, metade que não deveria. O insight crítico: as consultas de "não deveria disparar" precisam ser quase-acertos, não prompts obviamente não relacionados. Um teste negativo de "escreva uma função fibonacci" para uma skill de SEO não testa nada. Um teste negativo de "verifique se meu site carrega rápido no celular" testa se sua skill de SEO corretamente cede para uma ferramenta específica de performance.
O otimizador divide suas consultas em conjuntos de treinamento e teste, avalia a precisão de disparo da descrição atual, então reescreve iterativamente a descrição para melhorar a pontuação. Ele roda cada consulta múltiplas vezes para considerar a variância e seleciona a melhor descrição baseada no desempenho do conjunto de teste retido — não no desempenho de treinamento — para evitar overfitting.
Depois de rodar isso na minha skill de SEO, a confiabilidade de disparo saltou de aproximadamente 72% para 94%. A correção principal? Minha descrição original dizia "usar para análise SEO." A versão otimizada mencionava sintomas específicos: "auditoria de site", "rankings de busca", "Core Web Vitals", "schema markup", "E-E-A-T." Ela fala a linguagem que os usuários realmente usam.
# Antes da otimização
description: Use when performing SEO analysis on websites
# Depois da otimização
description: Use when analyzing website SEO health, checking search rankings,
auditing technical SEO (Core Web Vitals, crawlability, indexability),
reviewing schema markup, assessing E-E-A-T compliance, or optimizing
for AI search visibility. Triggers on site audits, page analysis,
and structured data validation.
Essa diferença — entre como você pensa sobre sua skill e como os usuários pedem por ela — é onde a maioria das falhas de disparo se escondem.
Quando Aposentar uma Skill (A Conversa que Ninguém Quer Ter)
A aposentadoria da minha skill de PDF não foi um caso isolado. Desde então, rodei comparações de referência em todas as minhas skills de melhoria de capacidades, e mais duas estão na lista de eliminação.
Aqui está meu framework de aposentadoria. É simples, e eu o executo após cada atualização importante do modelo:
Rode sua suíte de testes padrão com a skill desativada. Se os resultados sem skill pontuam dentro de 5% dos resultados com skill nas suas assertions, a skill está funcionando por inércia. Ela adiciona complexidade sem adicionar valor.
Verifique seu overhead de tokens. Mesmo uma skill que melhora marginalmente os resultados pode não valer os tokens extras se a melhoria é pequena. Calcule o custo mensal em tokens da skill em todo o seu uso e pergunte-se se você pagaria esse valor pela melhoria que está vendo.
Olhe as transcrições, não apenas os resultados. Às vezes uma skill faz o Claude tomar um caminho mais longo e tortuoso para chegar ao mesmo destino. Se você vê o modelo gastando tempo em passos que sua skill exige mas que não contribuem para a qualidade do resultado, essas instruções são peso morto.
Teste com prompts NOVOS, não seu conjunto de testes original. Seus prompts de teste originais podem estar acidentalmente ajustados às forças da skill. Lance cinco prompts novos e realistas e veja se a vantagem da skill se mantém em casos para os quais ela não foi otimizada.
Eu sei que aposentar uma skill parece admitir que o tempo gasto construindo-a foi desperdiçado. Não foi. A skill cumpriu seu propósito durante uma janela em que o modelo precisava daquela orientação. Mas se apegar a skills que o modelo superou é como manter as rodinhas de treinamento depois que você já aprendeu a andar de bicicleta. Não ajuda, e pode até te deixar mais lento.
Construindo Sua Primeira Skill com o Creator (Um Passo a Passo Real)
Teoria suficiente. Deixe-me te guiar pela construção de uma skill real usando o Skill Creator, do começo ao fim.
Recentemente eu precisava de uma skill para gerar relatórios semanais de engenharia — puxando contexto de múltiplas fontes, formatando consistentemente e atingindo um tom específico que meu time espera. Skill clássica de codificação de fluxo de trabalho.
A fase de entrevista: O Skill Creator começou perguntando o que a skill deveria fazer, quando deveria disparar e qual deveria ser o formato de saída. Descrevi a estrutura do relatório semanal, as fontes de dados (logs do Git, tickets do Jira, registros de deploy) e o tom (conciso, orientado a métricas, sem enrolação).
O rascunho: Baseado nas minhas respostas, ele gerou um SKILL.md com seções claras — template de saída, instruções de coleta de dados, diretrizes de tom e regras de formatação. O primeiro rascunho estava uns 80% correto. Os 20% restantes foram a parte interessante.
Criação de casos de teste: O Skill Creator propôs três prompts de teste:
- "Gere meu relatório semanal de engenharia para o standup do time amanhã"
- "ok preciso escrever o que entregamos essa semana, foca na migração de auth"
- "relatório semanal mas essa semana foi mais correção de bugs e dívida técnica, não tem muito pra mostrar"
Cada um aborda um cenário diferente — solicitação padrão, solicitação focada e a temida semana de "nada impressionante aconteceu". O terceiro é crítico porque testa se a skill consegue fazer uma semana tranquila soar substancial sem fabricar conquistas.
Os resultados A/B: Os resultados com skill acertaram o formato toda vez. Os resultados sem skill eram decentes mas inconsistentes — às vezes incluíam as seções corretas, às vezes omitiam as métricas de deploy, uma vez ignoraram completamente as diretrizes de tom e escreveram algo que parecia um comunicado de imprensa.
A iteração: Baseado no meu feedback de que o caso de teste da "semana tranquila" ainda parecia inflado demais, o Skill Creator ajustou a skill para abordar explicitamente semanas de baixa atividade: "Quando as conquistas da semana são principalmente manutenção, correção de bugs ou dívida técnica, apresente-as com um enquadramento honesto. Redução de dívida técnica é valioso — diga isso diretamente em vez de inflar trabalho rotineiro em narrativas dramáticas."
Duas iterações, uns 25 minutos no total, e eu tinha uma skill que consistentemente produz relatórios que meu time realmente considera úteis.
O que Eu Gostaria de Ter Sabido Seis Meses Atrás
Se eu pudesse voltar no tempo e me dar um conselho sobre Claude Skills, não seria sobre escrever melhores prompts ou otimizar descrições. Seria isso: trate skills como código, não como configuração.
Código é testado. Código é versionado. Código é revisado. Código é aposentado quando algo melhor aparece.
Skills merecem a mesma disciplina. O Skill Creator não apenas facilita a construção de skills — ele torna possível tratar o desenvolvimento de skills com o rigor que merece. Testes A/B automatizados, benchmarks quantitativos, otimização de disparo, ciclos de feedback estruturados. Esses não são luxos opcionais. Para qualquer skill em que você confia regularmente, são a diferença entre uma ferramenta que genuinamente ajuda e uma superstição que você nunca se deu ao trabalho de verificar.
Os engenheiros e times que obtêm os maiores ganhos de produtividade com Claude não são os que têm mais skills. São os que sabem — com evidências — quais skills estão justificando sua existência.
Comece com sua skill mais usada. Rode uma comparação de referência. Você pode se surpreender com o que encontrar. Eu certamente me surpreendi.
E aquela skill de PDF que eu deletei? Reconstruí uma versão mais leve que lida apenas com os casos extremos específicos com os quais o Claude ainda tem dificuldade — layouts de faturas multicoluna com tabelas aninhadas. Tem um terço do tamanho original, dispara apenas quando esses padrões específicos aparecem, e realmente melhora os resultados em 31% no seu foco estreito.
Às vezes a melhor skill não é a mais abrangente. É a que sabe exatamente quando aparecer — e quando ficar de fora.
Vamos Trabalhar Juntos
Quer construir sistemas de IA, automatizar fluxos de trabalho ou escalar sua infraestrutura tecnológica? Adoraria ajudar.
- Fiverr (desenvolvimentos personalizados e integrações): fiverr.com/s/EgxYmWD
- Portfolio: mejba.me
- Ramlit Limited (soluções empresariais): ramlit.com
- ColorPark (design e branding): colorpark.io
- xCyberSecurity (serviços de segurança): xcybersecurity.io
