O que aprendi criando mais de 30 skills para o Claude Code

O que aprendi criando mais de 30 skills para o Claude Code

Três meses atrás, eu deletei em massa catorze skills da minha configuração do Claude Code. Não arquivei. Deletei. Eram skills nas quais eu havia investido tempo real construindo, testando e iterando. Skills das quais eu tinha orgulho.

Elas estavam piorando meu trabalho.

Não drasticamente — isso teria sido fácil de perceber. Sutilmente. Uma skill de geração de conteúdo que estava sobrepondo as capacidades nativas aprimoradas de escrita do Claude. Uma skill de mensagens de commit que produzia resultados rígidos e formulaicos quando o modelo já havia aprendido a escrevê-los melhor por conta própria. Uma skill de code review tão prescritiva que o Claude estava marcando checkboxes em vez de realmente pensar sobre qualidade de código.

A deleção em massa me ensinou algo que eu não havia lido em nenhuma documentação: construir skills é a parte fácil. Construir skills que continuam úteis, que compõem bem entre si, que realmente melhoram seu fluxo de trabalho seis meses depois — isso é uma disciplina completamente diferente. E é uma disciplina que eu tive que aprender da maneira difícil.

Até agora construí e mantive mais de trinta skills ativas em quatro sites de marcas diferentes, um pipeline de criação de conteúdo, um fluxo de trabalho de auditoria de segurança e meu ambiente de desenvolvimento diário. Algumas dessas skills estão rodando há quase um ano. Outras duraram uma semana antes de eu perceber que estavam resolvendo o problema errado.

O que segue não é um tutorial sobre como criar sua primeira skill. Se você precisa disso, a documentação oficial da Anthropic e o curso Skilljar sobre Agent Skills vão te ajudar a começar. Isto é sobre o que acontece depois das suas primeiras dez skills — os padrões que emergem, os erros que se repetem e as decisões arquiteturais que separam skills que você usará por anos daquelas que deletará em um mês.

Aqui está a pergunta que mudou tudo para mim: que tipo de skill eu estou realmente construindo?

Por que a maioria das skills morre cedo — e uma mudança mental que resolve isso

Eu costumava pensar que uma skill era uma skill era uma skill. Você escreve algumas instruções em markdown, talvez adiciona um script ou dois, coloca em .claude/skills/ e segue em frente. Essa abordagem funcionava bem quando eu tinha três skills. Quando cheguei a quinze, minha configuração era uma bagunça.

Skills estavam conflitando entre si. Algumas carregavam contexto irrelevante 90% do tempo. Outras eram tão genéricas que mal melhoravam a saída do Claude. Uma skill — minha "qualidade de código" original — estava contradizendo minha skill de "práticas de teste" de maneiras que não percebi por semanas.

O ponto de virada veio quando comecei a categorizar minhas skills pelo que elas realmente fazem, não pelo assunto. Depois de catalogar tudo na minha configuração e estudar como as equipes internas da Anthropic organizam suas próprias skills (eles compartilharam parte disso publicamente), percebi que toda skill útil se encaixa claramente em uma de aproximadamente nove categorias. As skills confusas e difíceis de manter? Sempre eram as que tentavam abranger múltiplas categorias ao mesmo tempo.

Aqui está a taxonomia que eu agora uso antes de construir qualquer coisa nova.

Skills de referência de bibliotecas e API explicam como usar corretamente uma ferramenta, SDK ou biblioteca interna específica. Minha skill Aria se encaixa perfeitamente aqui — ela codifica diretrizes de marca, regras de voz, requisitos de SEO e padrões de arquitetura de conteúdo para quatro sites diferentes. Sem ela, o Claude escreve posts competentes que não soam nada como minha marca.

Skills de verificação de produto descrevem como testar ou verificar que a saída está realmente correta. Combinadas com Playwright, tmux ou scripts customizados. Eu investi pouco aqui por meses. Mais sobre isso adiante.

Skills de busca e análise de dados conectam aos seus stacks de dados e monitoramento — UIDs de datasource do Grafana, IDs de dashboard, padrões de query comuns. O Claude para de adivinhar nomes de colunas e começa a escrever queries que realmente funcionam.

Skills de automação de processos de negócio e equipe automatizam fluxos de trabalho repetitivos. Minha skill standup-post agrega atividade do GitHub, atualizações de tickets e mensagens do Slack em uma atualização diária formatada. Instruções simples, valor cumulativo.

Skills de scaffolding e templates de código geram boilerplate para padrões específicos do seu codebase. Uma skill de Laravel para "nova migration" com as convenções e armadilhas da sua equipe economiza trinta minutos toda vez.

Skills de qualidade e revisão de código aplicam padrões. Minha configuração de revisão adversarial gera um sub-agente para criticar código, implementa correções e itera até que os achados degradem para picuinhas.

Skills de CI/CD e deploy ajudam a buscar, enviar e fazer deploy. Minha skill babysit-pr monitora PRs, retenta CI instável, resolve conflitos de merge e habilita auto-merge.

Skills de runbook pegam um sintoma e percorrem uma investigação multi-ferramenta para produzir um relatório estruturado. Minas de ouro para rotações de plantão.

Skills de operações de infraestrutura lidam com manutenção rotineira com guardrails — fluxos de dependências, investigação de custos, limpeza de recursos órfãos com confirmação obrigatória antes de ações destrutivas.

No momento em que comecei a perguntar "a qual categoria isso pertence?" antes de escrever uma única linha de markdown, minhas skills ficaram mais precisas. Se uma skill tenta ser tanto um verificador de qualidade de código QUANTO um template de scaffolding, eu divido em duas. Se não se encaixa claramente em nenhuma categoria, questiono se deveria existir.

Mas categorizar skills é apenas o ponto de partida. A verdadeira arte está em como você as escreve.

A seção de gotchas vale mais que o resto da skill inteira

Vou fazer uma afirmação que pode soar extrema: a parte mais valiosa de qualquer skill é sua seção de gotchas. Não as instruções. Não os exemplos. Não a configuração. Os gotchas.

Eis por quê. O Claude já sabe muito. Ele sabe como escrever Python, como estruturar um componente React, como construir uma REST API. Quando você escreve uma skill que explica o uso básico de algo que o Claude já entende, você está desperdiçando tokens e restringindo a flexibilidade do modelo. Mas quando você documenta os modos de falha específicos — os edge cases que o Claude encontra repetidamente, as suposições que ele faz que estão erradas no seu contexto específico, os bugs sutis que só aparecem em produção — é aí que as skills provam seu valor.

Minha skill de conteúdo Aria tem uma seção de "Frases Banidas" com mais de cinquenta itens. Coisas como "No mundo acelerado de hoje" e "Vamos mergulhar" e "Além disso" — frases que sinalizam instantaneamente conteúdo gerado por IA. Eu não escrevi essa lista de uma vez. Construí ao longo de três meses flagrando o Claude recaindo em linguagem de IA, adicionando cada ofensor à lista de gotchas e observando a qualidade da saída melhorar a cada adição.

Mesmo padrão com minha skill de migrations do Laravel. A sintaxe real de migration? O Claude domina. Mas os gotchas — "nunca use ->change() em uma coluna que tem um índice no MySQL 5.7", "sempre adicione ->after('column_name') para manter a ordem das colunas", "nosso banco de staging usa um collation diferente da produção" — essas entradas previnem bugs que de outra forma levariam horas para debugar.

A conclusão prática: comece cada nova skill com um conjunto mínimo de instruções e uma seção de gotchas vazia. Use a skill por uma semana. Toda vez que o Claude fizer algo errado ou inesperado, adicione aos gotchas. Depois de um mês, sua seção de gotchas será a parte mais refinada e testada em batalha da skill. Também será a parte que economiza mais tempo.

Agora eu reviso minhas seções de gotchas mensalmente. Algumas entradas são promovidas para as instruções principais porque são tão fundamentais. Outras são removidas porque o Claude melhorou e não comete mais esse erro nativamente. Esse ciclo de manutenção é chato, mas é a diferença entre uma skill que se mantém afiada e uma que apodrece lentamente.

Esse hábito de revisão mensal leva diretamente a outra lição que demorei vergonhosamente para aprender.

Skills são pastas, não arquivos — e isso muda tudo

Um equívoco que mantive por tempo demais: uma skill é "apenas um arquivo markdown". Tecnicamente, um arquivo SKILL.md é tudo que você precisa. Mas no momento em que você trata skills como pastas — com scripts, arquivos de referência, templates e dados — seu poder se multiplica.

Esta é a estrutura da minha skill de conteúdo Aria como existe hoje:

aria/
  SKILL.md              # Core instructions, loaded on trigger
  aria-system-prompt.md # Full brand guidelines, loaded on demand
  references/
    banned-phrases.md   # AI detection trigger phrases
    footer-templates.md # Brand-specific CTA footers
    headline-formulas.md # Proven header structures by brand
  assets/
    post-template.md    # Skeleton for new blog posts
  scripts/
    word-count.sh       # Validates 3,000-5,000 word requirement

O arquivo SKILL.md é mantido abaixo de 500 linhas. Ele contém a identidade central, a filosofia de escrita e ponteiros para arquivos de referência. Quando o Claude está gerando um post para mejba.me, ele lê as seções específicas da marca do system prompt. Quando precisa verificar um título contra fórmulas comprovadas, consulta references/headline-formulas.md. A lista de frases banidas vive em seu próprio arquivo porque muda frequentemente e eu não quero que edições nela poluam minhas instruções principais.

Isso é divulgação progressiva em ação. O Claude não carrega tudo de uma vez. O frontmatter YAML — nome e descrição — entra no prompt no início da sessão. São aproximadamente 100 tokens. O corpo do SKILL.md carrega quando o Claude determina que a skill é relevante. Os arquivos de referência carregam apenas quando o SKILL.md explicitamente direciona o Claude a lê-los.

Por que isso importa? Porque o gerenciamento da janela de contexto é uma restrição real. Cada token de instruções de skill é um token que não pode ser usado para a tarefa real. Se eu despejasse todo meu sistema Aria — diretrizes de marca para quatro sites, cinquenta frases banidas, templates de footer, fórmulas de títulos, o blueprint completo de arquitetura de conteúdo — em um único arquivo SKILL.md, seriam milhares de tokens carregados para cada conversa, mesmo aquelas em que eu só peço ao Claude para corrigir um typo.

A estrutura de pastas também facilita dramaticamente a manutenção. Quando preciso atualizar frases banidas, edito um arquivo. Quando adiciono uma nova marca, atualizo o system prompt sem tocar na lógica central da skill. Quando um colega quer entender o que a skill faz, ele lê o SKILL.md. Quando quer entender as diretrizes profundas da marca, lê os arquivos de referência.

Um padrão que comecei a usar recentemente: incluir arquivos de template em assets/ que o Claude copia e preenche em vez de gerar do zero. Meu template de blog post inclui o bloco de metadados, os marcadores de estrutura de fases e o footer obrigatório. O Claude não precisa lembrar o formato exato — ele simplesmente copia o template e preenche os espaços. Menos erros de formato, saída mais consistente.

Se você prefere que alguém construa esse tipo de arquitetura de skills para seus próprios fluxos de trabalho, eu aceito configurações e integrações customizadas do Claude Code. Você pode ver o que eu construí em fiverr.com/s/EgxYmWD.

Há uma sutileza aqui que quase me escapou — e é sobre o que você NÃO coloca na skill.

O que aprendi sobre não engessar o Claude

Minhas skills de primeira geração eram ditadoras. Cada passo prescrito. Cada formato de saída travado. Cada decisão tomada antecipadamente.

Os resultados eram consistentes. Também eram medíocres.

O problema de sobre-especificar uma skill é que você perde a capacidade do Claude de se adaptar. Você está essencialmente convertendo um motor de raciocínio inteligente em um preenchedor de templates. E preenchedores de templates não lidam com edge cases. Não te surpreendem com uma abordagem melhor que a que você planejou. Não detectam erros nas suas próprias instruções.

Aprendi essa lição com minha skill de code review. A versão um era uma checklist de vinte passos: verificar imports não usados, verificar tratamento de erros, confirmar cobertura de testes, validar convenções de nomenclatura... O Claude percorria metodicamente cada item e produzia uma revisão perfeitamente formatada. Mas as revisões deixavam passar o que realmente importava — preocupações arquiteturais, implicações de performance, vulnerabilidades de segurança que não se encaixavam em nenhum item da checklist.

A versão dois reduziu a checklist a cinco princípios e uma seção de gotchas. Em vez de "verificar imports não usados", dizia "priorize achados por impacto real na confiabilidade em produção". Em vez de prescrever o formato de saída, dizia "estruture sua revisão para ajudar o autor a entender o porquê por trás de cada achado".

As revisões melhoraram dramaticamente. O Claude começou a detectar coisas que a checklist nunca cobria — race conditions, violações de contratos de API, bugs sutis de gerenciamento de estado. Ele estava pensando sobre o código em vez de marcar caixas.

O princípio que agora sigo: dê ao Claude a informação que ele precisa e a flexibilidade para se adaptar à situação. Diga o que importa, não exatamente o que fazer. Inclua seus gotchas e restrições, mas deixe espaço para o modelo aplicar seu próprio julgamento.

Há uma maneira concreta de testar se você sobre-especificou: execute a mesma tarefa três vezes com sua skill. Se as saídas são quase idênticas em estrutura e conteúdo, sua skill provavelmente é rígida demais. Se são consistentes em qualidade mas variadas em abordagem, você acertou o ponto ideal.

Esse princípio de flexibilidade se aplica aos gatilhos de skills também — e é aí que o campo de descrição se torna crítico.

O campo de descrição é marketing para o modelo, não para humanos

Quando o Claude Code inicia uma sessão, ele constrói uma listagem de cada skill disponível com sua descrição. Essa listagem é o que o Claude escaneia para decidir "existe uma skill para essa requisição?". O campo de descrição não é um resumo para leitores humanos. É uma especificação de gatilho para o modelo.

Cometi esse erro com meu primeiro lote de skills. Minha skill de mensagens de commit tinha uma descrição como: "Ajuda a escrever melhores mensagens de commit". Vaga. Genérica. O Claude a ativava para tudo remotamente relacionado a git, incluindo momentos em que eu só queria verificar um log ou diff.

A descrição revisada: "Usar quando o usuário pedir para criar um commit, escrever uma mensagem de commit, ou disser /commit. Não ativar para git log, git diff, git status ou outras operações git somente leitura".

Uma diferença abissal. O Claude agora ativa a skill precisamente quando eu preciso e fica fora do caminho quando não preciso.

Alguns padrões que encontrei que funcionam bem para descrições:

Gatilhos positivos — o que deveria ativar a skill: "Usar quando o usuário pedir para criar um blog post, escrever um artigo, gerar conteúdo, ou mencionar qualquer uma dessas marcas: mejba.me, ramlit.com, colorpark.io, xcybersecurity.io".

Gatilhos negativos — o que NÃO deveria ativá-la: "Não ativar para code reviews, correção de bugs ou documentação técnica".

Condições de contexto — quando a skill se aplica: "Só relevante quando trabalhando em repositórios que usam Laravel 11+ com Livewire".

Acertar nisso previne um problema que aflige coleções maiores de skills: conflitos de gatilho. Quando duas skills ambas afirmam lidar com "tarefas de escrita", o Claude precisa adivinhar qual você quer. Descrições específicas e bem delimitadas eliminam a adivinhação.

Isso se torna ainda mais importante quando você começa a compor skills juntas, que é onde o verdadeiro poder aparece.

Composição de skills: onde o efeito multiplicador entra em ação

Skills individuais são úteis. Skills que referenciam e constroem umas sobre as outras são transformadoras.

Meu pipeline de conteúdo funciona assim: a skill Aria lida com geração de conteúdo. Ela referencia uma skill de SEO toolkit para pesquisa e otimização de palavras-chave. A skill de SEO, por sua vez, referencia uma skill de análise de dados que pode puxar dados de tráfego e métricas do Search Console. Quando peço ao Claude para "criar um post para mejba.me sobre networking no Docker", essas três skills se coordenam automaticamente.

A composição não é gerenciada por algum sistema de dependências — o Claude Code ainda não tem gerenciamento nativo de dependências para skills. Em vez disso, eu referencio outras skills por nome nos meus arquivos SKILL.md: "Para análise de SEO, invoque a skill seo-toolkit". O Claude lê essa instrução e invoca a skill referenciada se estiver instalada.

Isso funciona surpreendentemente bem na prática. Mas há uma armadilha: referências circulares. Se a skill A diz "verifique com a skill B" e a skill B diz "confirme com a skill A", o Claude entra em loop. Isso aconteceu comigo uma vez com minhas skills de code review e testes — a skill de revisão dizia "verifique se testes existem" e a skill de testes dizia "verifique os achados da revisão de código". A solução foi tornar a dependência direcional: code review pode invocar práticas de teste, mas não o contrário.

Outro padrão de composição que rendeu frutos: usar uma skill "orquestradora" simples que conhece todas as suas outras skills e roteia tarefas para a correta. Minha skill de fluxo de trabalho de desenvolvimento não faz nenhum trabalho real por si mesma — ela apenas sabe que scaffolding de código vai para a skill de scaffolding, revisões vão para a skill de revisão e deploys vão para a skill de CI/CD. É um dispatcher, e me evita ter que lembrar qual skill lida com o quê.

O padrão de orquestrador também torna trivial a integração de novos membros da equipe. Eles instalam uma skill, e ela automaticamente roteia para tudo mais que precisam. O que nos leva à questão de como compartilhar skills com uma equipe em primeiro lugar.

Como distribuo skills sem criar caos

Compartilhar skills parece simples. Você as commita no seu repositório em .claude/skills/ e todo mundo as obtém. Pronto.

Exceto que não está pronto. Porque cada skill commitada no repositório adiciona ao contexto que o Claude carrega para cada membro da equipe, precisem dela ou não. Uma equipe de cinco com dez skills cada significa cinquenta skills em contexto. Isso é muito ruído.

A abordagem que adotei usa dois níveis.

Nível um: skills no nível do repositório ficam em .claude/skills/ e são commitadas no repositório. Estas são skills que todo contribuidor precisa — aplicação de estilo de código, convenções de teste, procedimentos de deploy. Se você toca nesse codebase, você precisa dessas skills. Ponto final. Mantenho essa lista intencionalmente pequena: três a cinco skills por repositório, máximo.

Nível dois: skills pessoais e específicas de função são distribuídas como plugins através de um diretório compartilhado. Minhas skills de conteúdo, minhas ferramentas de SEO, minhas referências de design system — essas são instaladas por usuário. Desenvolvedores na equipe não precisam da minha skill de conteúdo Aria. Eu não preciso da skill de migration de banco deles. Cada um instala o que é relevante para seu trabalho.

Para equipes maiores que cerca de dez pessoas, eu recomendaria construir um marketplace interno de plugins — um repositório compartilhado no GitHub onde as pessoas podem navegar pelas skills disponíveis, ler descrições e instalar o que precisam. As equipes internas da Anthropic fazem algo similar: skills começam em um diretório sandbox, as pessoas as compartilham pelo Slack, e uma vez que uma skill ganha tração, o dono envia um PR para movê-la para o marketplace oficial.

O passo de curadoria importa mais do que você imagina. Sem controle, coleções de skills incham rápido. As pessoas criam skills para cada incômodo menor, e em poucos meses você tem quarenta skills onde dez bastariam. Antes de adicionar qualquer coisa a um marketplace compartilhado, eu pergunto: "Pelo menos três pessoas nesta equipe usariam esta skill pelo menos uma vez por semana?". Se a resposta é não, ela fica pessoal.

Mais uma lição de distribuição que aprendi da maneira difícil — que também é uma das funcionalidades mais poderosas que a maioria não conhece.

Hooks sob demanda mudaram como eu penso sobre segurança

Skills podem registrar hooks que só se ativam quando a skill é invocada, durando pela sessão inteira. Isso é diferente de hooks globais que rodam o tempo todo. Hooks sob demanda são guardrails contextuais.

Minha skill /careful é o melhor exemplo. Quando estou prestes a trabalhar em infraestrutura de produção, eu a invoco. A skill registra hooks PreToolUse que bloqueiam rm -rf, DROP TABLE, force-push e kubectl delete. Esses hooks interceptam cada comando Bash que o Claude tenta executar e rejeitam qualquer coisa que combine com os padrões perigosos.

Eu não quero esses hooks rodando o tempo todo — seriam enlouquecedores durante o desenvolvimento normal. Mas quando estou tocando bancos de produção ou clusters Kubernetes ao vivo, eles são inegociáveis. A skill me dá um interruptor: segurança máxima quando preciso, zero overhead quando não preciso.

Outro hook sob demanda que uso: /freeze, que bloqueia qualquer operação de Edit ou Write fora de um diretório específico. Quando estou debugando um problema de produção, quero que o Claude leia e analise livremente mas não modifique nada acidentalmente. A skill freeze trava o sistema de arquivos enquanto mantém o acesso de leitura aberto.

O sistema de hooks também permite medição. Eu rodo um hook PreToolUse que registra cada invocação de skill — qual skill, quando ativou, em qual contexto rodou. Depois de um mês de dados, posso ver quais skills são populares, quais estão sub-ativando (significando que suas descrições precisam de trabalho) e quais estão super-ativando (significando que seu escopo é amplo demais).

Esse tipo de instrumentação parece exagero até que você está gerenciando trinta skills e tentando descobrir por que sua sessão do Claude Code está mais lenta do que deveria. Os dados de log te dizem exatamente para onde o orçamento de contexto está indo.

Falando em orçamentos de contexto — há um padrão de memória que eu gostaria de ter começado a usar desde o primeiro dia.

Ensinando suas skills a lembrar

Algumas das minhas skills mais eficazes mantêm estado entre sessões. Não através de nenhum banco de dados sofisticado — através de arquivos de texto puro.

Minha skill standup-post mantém um arquivo standups.log. Toda vez que gera um standup, ela anexa a saída. Na manhã seguinte, o Claude lê sua própria história e sabe exatamente o que mudou desde ontem. Os standups passaram de resumos genéricos para relatórios de delta precisos: "Mergeou o PR de refatoração de auth que estava bloqueando desde terça. Três novos tickets abertos, todos triados para o sprint atual".

Minha skill de pipeline de conteúdo rastreia quais tópicos eu cobri, quais palavras-chave eu targetei e quais links internos eu coloquei. Quando peço um novo post, o Claude verifica o log e evita duplicar ângulos que já publiquei. Ele também pode sugerir links internos para conteúdo existente porque sabe o que já está disponível.

A implementação é extremamente simples. Um arquivo JSON ou um log append-only em um diretório estável. O Claude Code fornece ${CLAUDE_PLUGIN_DATA} como uma pasta estável por plugin especificamente para esse propósito — dados armazenados aqui persistem mesmo quando você atualiza a skill.

// ${CLAUDE_PLUGIN_DATA}/content-history.json
{
  "posts": [
    {
      "date": "2026-03-10",
      "brand": "mejba.me",
      "slug": "opus-4-6-hands-on-review",
      "primary_keyword": "Claude Opus 4.6 review",
      "internal_links": ["claude-sonnet-5-agentic-coding", "claude-agent-teams-guide"]
    }
  ],
  "keywords_used": ["Claude Opus 4.6", "agentic coding", "agent teams"],
  "next_suggested": ["Claude Code skills deep dive", "hook development patterns"]
}

Um aviso: não armazene dados de memória dentro do diretório da skill. Quando você atualiza uma skill, o diretório pode ser sobrescrito. Perdi dois meses de histórico de standups aprendendo essa lição. Sempre use um caminho externo estável.

O padrão de memória também abre algo poderoso — skills que melhoram sozinhas ao longo do tempo. Toda vez que o Claude encontra um novo edge case e eu adiciono à seção de gotchas, isso é melhoria manual. Mas uma skill que registra suas próprias falhas e as apresenta para revisão? Isso está chegando perto de auto-melhoria. Eu ainda não automatizei completamente esse ciclo, mas a infraestrutura de logging torna isso possível.

Certo — isso cobre os princípios. Como isso realmente se parece quando você junta tudo?

Como é meu fluxo de trabalho real em março de 2026

Aqui vai uma segunda-feira de manhã típica. Abro o Claude Code e inicio uma sessão. Três skills no nível do repositório carregam automaticamente de .claude/skills/: aplicação de estilo de código, convenções de teste e nossa checklist de deploy. Meus plugins pessoais também carregam: Aria (conteúdo), SEO toolkit, convenções de commit, code review, fluxo TDD e algumas skills utilitárias.

Overhead total de contexto no início da sessão: aproximadamente 600 tokens para todas as descrições de skills. Os corpos reais das skills ainda não carregaram — estão esperando relevância.

Eu digito: "Crie um post para mejba.me sobre melhores práticas de networking no Docker".

O Claude escaneia as descrições de skills, identifica Aria como relevante, carrega o corpo do SKILL.md. As instruções da Aria dizem ao Claude para verificar o log de histórico de conteúdo, que vive em ${CLAUDE_PLUGIN_DATA}. O Claude lê o histórico, confirma que eu não cobri esse ângulo específico antes e identifica dois posts existentes que deveriam ser linkados internamente.

A skill Aria referencia o SEO toolkit. O Claude carrega essa skill também, roda análise de palavras-chave e determina palavras-chave primárias e secundárias. Ambas as skills estão agora ativas, trabalhando juntas.

O Claude gera o pacote de conteúdo completo — metadados, artigo de 3.500 palavras, footer adequado à marca. O script de contagem de palavras em aria/scripts/ valida o comprimento. Se está abaixo de 3.000 ou acima de 5.000 palavras, o Claude ajusta. O log de histórico de conteúdo é atualizado com os detalhes do novo post.

Tempo total: aproximadamente oito minutos. O mesmo trabalho sem skills — explicar diretrizes de marca, requisitos de SEO, arquitetura de conteúdo, frases banidas, formato de footer, estratégia de links internos — levaria quarenta minutos de engenharia de prompt antes do Claude sequer começar a escrever.

Isso não é um truque de produtividade. É uma mudança fundamental em como eu trabalho com IA.

Os três erros que continuo vendo (e ainda cometo às vezes)

Depois de ajudar uma dúzia de desenvolvedores a configurar seus próprios sistemas de skills, os mesmos três erros aparecem repetidamente.

Erro um: construir skills para coisas que o Claude já faz bem. Se você está escrevendo uma skill que diz ao Claude como escrever um loop for ou estruturar uma resposta JSON, você está desperdiçando esforço. Skills devem codificar conhecimento que o Claude não tem — suas convenções específicas, suas APIs internas, os modos de falha da sua equipe. Teste isso executando a tarefa sem a skill primeiro. Se a saída já é 80% do que você quer, provavelmente não precisa de uma skill. Precisa de uma frase no seu arquivo CLAUDE.md.

Erro dois: nunca atualizar skills depois de criá-las. Skills não são artefatos de escrita única. O Claude melhora a cada atualização do modelo. Seu codebase evolui. As convenções da sua equipe mudam. Uma skill que era perfeita três meses atrás pode ser ativamente prejudicial hoje. Eu agendo uma "auditoria de skills" mensal — trinta minutos onde reviso cada skill, podo gotchas desatualizados e testo se a skill ainda melhora a saída comparado a executar sem ela.

Erro três: fazer skills amplas demais. Uma skill de "assistente de desenvolvimento" que cobre estilo de código, testes, deploy e documentação são quatro skills vestindo um sobretudo fingindo ser uma. Divida. Cada skill deveria ter um propósito único e claro que você pode dizer em uma frase. Se precisa da palavra "e" para descrever o que uma skill faz, provavelmente são duas skills.

Há um quarto erro que é mais sutil e mais difícil de detectar: não investir em skills de verificação. Passei meses construindo skills de geração — skills que ajudam o Claude a criar coisas. Mas mal investi em skills que ajudam o Claude a verificar sua própria saída. Skills de verificação são chatas de construir mas detectam erros antes de chegarem à produção. Um driver de fluxo de cadastro que testa a jornada completa do usuário. Um verificador de checkout que exercita cartões de teste do Stripe. Um smoke test de deploy que confirma que os health checks passam. Essas skills não produzem saídas impressionantes. Elas previnem falhas embaraçosas. Se eu pudesse voltar e redistribuir meu tempo de construção de skills, verificação receberia 40% do orçamento em vez dos 10% que realmente recebeu.

O que vem a seguir para skills (e para onde estou construindo)

O ecossistema de skills em março de 2026 está amadurecendo rapidamente. O marketplace oficial de skills da Anthropic teve crescimento explosivo — só a skill de frontend-design tem mais de 277.000 instalações. Plataformas comunitárias como skills.sh fornecem diretórios pesquisáveis organizados por categoria, autor e número de instalações. O comando npx skills add tornou a instalação trivialmente fácil.

Mas a verdadeira evolução está em como as skills compõem e se comunicam. Agora, a composição de skills é feita através de referências por nome em markdown — "invoque a skill X". Funciona, mas é manual e frágil. Espero gerenciamento nativo de dependências dentro do próximo ano, onde o frontmatter de uma skill pode declarar pré-requisitos que são auto-carregados.

Também estou acompanhando de perto a interseção de skills e hooks. Hooks sob demanda que ativam por skill já são poderosos. O próximo passo são hooks que se coordenam entre skills — uma skill de code review que automaticamente aciona uma skill de testes, que aciona uma verificação de prontidão para deploy, tudo em um pipeline verificado. Agora eu conecto manualmente. Em breve será declarativo.

A fronteira mais interessante são skills que aprendem — não através de treinamento, mas através de logging estruturado e auto-reflexão. Tenho um protótipo rodando com meu pipeline de conteúdo onde o Claude revisa seu log de histórico semanalmente, identifica padrões nas edições que eu fiz e propõe adições à lista de frases banidas. Ainda não estamos em auto-melhoria autônoma. Mas os blocos de construção estão todos lá.

As skills que mais importarão daqui a um ano não são as mais chamativas. São as que silenciosamente melhoram seu trabalho diário e ficam um pouco mais afiadas todo mês porque alguém dedicou trinta minutos para revisar os gotchas.

Comece por aí. Construa uma skill esta semana para a tarefa que você mais repete. Mantenha as instruções mínimas e a seção de gotchas vazia. Use por um mês. Adicione cada falha aos gotchas. No final do mês, você terá algo genuinamente útil. E entenderá, de uma forma que nenhuma documentação pode ensinar, por que skills são o ponto de extensão mais poderoso do Claude Code.

Qual é aquele fluxo de trabalho que você repete todos os dias e que ainda requer prompting manual? Essa é sua primeira skill. Vá construí-la.

Perguntas frequentes

Quantas skills do Claude Code devo ter instaladas ao mesmo tempo?

Mantenha skills no nível do repositório entre três e cinco por repositório e skills pessoais abaixo de quinze no total. Além disso, as descrições de skills consomem contexto significativo e conflitos de gatilho ficam mais difíceis de gerenciar. Qualidade e especificidade vencem quantidade — sempre.

Qual é a diferença entre uma skill do Claude Code e um arquivo CLAUDE.md?

O CLAUDE.md carrega em toda conversa de um projeto e cobre contexto geral do codebase. Skills carregam apenas quando ativadas por requisições relevantes, podem incluir scripts e arquivos de referência, e suportam hooks. Use CLAUDE.md para fatos universais do projeto; use skills para fluxos de trabalho específicos.

Com que frequência devo atualizar minhas skills do Claude Code?

Revisões mensais funcionam bem para a maioria das equipes. Verifique cada skill contra as capacidades nativas atuais do Claude, pode gotchas desatualizados e teste se a skill ainda melhora a saída de forma mensurável comparado a executar sem ela. Atualizações do modelo podem tornar skills de aumento de capacidade obsoletas rapidamente.

Skills do Claude Code podem chamar outras skills?

Sim, através de referências por nome nas instruções do seu SKILL.md. Escreva "invoque a skill [nome-da-skill] para este passo" e o Claude vai ativá-la se estiver instalada. Gerenciamento nativo de dependências ainda não está embutido, então mantenha referências direcionais para evitar loops circulares.

Onde devo armazenar dados que minhas skills geram entre sessões?

Use a variável de ambiente ${CLAUDE_PLUGIN_DATA}, que fornece um diretório estável por plugin que persiste através de atualizações de skills. Nunca armazene dados persistentes dentro da pasta da skill — ela pode ser sobrescrita durante atualizações.

Let's Work Together

Looking to build AI systems, automate workflows, or scale your tech infrastructure? I'd love to help.

• Fiverr (custom builds & integrations): fiverr.com/s/EgxYmWD
• Portfolio: mejba.me
• Ramlit Limited (enterprise solutions): ramlit.com
• ColorPark (design & branding): colorpark.io
• xCyberSecurity (security services): xcybersecurity.io