O que aprendemos ao criar o Claude Code: como usamos Skills

• No Claude Code, Skills são um dos pontos de extensão mais usados, e a Anthropic compartilha know-how prático acumulado ao operar centenas de skills internamente
• Skills não são apenas arquivos Markdown, mas uma estrutura de pastas que inclui scripts, assets, dados etc., em um formato que o agente pode explorar e utilizar
• Elas se dividem em 9 categorias de skills, como referência de bibliotecas, validação de produto, análise de dados, scaffolding de código e CI/CD, e uma boa skill deve se encaixar claramente em uma única categoria
• Ao escrever skills, dicas práticas como seção de Gotchas, uso do sistema de arquivos, divulgação progressiva (Progressive Disclosure) e armazenamento de dados são essenciais
• Ao escalar na organização, recomenda-se uma estrutura para distribuir skills por meio de um marketplace interno de plugins e acompanhar sua eficácia com hooks de medição de uso

---

O que são Skills

• Um equívoco comum sobre Skills é achar que são “apenas arquivos Markdown”, mas na prática elas são uma pasta que inclui scripts, assets, dados etc.
• O agente pode explorar essa pasta, descobrir seu conteúdo e manipulá-lo
• No Claude Code, Skills oferecem várias opções de configuração, e também é possível registrar hooks dinâmicos
• As skills mais interessantes são aquelas que aproveitam criativamente essas opções de configuração e a estrutura de pastas

As 9 categorias de skills

• Ao classificar todas as skills usadas internamente, elas se agruparam em algumas categorias que aparecem repetidamente
• Uma boa skill se encaixa claramente em uma categoria, enquanto skills confusas acabam atravessando várias

• 1. Library & API Reference

  • Skills que explicam como usar corretamente bibliotecas, CLI e SDKs
  • O alvo não são apenas bibliotecas internas, mas também bibliotecas gerais com as quais o Claude Code costuma errar
  • Muitas vezes incluem uma pasta com snippets de código de referência e uma lista de cuidados (gotchas)
  • Exemplos: billing-lib(casos de borda da biblioteca interna de pagamentos), internal-platform-cli(todos os subcomandos e exemplos de uso do wrapper de CLI interno), frontend-design(melhorias na aplicação do design system)

• 2. Product Verification

  • Skills que descrevem como testar e verificar se o código está funcionando corretamente
  • Muitas vezes são usadas em conjunto com ferramentas externas como Playwright e tmux
  • São muito úteis para garantir a precisão da saída do Claude, e vale a pena que um engenheiro invista até uma semana para criar uma ótima skill de validação
  • Recomenda-se usar técnicas como fazer o Claude gravar a saída em vídeo ou impor assertivas programáticas sobre o estado em cada etapa
  • Exemplos: signup-flow-driver(realiza cadastro → verificação de e-mail → onboarding em navegador headless), checkout-verifier(executa a UI de pagamento com cartões de teste da Stripe e depois verifica o estado da fatura), tmux-cli-driver(para testar CLIs interativas que exigem TTY)

• 3. Data Fetching & Analysis

  • Skills que se conectam à stack de dados e monitoramento
  • Incluem bibliotecas de ingestão de dados com credenciais, IDs específicos de dashboards e orientação sobre workflows comuns
  • Exemplos: funnel-query(tabelas com os eventos necessários e canonical user_id para o funil cadastro → ativação → pagamento), cohort-compare(compara retenção/taxa de conversão entre dois cohorts e sinaliza significância estatística), grafana(UIDs de data source, nomes de cluster e tabela de lookup problema → dashboard)

• 4. Business Process & Team Automation

  • Skills que automatizam workflows repetitivos com um único comando
  • As instruções em si podem ser relativamente simples, mas podem ter dependências complexas de outras skills ou MCP
  • Salvar resultados de execuções anteriores em um arquivo de log ajuda o modelo a manter consistência e refletir execuções passadas
  • Exemplos: standup-post(gera um standup formatado com base no rastreador de tickets, atividade no GitHub e Slack), create-ticket(aplica schema obrigatório e workflow pós-criação), weekly-recap(escreve um post resumindo PRs mesclados + tickets fechados + deploys)

• 5. Code Scaffolding & Templates

  • Skills que geram boilerplate de framework para determinados recursos do codebase
  • Podem ser combinadas com scripts componíveis e são especialmente úteis quando há requisitos em linguagem natural que não podem ser totalmente cobertos só com código
  • Exemplos: new-framework-workflow(scaffolding de novo serviço/workflow/handler com anotações), new-migration(template de arquivo de migração e cuidados), create-app(novo app interno com autenticação, logging e configuração de deploy já conectados)

• 6. Code Quality & Review

  • Skills que aplicam qualidade de código dentro da organização e ajudam em code review
  • Para máxima robustez, podem incluir scripts ou ferramentas determinísticas
  • Também podem rodar automaticamente como parte de hooks ou GitHub Actions
  • Exemplos: adversarial-review(um subagente com nova perspectiva critica → corrige → repete até que os apontamentos caiam ao nível de nitpick), code-style(aplica estilos de código que o Claude normalmente não segue bem por padrão), testing-practices(explica como escrever testes e o que deve ser testado)

• 7. CI/CD & Deployment

  • Skills para buscar, enviar e fazer deploy de código dentro do codebase
  • Podem consultar outras skills para coletar dados
  • Exemplos: babysit-pr(monitora PR → tenta novamente CI flaky → resolve conflitos de merge → ativa auto-merge), deploy-service(build → smoke test → rollout gradual de tráfego → comparação da taxa de erro → rollback automático em caso de regressão), cherry-pick-prod(worktree isolada → cherry-pick → resolução de conflitos → criação de PR a partir de template)

• 8. Runbooks

  • Skills que recebem sintomas (thread no Slack, alerta, assinatura de erro etc.), executam uma investigação com múltiplas ferramentas e geram um relatório estruturado
  • Exemplos: service-debugging(mapeamento sintoma → ferramenta → padrão de consulta), oncall-runner(busca alertas → checa causas comuns → formata o resultado), log-correlator(coleta logs de todos os sistemas relacionados por request ID)

• 9. Infrastructure Operations

  • Skills que realizam procedimentos rotineiros de manutenção e operação, incluindo guardrails para ações destrutivas
  • Elas facilitam que engenheiros sigam boas práticas em operações importantes
  • Exemplos: resource-orphans(localiza Pods/volumes órfãos → alerta no Slack → período de espera → confirmação do usuário → limpeza em cascata), dependency-management(workflow de aprovação de dependências da organização), cost-investigation(buckets e padrões de consulta para investigar picos em custos de storage/egress)

Dicas para escrever skills

• Não escreva o óbvio

  • O Claude Code já sabe bastante sobre o codebase e também tem opiniões básicas sobre programação
  • Se você for criar uma skill centrada em conhecimento, deve focar em informações que desviem o Claude do seu modo geral de pensar
  • A skill frontend-design é um bom exemplo: foi criada por engenheiros da Anthropic em iteração com clientes para melhorar o senso de design do Claude, evitando padrões típicos como fonte Inter e gradientes roxos

• Construa uma seção de Gotchas

  • Em todas as skills, o conteúdo com maior valor de sinal é a seção de Gotchas
  • Ela deve ser acumulada a partir dos pontos de falha que o Claude encontra com frequência ao usar a skill
  • O ideal é continuar atualizando esses gotchas ao longo do tempo

• Use o sistema de arquivos e a divulgação progressiva

  • Como skills são pastas, você deve usar todo o sistema de arquivos como meio de engenharia de contexto e divulgação progressiva
  • Se você informar ao Claude quais arquivos existem na skill, ele os lerá no momento apropriado
  • A forma mais simples: separar assinaturas detalhadas de funções e exemplos de uso em um Markdown separado, como references/api.md
  • Se a saída final for Markdown, também é possível incluir arquivos de template na pasta assets/
  • Pastas de referência, scripts e exemplos aumentam a eficiência de trabalho do Claude

• Não restrinja demais o Claude

  • O Claude tenta seguir instruções, mas skills têm alta reutilização, então é preciso ter cuidado com instruções excessivamente específicas
  • Dê as informações necessárias, mas deixe espaço para que ele se adapte com flexibilidade à situação

• Projete o processo de setup

  • Algumas skills precisam de uma etapa de configuração para coletar contexto do usuário
  • Ex.: se for uma skill para postar standup no Slack, é preciso perguntar em qual canal publicar
  • Um bom padrão: salvar as informações de setup em um arquivo config.json dentro do diretório da skill; se não estiver configurado, o agente pergunta ao usuário
  • Para apresentar perguntas estruturadas de múltipla escolha, é possível instruir o uso da ferramenta AskUserQuestion

• O campo Description é para o modelo

  • Quando o Claude Code inicia uma sessão, ele constrói uma lista de descriptions de todas as skills disponíveis
  • O Claude examina essa lista para decidir: “existe alguma skill adequada para esta solicitação?”
  • Portanto, o campo description não é um resumo, mas uma explicação de quando essa skill deve ser acionada

• Memória e armazenamento de dados

  • É possível incluir na skill uma memória na forma de armazenamento de dados
  • Isso pode variar de arquivos simples de log em texto ou JSON até um banco de dados SQLite
  • Ex.: se a skill standup-post salvar todo o histórico em standups.log, na próxima execução o Claude poderá ler esse histórico e entender o que mudou desde ontem
  • Como os dados salvos no diretório da skill podem ser apagados em upgrades, eles devem ser armazenados em uma pasta estável chamada ${CLAUDE_PLUGIN_DATA}

• Armazenar scripts e gerar código

  • Uma das ferramentas mais poderosas que você pode dar ao Claude é o próprio código
  • Ao fornecer scripts e bibliotecas, o Claude pode focar em composição em vez de reconstruir boilerplate
  • Ex.: incluir em uma skill de ciência de dados uma biblioteca de funções auxiliares para buscar dados de fontes de eventos
  • O Claude pode combinar essas funções para gerar scripts na hora e usá-los em análises complexas, como “o que aconteceu na terça-feira?”

• On Demand Hooks

  • É possível incluir hooks que só são ativados quando a skill é chamada e persistem apenas durante a sessão
  • Eles são ideais para hooks opinativos fortes que seriam pesados demais para rodar sempre, mas muito úteis em situações específicas
  • Exemplos:
    • /careful — bloqueia rm -rf, DROP TABLE, force-push, kubectl delete com matchers de PreToolUse, ativando apenas em trabalho de produção
    • /freeze — bloqueia todos os Edit/Write fora de um diretório específico, útil para evitar mudanças acidentais durante debugging

Distribuição de skills

• Uma das grandes vantagens das skills é que elas podem ser compartilhadas com toda a equipe
• Existem duas formas de compartilhamento:
  • Fazer check-in da skill no repositório (em ./.claude/skills)
  • Transformá-la em plugin e enviá-la ao marketplace de Claude Code Plugin, para que usuários a instalem

• Gerenciamento do marketplace

  • Quando equipes pequenas trabalham em poucos repositórios, fazer check-in no repo é uma boa opção
  • Como skills versionadas no repositório vão sendo adicionadas pouco a pouco ao contexto do modelo, um marketplace interno de plugins passa a ser mais vantajoso conforme a escala cresce
  • Não existe uma equipe central que decide quais skills entram no marketplace; as skills mais úteis acabam sendo descobertas naturalmente
  • Se houver uma skill que valha testar, faça upload para a pasta sandbox no GitHub e divulgue em canais como Slack
  • Se ela ganhar tração suficiente, o responsável pela skill abre uma PR para movê-la ao marketplace
  • Como é fácil criar skills ruins ou duplicadas, um mecanismo de curadoria antes do release é importante

• Composição de skills

  • Pode haver necessidade de dependências entre skills (ex.: skill de upload de arquivos + skill de gerar e enviar CSV)
  • Embora nem o marketplace nem as skills tenham gerenciamento de dependências nativo, se você referenciar outra skill pelo nome, o modelo a chamará caso ela esteja instalada

• Medição de skills

  • Para entender o desempenho das skills, a Anthropic registra o uso interno com um hook de PreToolUse
  • Isso ajuda a identificar skills populares e também skills que disparam menos do que o esperado

Conclusão

• Skills são ferramentas extremamente poderosas e flexíveis para agentes, mas ainda estão em estágio inicial, e todos ainda estão descobrindo as melhores formas de usá-las
• Este texto não é um guia definitivo, mas uma coletânea de dicas que funcionaram na prática
• A maioria das skills começou com algumas linhas e um único gotcha, e foi sendo aprimorada continuamente à medida que o Claude encontrava novos casos de borda

[xguru]

O que sinto ao observar a Anthropic hoje em dia é que a equipe de desenvolvimento compartilha ao máximo o que aprendeu com a própria experiência e, ao mesmo tempo, incentiva as pessoas a usarem melhor seus produtos.

Parece um exemplo prático de “é assim que se constrói o ecossistema de desenvolvimento na era da IA”.