Agent Skills no Claude Code: O Guia Avançado Definitivo

Agent Skills no Claude Code: O Guia Avançado Definitivo

A skill quebrou minha sessão principal. Não foi uma falha suave — não foi uma situação de "hmm, isso não ficou certo". Estou falando de uma janela de contexto de 47.000 tokens consumida em oito segundos porque uma skill de pesquisa que eu havia escrito tentou puxar todo o histórico de issues de um repositório do GitHub para a conversa. O Claude parou de responder no meio de uma frase. A sessão foi pro lixo.

Isso foi há três semanas. Eu estava tentando construir uma skill que coletasse inteligência competitiva antes de escrever um artigo técnico. Ideia simples: consultar o GitHub, puxar issues recentes, resumir tendências. A skill funcionava — tecnicamente. Mas funcionava do jeito que uma mangueira de incêndio funciona quando você está tentando encher uma xícara de café. Todos os dados chegaram e destruíram tudo ao redor.

Passei a semana seguinte reconstruindo essa skill usando três funcionalidades que eu vinha ignorando: context forking, injeção dinâmica de contexto e agentes em segundo plano. A mesma skill agora roda em sua própria sessão isolada, pré-processa os dados através de scripts de shell antes que o Claude sequer os veja, e funciona de forma assíncrona enquanto eu continuo programando na minha janela principal. O custo de tokens caiu de 47.000 para cerca de 3.200. Mesma qualidade de resultado. Um universo completamente diferente de eficiência.

Essa experiência me ensinou algo que eu não tinha lido em nenhuma documentação ou tutorial: a arquitetura básica de uma skill — uma pasta com um arquivo SKILL.md — é a linha de partida, não a linha de chegada. As funcionalidades avançadas construídas sobre essa base são o que transformam skills de "atalho de prompt esperto" em "fluxo de trabalho autônomo de verdade". E a maioria dos desenvolvedores construindo skills agora não tocou nelas.

Aqui está tudo o que aprendi sobre o lado avançado das skills do Claude Code — as partes que me levaram de construir brinquedos a construir sistemas.

Onde as Skills Estão Agora (E Por Que o Básico Não É Suficiente)

Se você leu minha análise anterior sobre como agent skills funcionam em nível fundamental, você conhece o conceito central: uma skill é uma pasta contendo um arquivo SKILL.md com frontmatter YAML e instruções em markdown. O Claude carrega os metadados, vê quais skills estão disponíveis e puxa o conteúdo completo apenas quando uma skill é relevante para a tarefa atual. Revelação progressiva. Eficiência de contexto. Expertise modular.

Essa arquitetura é genuinamente boa. Eu ainda uso skills básicas todos os dias — meu formatador de mensagens de commit, minha checklist de revisão de código, meu script de verificação pré-deploy. São simples, funcionam e me economizam de 10 a 15 minutos por uso.

Mas eu continuava batendo em paredes.

O fiasco da skill de pesquisa foi o exemplo dramático, mas as falhas mais silenciosas foram mais instrutivas. Uma skill que precisava do estado atual do projeto — quais arquivos mudaram, em qual branch estou, quais dependências estão instaladas — mas só conseguia acessar instruções estáticas escritas no momento de criação da skill. Uma skill que executava um fluxo de trabalho complexo de múltiplas etapas e poluía minha conversa principal com 30 mensagens de saída intermediária que eu não me importava. Uma skill que funcionava brilhantemente com o Opus 4 mas começava a alucinar etapas depois que eu trocava para o Sonnet 4.6.

Cada uma dessas falhas apontava para a mesma lacuna: skills básicas são estáticas. Elas codificam conhecimento, mas não conseguem se adaptar ao contexto em tempo real, isolar seu trabalho ou provar que ainda estão funcionando corretamente conforme os modelos evoluem.

A Anthropic claramente viu a mesma lacuna. O sistema de skills em março de 2026 inclui funcionalidades que abordam cada um desses problemas. O desafio é que essas funcionalidades estão documentadas em páginas diferentes, explicadas em contextos diferentes e — sendo honesto — nem sempre são óbvias em seu poder até você bater na parede específica que elas resolvem.

Vou percorrer cada uma na ordem em que eu gostaria de tê-las aprendido.

Tipos de Skills: Escolha a Arquitetura Certa Antes de Escrever uma Linha

Antes de construir qualquer skill avançada, você precisa responder uma pergunta: que tipo de problema essa skill resolve? A Anthropic categoriza skills em dois tipos, e escolher errado significa construir algo que é complicado demais ou insuficiente.

Skills de Ampliação de Capacidades

Estas dão ao Claude habilidades que ele não tem de fábrica. Minha skill de automação de navegador com Airtop é uma pura ampliação de capacidades — o Claude não consegue controlar um navegador na nuvem nativamente, mas com a skill instalada, ele pode navegar sites, preencher formulários, extrair dados e lidar com sessões autenticadas. A integração com Airtop compila instruções em linguagem natural em código determinístico que roda contra uma instância real do Chromium na nuvem.

Outros exemplos de ampliação de capacidades que uso diariamente: uma skill que roda auditorias do Lighthouse e alimenta as pontuações de volta na conversa. Uma skill que consulta meu banco de dados de projetos no Airtable. Uma skill que gera e renderiza composições do Remotion.

O padrão é consistente — skills de ampliação de capacidades incluem scripts executáveis (bash, Python, Node) que o Claude invoca como ferramentas. As instruções em markdown dizem ao Claude quando e como usar a ferramenta. O script faz o trabalho real.

Skills de Preferências Codificadas

Estas não adicionam novas capacidades. Elas codificam fluxos de trabalho específicos, convenções e padrões de tomada de decisão. Minha skill de revisão de código não dá ao Claude nenhuma ferramenta nova — o Claude já consegue ler código e sugerir melhorias. A skill codifica os padrões de revisão do meu time: verificar consultas N+1 primeiro, confirmar que todos os métodos públicos têm docblocks, sinalizar qualquer SQL direto que não esteja parametrizado, garantir que respostas de erro sigam nosso contrato de API.

A distinção importa porque determina a complexidade. Skills de ampliação de capacidades precisam de scripts, definições de ferramentas, às vezes configurações de servidor MCP. Skills de preferências codificadas são puro markdown — frequentemente apenas 50-200 linhas de instruções precisas. Se você está construindo uma skill de preferências codificadas e se encontra escrevendo scripts de shell, provavelmente identificou o tipo errado.

Cometi esse erro duas vezes antes de ele grudar. Construí uma skill elaborada com um script Python para "analisar" os padrões de teste da minha base de código, quando tudo que eu realmente precisava era um arquivo markdown dizendo ao Claude "ao escrever testes para este projeto, use Pest em vez de PHPUnit, simule serviços externos com Http::fake(), e sempre teste o caminho triste primeiro". A versão somente markdown foi mais rápida de construir, mais rápida de carregar e produziu resultados melhores porque o Claude não ficava alternando entre seguir instruções e chamar ferramentas.

Dito isso — as skills mais poderosas que construí combinam ambos os tipos. A skill de pesquisa que finalmente corrigi? Ampliação de capacidades para coleta de dados (scripts de shell que consultam a API do GitHub), preferências codificadas para análise (como ponderar diferentes sinais, em que formato gerar a saída). Skills híbridas é onde as coisas ficam interessantes, e onde as funcionalidades avançadas começam a justificar sua complexidade.

Context Forking: Dê às Skills Seu Próprio Espaço para Pensar

Esta é a funcionalidade que salvou minha skill de pesquisa. E é a que eu acho que a maioria dos desenvolvedores deveria aprender primeiro.

Eis o problema que o context forking resolve. Quando uma skill roda na sua sessão principal do Claude, cada token que ela gera — cada etapa intermediária, cada dado que processa, cada cadeia de raciocínio que segue — vive na sua janela de contexto principal. Uma skill que faz 15 etapas de trabalho antes de produzir uma resposta final despejou 15 etapas de contexto que você não pediu na sua conversa. Seu próximo prompt agora precisa competir com todo esse ruído pela atenção do Claude.

Medi isso em um projeto real no mês passado. Minha sessão principal estava com aproximadamente 12.000 tokens quando ativei uma skill que analisava meu package.json, verificava dependências desatualizadas, cruzava referências com vulnerabilidades conhecidas e produzia um plano de atualização priorizado. Quando a skill terminou, minha janela de contexto continha 38.000 tokens. A saída da skill — a parte que eu realmente queria — tinha cerca de 800 tokens. Os outros 25.200 tokens eram memória de trabalho que eu nunca mais olharia. E eles ficariam ali, consumindo capacidade e degradando levemente o foco do Claude, pelo resto da sessão.

O context forking elimina isso por completo. Você adiciona uma linha ao frontmatter YAML da sua skill:

---
name: dependency-audit
description: Analyzes project dependencies for security issues and updates
context: fork
---

Essa diretiva context: fork diz ao Claude Code para criar um subagente dedicado para essa skill. O subagente recebe sua própria janela de contexto, seu próprio histórico de conversa e o conteúdo completo da skill injetado na inicialização. Ele faz todo o trabalho isoladamente e depois retorna apenas o resultado final para sua sessão principal.

Mesma skill de auditoria de dependências, mesmo projeto. Custo na sessão principal: cerca de 1.200 tokens (a solicitação e o resumo retornado). O subagente consumiu seus próprios 26.000 tokens em sua própria janela, que foi limpa depois que a skill terminou.

O modelo mental que me ajudou: pense no context forking como executar uma função em uma thread separada versus inline. A versão inline funciona, mas bloqueia sua thread principal e deixa seus stack frames espalhados. A versão bifurcada roda independentemente e retorna um resultado limpo.

Quando Bifurcar (E Quando Não)

Eu bifurco qualquer coisa que envolva mais de 3-4 etapas de processamento intermediário. Skills curtas — formatar uma mensagem de commit, gerar um arquivo de migração, verificar uma configuração individual — rodam bem no contexto principal. O overhead de criar um subagente não vale a pena para uma skill que gera 500 tokens de memória de trabalho.

Mas qualquer coisa que envolva pesquisa, análise, processamento de múltiplos arquivos ou raciocínio complexo? Bifurque. A economia de contexto se acumula ao longo do dia de trabalho. Eu costumava reiniciar sessões do Claude a cada 2-3 horas porque o contexto ficava poluído demais. Com skills bifurcadas lidando com o trabalho pesado, eu regularmente faço sessões de 8 horas inteiras sem degradação.

Algo que a documentação não enfatiza o suficiente: skills bifurcadas podem especificar qual modelo de agente usar. Eu rodo minha sessão principal no Opus 4.6 pelo seu raciocínio profundo, mas minhas skills bifurcadas mais simples — coleta de dados, formatação, organização de arquivos — rodam no Sonnet 4.6 por uma fração do custo. Você configura isso no frontmatter:

---
name: format-changelog
description: Generates a formatted changelog from git history
context: fork
model: sonnet
---

Uma única skill de pesquisa que costumava me custar $0.40 por execução no Opus agora custa $0.06 porque o fork de coleta de dados roda no Sonnet e apenas a etapa final de análise usa o Opus na minha sessão principal. Ao longo de um mês de uso diário, isso é dinheiro real.

Injeção Dinâmica de Contexto: Skills Que Sabem O Que Está Acontecendo Agora

Instruções estáticas falham no momento em que o estado do seu projeto importa. Aprendi isso construindo uma skill de deploy que precisava saber a branch atual do git, o último hash de commit, quais variáveis de ambiente estavam configuradas e se havia migrações pendentes. Eu poderia codificar instruções sobre como verificar essas coisas, mas a skill gastaria tokens fazendo o Claude rodar comandos e processar saídas que eu poderia ter coletado antecipadamente.

A injeção dinâmica de contexto inverte o modelo. Em vez do Claude descobrir o estado do projeto em tempo de execução, um script de pré-processamento coleta os dados antes da skill carregar e os injeta diretamente no conteúdo da skill. O Claude recebe a skill com dados em tempo real já incorporados. Sem etapa de descoberta. Sem tokens desperdiçados.

A sintaxe usa marcadores !command no seu SKILL.md:

---
name: deploy-preflight
description: Runs deployment readiness checks for current branch
context: fork
---

## Current Project State

- **Branch:** !git rev-parse --abbrev-ref HEAD
- **Last commit:** !git log -1 --oneline
- **Uncommitted changes:** !git status --porcelain | wc -l
- **Pending migrations:** !php artisan migrate:status --pending 2>/dev/null || echo "N/A"
- **Node version:** !node --version
- **Environment:** !echo $APP_ENV

## Deployment Checklist

Based on the current state above, verify the following...

Quando essa skill é ativada, o Claude Code executa cada comando shell !command, captura a saída e substitui o marcador pelo resultado real. O Claude vê:

- **Branch:** feature/payment-gateway
- **Last commit:** a3f2c91 Add Stripe webhook handler
- **Uncommitted changes:** 3
- **Pending migrations:** 2 pending

Não os comandos. Os resultados. O Claude começa a raciocinar sobre a prontidão para deploy a partir do estado real do projeto em vez de gastar tokens descobrindo-o.

A economia de tokens é significativa — minha skill deploy-preflight caiu de cerca de 4.800 tokens (com o Claude rodando comandos de descoberta) para 1.900 tokens (com estado pré-injetado). Mas o ganho maior é a precisão. Quando o Claude descobre o estado por conta própria, ele às vezes interpreta mal a saída de um comando, pula uma verificação se está "confiante o suficiente" ou se distrai com uma resposta inesperada. Com dados pré-injetados, cada informação está garantida de estar presente e corretamente formatada.

Combinando Injeção com Forking

O verdadeiro golpe de mestre é usar ambos juntos. Minha skill de pesquisa competitiva — a que iniciou toda essa jornada — agora fica assim:

---
name: competitive-research
description: Analyzes GitHub activity and trends for a given technology
context: fork
model: sonnet
---

## Research Context

Target technology: {{topic}}
Date range: !date -v-30d +%Y-%m-%d to !date +%Y-%m-%d

## Recent Activity
!gh api search/repositories --jq '.[0:5] | .[] | "\(.full_name) - \(.stargazers_count) stars - \(.description)"' -q "{{topic}} pushed:>$(date -v-30d +%Y-%m-%d)"

## Trending Issues
!gh api search/issues --jq '.[0:10] | .[] | "[\(.repository_url | split("/") | last)] \(.title)"' -q "{{topic}} is:issue created:>$(date -v-7d +%Y-%m-%d)"

Os comandos de shell pré-processam as consultas à API do GitHub. O context: fork roda tudo em um subagente isolado no Sonnet. Minha sessão principal do Opus recebe um resumo limpo. Custo total de tokens na sessão principal: cerca de 900 tokens. Trabalho total realizado: equivalente ao que antes estourava minha janela de contexto de 47.000 tokens.

Isso não é uma melhoria incremental. É uma capacidade fundamentalmente diferente.

Agentes em Segundo Plano: Skills Que Trabalham Enquanto Você Trabalha

Algumas skills levam tempo. Uma auditoria de segurança abrangente de uma base de código. Uma execução completa da suíte de testes com análise. Scraping e resumo de 20 páginas de documentação. Esses fluxos de trabalho podem levar de 3 a 5 minutos — uma eternidade quando você está esperando seu terminal ficar utilizável novamente.

Agentes em segundo plano resolvem isso permitindo que skills rodem de forma assíncrona. Você dispara a skill, ela cria um agente em segundo plano, e sua sessão principal continua responsiva. Quando o agente em segundo plano termina, ele apresenta os resultados.

Uso isso diariamente para minha skill de análise de testes. Depois de fazer push de uma branch de feature, eu disparo a skill:

/skill test-analysis

A skill se bifurca em um agente em segundo plano, roda a suíte completa de testes, captura quaisquer falhas, analisa relatórios de cobertura e redige um resumo. Enquanto isso, eu já estou trabalhando na próxima feature na minha sessão principal. Três minutos depois, o agente em segundo plano retorna com:

Test Analysis Complete:
- 247 tests passed, 2 failed
- Failed: OrderCalculation::test_discount_stacking (assertion mismatch on line 89)
- Failed: PaymentGateway::test_timeout_retry (mock not returning expected response)
- Coverage: 78.3% (down 0.4% from main branch)
- Suggestion: The discount stacking failure looks like a rounding issue...

O fluxo de trabalho é similar a como você usaria Ctrl+B para colocar em segundo plano um subagente em execução — o agente continua trabalhando independentemente mesmo depois que sua tarefa principal prossegue. O comando /tasks te dá um painel de tudo rodando em segundo plano, com IDs que você pode usar para verificar status, ver detalhes ou cancelar.

O que ninguém te conta sobre agentes em segundo plano: o mais valioso não é a economia de tempo, mas o isolamento de contexto. Antes de usar agentes em segundo plano, eu rodava minha suíte de testes na sessão principal do Claude e recebia mais de 200 linhas de saída de testes que eu precisava filtrar mentalmente. O agente em segundo plano processa todo esse ruído em seu próprio contexto e me devolve apenas o sinal.

Se você prefere que alguém construa esse tipo de sistema de skills multi-agente do zero, eu aceito projetos de automação com Claude Code. Você pode ver o que já construí em fiverr.com/s/EgxYmWD.

Instalando Skills: O Ecossistema É Maior Do Que Você Imagina

Preciso voltar um passo e falar sobre como instalar skills no seu sistema, porque a história de instalação evoluiu rapidamente.

O Comando Plugin

O método principal é o sistema de plugins integrado do Claude Code:

/plugin install <skill-name>@<marketplace>

Para o repositório oficial de skills da Anthropic:

/plugin install document-skills@anthropic-agent-skills

Você também pode registrar marketplaces de terceiros:

/plugin marketplace add alirezarezvani/claude-skills

Depois de adicionar um marketplace, cada skill naquele repositório se torna instalável com um único comando.

O Ecossistema skills.sh

O ecossistema do skills.sh explodiu desde que escrevi sobre ele pela primeira vez. Em março de 2026, há mais de 7.000 skills avaliadas em múltiplos marketplaces, compatíveis não apenas com o Claude Code mas também com Codex CLI, Gemini CLI, Cursor e Antigravity IDE. O formato universal SKILL.md significa que uma skill que você constrói para o Claude funciona em todas essas ferramentas.

O melhor método de descoberta que encontrei: navegar pelo SkillHub ou pelo repositório VoltAgent awesome-agent-skills, que curadoria skills de times oficiais de desenvolvimento e da comunidade. Filtre por categoria, confira avaliações e instale com um único comando.

Instalação Manual

Para skills que você mesmo constrói — que é onde está o verdadeiro poder — você tem dois caminhos:

Com escopo de projeto: Coloque a pasta da skill em .claude/skills/ no seu repositório. Cada membro do time que clonar o repo recebe a skill automaticamente. Com controle de versão, compartilhada, consistente.

Pessoal: Coloque em ~/.claude/skills/ para skills que você quer disponíveis em todos os projetos. Minhas skills de formatação, meus padrões gerais de revisão de código, meu guia de estilo de escrita — estes vivem no meu diretório pessoal porque não são específicos de projeto.

A estrutura de pastas é direta:

.claude/skills/
  deploy-preflight/
    SKILL.md          # Frontmatter + instructions
    scripts/
      check-deps.sh   # Optional executable scripts
    templates/
      deploy-log.md   # Optional reference files

O Claude vê o nome e a descrição da skill pelo frontmatter. O conteúdo completo carrega apenas quando ativado. Scripts na pasta se tornam ferramentas que a skill pode invocar.

Construindo Skills Manualmente: Os Padrões Que Realmente Funcionam

Construí cerca de 40 skills nos últimos quatro meses. A maioria das primeiras era medíocre. As que construo agora são dramaticamente melhores, e a diferença se resume a três padrões que tive que aprender através do fracasso.

Padrão 1: Especificidade de Instruções Acima de Volume de Instruções

Minhas primeiras skills tinham mais de 500 linhas de instruções detalhadas. "Se o usuário perguntar sobre X, faça Y. Se ele mencionar Z, certifique-se de verificar W primeiro. Em casos onde..." Exaustivo. E terrível.

O problema: skills longas queimam tokens de contexto mesmo depois do forking, e o Claude piora em seguir instruções conforme o conjunto de instruções cresce. Há um ponto ideal — e nos meus testes, fica entre 80 e 200 linhas de markdown para a seção de instruções.

A solução foi escrever instruções como se eu estivesse orientando um engenheiro sênior, não um júnior. Em vez de detalhar cada passo, descrevo o objetivo, as restrições e o padrão de qualidade. O raciocínio do Claude preenche as lacunas.

Ruim:

1. First, open the file
2. Then find all functions
3. For each function, check if it has a docblock
4. If it doesn't have a docblock, generate one
5. The docblock should include @param tags
6. The @param tags should list the type first, then the name
7. After the @param tags, add a @return tag
...

Bom:

## Task
Add PHPDoc blocks to all public methods missing them.

## Standards
- Follow PSR-5 PHPDoc format
- Infer parameter types from type hints; fall back to mixed
- Include @throws if the method contains throw statements
- Keep descriptions to one sentence — if you need two, the method needs refactoring

A versão boa tem 6 linhas em vez de mais de 30. Produz resultados melhores porque dá ao Claude espaço para raciocinar sobre cada caso específico em vez de seguir mecanicamente uma checklist.

Padrão 2: Condições de Saída, Não Apenas Condições de Entrada

Todo frontmatter de skill tem uma descrição que diz ao Claude quando ativar. A maioria dos criadores de skills para por aí. Mas dizer ao Claude quando a skill está concluída é igualmente importante.

Sem condições de saída explícitas, skills tendem a entregar além do necessário. Minha skill de auditoria SEO costumava continuar encontrando "mais uma coisa para verificar" até ter consumido 15.000 tokens de análise para uma única página. Adicionar condições de saída corrigiu isso:

## Completion Criteria
- All five audit categories scored (Performance, Accessibility, SEO, Best Practices, Content)
- Critical issues listed (severity: high only)
- Three specific, actionable recommendations provided
- Total output: under 500 words

Stop when these criteria are met. Do not continue analyzing.

Padrão 3: Instruções de Recuperação de Erros

Skills que chamam ferramentas externas — APIs, comandos de shell, consultas a bancos de dados — vão encontrar falhas. Se você não disser ao Claude como lidar com falhas, ele para de forma desajeitada ou começa a improvisar, o que geralmente é pior.

Toda skill de ampliação de capacidades que construo agora inclui uma seção de modos de falha:

## When Things Go Wrong

**API returns 401:** The token has expired. Tell the user to run `gh auth refresh` and retry.
**API returns 404:** The repository doesn't exist or is private. Ask the user to verify the repo name.
**Command timeout (>30s):** The network request is hanging. Suggest checking VPN status or retrying with `--timeout 60`.
**Empty results:** This is valid — not every query has results. Report "no data found" rather than guessing.

Never fabricate data if a command fails. Report the failure and suggest a fix.

Esse único padrão eliminou aproximadamente 80% do comportamento imprevisível que eu estava vendo nas minhas skills.

Teste e Avaliação de Skills: A Parte Que Todo Mundo Pula

Vou ser direto sobre isso: se você está construindo skills sem testá-las, está construindo skills que vão quebrar sem aviso.

Pulei os testes nas minhas primeiras 20 skills. Então o Claude teve uma atualização de modelo, e 6 delas começaram a produzir resultados piores. Não quebradas — piores. Degradação sutil. Minha skill de revisão de código parou de detectar consultas N+1. Minha skill de deploy começou a pular a verificação de migrações. Não percebi por uma semana porque as skills ainda rodavam — apenas rodavam mal.

É por isso que a Anthropic construiu o Skill Creator.

O Skill Creator: Uma Skill Que Constrói e Testa Outras Skills

O Skill Creator é uma meta-skill — uma skill que automatiza o desenvolvimento, teste e avaliação de outras skills. Instale-a como plugin e você ganha acesso a dois fluxos de trabalho principais:

Modo eval: Defina prompts de teste, descreva as saídas esperadas, e o Skill Creator roda sua skill contra cada prompt e avalia os resultados. Ele avalia em cinco dimensões: completude do frontmatter, qualidade da descrição, clareza das instruções, profundidade da explicação e taxa de aprovação do eval.

eval: Execute skill on test prompts → Grade outputs → Report scores

Modo improve: Tudo do modo eval, mais comparações A/B cegas, análise automatizada e refinamento iterativo. O Skill Creator roda duas instâncias do Claude — uma com sua skill, uma sem — dá a elas o mesmo prompt e compara as saídas. Se a versão com skill não supera significativamente a versão sem skill, você sabe que a skill não está agregando valor.

improve: Execute → Grade → Blind A/B compare → Analyze → Iterate

Como Eu Testo Minhas Skills Agora

Toda skill que construo passa por esse pipeline antes de eu considerá-la pronta:

Passo 1: Definir 3-5 prompts de teste. Estes devem cobrir o caminho feliz da skill, um caso limite e pelo menos um caso adversário (um prompt que está próximo do domínio da skill mas não deveria ativá-la).

Passo 2: Rodar modo eval. Verificar que todos os prompts de teste produzam as saídas esperadas. Se algum falhar, revisar as instruções da skill.

Passo 3: Rodar o teste A/B. Este é o passo que mudou minha perspectiva sobre construção de skills. Eu tinha uma skill que achava ser brilhante — uma skill de revisão de código com padrões detalhados. O teste A/B mostrou que o Claude sem skill produzia revisões igualmente boas em 3 de 5 casos de teste. Minha skill "brilhante" só agregava valor em casos limite envolvendo consultas a bancos de dados e tratamento de erros de API. Reescrevi para focar exclusivamente nessas áreas, reduzi o tamanho das instruções em 60%, e as pontuações do A/B inverteram para 5 de 5.

Passo 4: Retestar após atualizações do modelo. Mantenho meus prompts de teste em uma subpasta tests/ dentro do diretório de cada skill. Após qualquer atualização do modelo do Claude, re-executo os evals. Isso leva cerca de 10 minutos para toda minha biblioteca de skills e detectou degradação três vezes nos últimos dois meses.

O sistema de avaliação roda cada teste em paralelo, em contextos isolados, para que skills não possam interferir umas com as outras durante os testes. Esse isolamento importa — uma vez tive um teste de skill que passava quando rodado individualmente mas falhava quando rodado junto com outras skills por causa de uma colisão de nomes no frontmatter.

Essa disciplina de testes parece overhead até a primeira vez que te salva. Depois disso, parece a única forma responsável de construir skills.

Integração Real: Automação de Navegador na Nuvem com Airtop

Teoria é útil. Deixe-me mostrar como uma skill totalmente avançada fica em produção.

A skill da qual mais tenho orgulho agora é minha skill de automação de navegador com Airtop. O Airtop fornece um navegador real na nuvem — não um scraper headless, não um DOM simulado, uma instância real do Chromium rodando na nuvem que consegue lidar com sites pesados em JavaScript, sessões autenticadas e conteúdo dinâmico.

Eis por que isso importa: metade das automações que quero que o Claude rode envolvem sites que não têm APIs. Páginas de preços de concorrentes. Portais de fornecedores. Bancos de dados governamentais de conformidade. Sites de vagas. CRMs. Não há API para consultar — a única interface é um navegador.

A skill do Airtop resolve isso combinando todas as funcionalidades avançadas:

---
name: airtop-research
description: Automates web research using a real cloud browser via Airtop
context: fork
model: sonnet
---

Ela se bifurca em seu próprio contexto (porque automação de navegador gera saída intermediária verbosa). Usa injeção dinâmica para carregar minhas credenciais de API do Airtop e as URLs alvo. Roda Sonnet para as etapas de interação com o navegador (custo-efetivo para navegação mecânica) e retorna resultados estruturados para minha sessão principal do Opus para análise.

Um fluxo de trabalho que rodei ontem: monitorar preços de concorrentes em cinco ferramentas SaaS. Descrevi o que precisava em linguagem natural, a skill compilou em código de automação determinístico, lançou sessões de navegador na nuvem contra cada site, extraiu tabelas de preços e retornou uma comparação estruturada. Tempo total: cerca de 90 segundos. Equivalente manual: 20-30 minutos de alternar abas e copiar e colar.

A automação compilada é a parte que mais me surpreendeu. O Airtop não apenas reproduz minhas instruções — ele gera código real a partir delas, que roda de forma determinística nas execuções subsequentes. A primeira execução é dirigida pelo agente e exploratória. Toda execução depois disso é rápida e confiável. É um padrão que não vi em outras ferramentas de automação de navegador, e faz a diferença entre "demo legal" e "fluxo de trabalho de produção".

A Fusão de Skills e Comandos Personalizados

Uma mudança arquitetural que vale mencionar: skills e slash commands personalizados no Claude Code estão convergindo. Versões anteriores os tratavam como sistemas separados — comandos eram atalhos rápidos, skills eram módulos de conhecimento mais profundos. A partir do Claude Code 2.1, a linha ficou borrada.

Uma skill agora pode se registrar como slash command através do frontmatter:

---
name: security-audit
description: Full OWASP-aligned security review of the current project
command: /audit
context: fork
---

Digitar /audit no Claude Code aciona a skill completa com todas suas funcionalidades avançadas — forking, injeção dinâmica, execução em segundo plano. Sem necessidade de manter configurações de comandos separadas.

Essa convergência importa porque reduz a carga cognitiva de gerenciar seu kit de ferramentas. Antes eu mantinha um mapa mental de "quais coisas são skills e quais são comandos". Agora tudo é uma skill, algumas das quais têm atalhos de comando. Um sistema. Uma localização. Um framework de testes.

O post claude-skills-guide-decoded que escrevi anteriormente cobre o formato fundamental do SKILL.md em profundidade. O que mudou desde então é que o formato agora suporta significativamente mais opções de frontmatter — context, model, command, restrições de ferramentas e hooks de ciclo de vida — transformando um simples arquivo markdown em uma configuração completa de agente.

O Que Eu Errei (E O Que Faria Diferente)

Quero encerrar com os erros, porque são mais úteis que os sucessos.

Erro 1: Forking em excesso. Depois de descobrir o context forking, apliquei em tudo. Uma skill de formatação de 3 linhas que gerava 200 tokens de saída? Bifurcada. O overhead de criar um subagente excedia o custo de contexto de simplesmente rodá-la inline. Bifurque skills que geram mais de 2.000 tokens de memória de trabalho. Deixe skills simples rodarem na sua sessão principal.

Erro 2: Injeção dinâmica sem cache. Algumas das minhas chamadas !command consultavam APIs em cada ativação da skill. Se você dispara uma skill 10 vezes em uma hora, são 10 chamadas idênticas à API. Agora uso comandos de shell que verificam primeiro um resultado em cache e só consultam ao vivo se o cache estiver obsoleto. Padrão simples, óbvio em retrospecto, mas estourei meus limites de taxa de API antes de descobrir isso.

Erro 3: Construir skills para coisas que o Claude já faz bem. O framework de A/B testing me ensinou isso: se o Claude sem skill lida com a tarefa com qualidade acima de 80% sem uma skill, a skill não vale a pena manter. Skills devem mirar nas lacunas — as convenções específicas do projeto, as integrações com ferramentas externas, o conhecimento de domínio que o Claude não tem. Construir uma skill para "escrever bom código Python" é esforço desperdiçado. Construir uma skill para "escrever código Python que siga o padrão de decorators do nosso time para endpoints FastAPI com logging estruturado" é uma melhoria real.

Erro 4: Ignorar os testes até ser tarde demais. Seis skills quebradas depois de uma atualização do modelo. Foi o que precisou acontecer. Construa a suíte de eval junto com a skill, não depois.

A avaliação honesta de onde as skills estão agora: o sistema funciona. As funcionalidades avançadas — forking, injeção, agentes em segundo plano, evals automatizados — transformam skills de "templates de prompt espertos" em automação de fluxos de trabalho genuína. As ferramentas ainda estão em estágio inicial o suficiente para que você encontre arestas (mensagens de erro de skills bifurcadas poderiam ser muito mais descritivas, e a configuração do A/B testing requer mais configuração manual do que deveria). Mas a arquitetura é sólida, e o ecossistema está se movendo em um ritmo que eu não via desde os primeiros dias do npm.

Sete mil skills só no SkillsMP, e o formato funciona no Claude Code, Codex CLI, Gemini CLI e Cursor. Isso não é mais uma funcionalidade específica do Claude. É um padrão da indústria se formando em tempo real.

A questão não é se você deve investir em aprender as funcionalidades avançadas de skills. É se você pode se dar ao luxo de continuar construindo agentes sem elas.

Perguntas Frequentes

O que é context forking nas skills do Claude Code?

O context forking cria um subagente dedicado com sua própria janela de contexto para executar uma skill em isolamento. Adicione context: fork ao frontmatter do seu SKILL.md para evitar que skills pesadas poluam sua conversa principal. Para o passo a passo completo, veja a seção de Context Forking acima.

Como eu instalo skills do Claude Code a partir do marketplace?

Execute /plugin install <skill-name>@<marketplace> no Claude Code, ou adicione um marketplace de terceiros com /plugin marketplace add <repo>. Skills são instaladas em .claude/skills/ para uso com escopo de projeto ou em ~/.claude/skills/ para uso pessoal.

O que é injeção dinâmica de contexto no Claude Code?

A injeção dinâmica de contexto usa a sintaxe !command no SKILL.md para rodar comandos de shell antes da skill carregar. A saída do comando substitui o marcador, de forma que o Claude recebe dados do projeto em tempo real — branch do git, variáveis de ambiente, respostas de API — sem gastar tokens em descoberta.

Como eu testo skills do Claude Code com o Skill Creator?

Instale o plugin Skill Creator, defina prompts de teste com saídas esperadas e rode o modo eval. Para validação mais profunda, use o modo improve, que roda testes A/B cegos comparando a saída do Claude com e sem a skill ativa. Veja a seção de Teste e Avaliação acima.

Skills do Claude Code podem rodar em segundo plano?

Sim. Skills com context: fork podem criar agentes em segundo plano que trabalham de forma assíncrona enquanto sua sessão principal continua responsiva. Use /tasks para monitorar skills rodando em segundo plano, verificar seu status ou cancelá-las.

Vamos Trabalhar Juntos

Procurando construir sistemas de IA, automatizar fluxos de trabalho ou escalar sua infraestrutura tecnológica? Adoraria ajudar.

• Fiverr (projetos 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