TL;DR
Troquei subagentes por skills em tarefas repetitivas e medi a diferença ao vivo
Code review: 38.000 tokens → 2.800 tokens (-93%) | 3min40s → 22 segundos (-90%)
A pergunta de decisão que resolve 80% dos casos: isolamento ou contexto da sessão?
Template de SKILL.md copiável + os dois campos de frontmatter que todo mundo ignora
O único caso onde subagente ainda ganha: paralelismo (com dados)
🎥 Tutorial em Vídeo
Gravei o comparativo: subagente vs skill no mesmo código, commit review em 8 segundos e o caso do paralelismo.
O Problema Que Eu Tinha
Depois de montar os primeiros orquestradores com subagentes, entrei no modo "agente resolve tudo."
Todo fluxo repetitivo que eu queria automatizar criava um subagente. Parecia o caminho natural. Em duas semanas eu tinha 7 subagentes criados: code-reviewer.md, commit-checker.md, pattern-validator.md. Cada um com seu próprio prompt, ferramentas, permissões.
A conta chegou quando eu abri o dashboard de uso de tokens.
Cada execução do code-reviewer: 38.000 tokens. Do zero. O subagente explorava todos os arquivos relevantes, reconstruía o contexto do projeto, e só então fazia a revisão. Sem memória da sessão. Sem acesso ao que eu já tinha discutido.
E o detalhe mais frustrante: 10 minutos antes de rodar o code-reviewer, eu tinha comentado na conversa que queries.js recebia input não-sanitizado. O subagente não sabia disso. Explorou o arquivo, viu a função, não sinalizou nada de errado porque não tinha o contexto do problema que eu já tinha identificado.
Eu estava pagando por isolamento que atrapalhava o meu trabalho, não ajudava.
Tinha criado 7 subagentes em duas semanas. Todos faziam a tarefa certa para o problema errado. O problema não era o código que eles produziam era o ponto de partida. Começar do zero toda vez, em contexto isolado, para tarefas que precisavam exatamente do histórico que eu já tinha construído na sessão.
A Descoberta
A virada veio quando li uma frase na documentação oficial da Anthropic e ela está lá, explícita:
"Consider Skills instead when you want reusable prompts or workflows that run in the main conversation context rather than isolated subagent context."
Quando li isso, entendi o erro.
Skill e subagente parecem a mesma coisa, mas fazem isso de lugares completamente diferentes.
Skill roda dentro da sua sessão. Quando você invoca /code-review, o Claude já sabe tudo que você discutiu, quais arquivos você abriu, o que comentou, as decisões que tomou. Não precisa explorar do zero porque o contexto já existe na conversa.
Subagente abre uma janela separada. Começa do zero. De propósito, e isso é exatamente o que torna ele útil, mas quando você quer esse isolamento.
A maioria das automações que eu tinha criado não precisava de isolamento. Precisava exatamente do contrário.
Antes vs Depois, Code Review:
Subagente | Skill | |
|---|---|---|
Tempo | 3min40s | 22 segundos |
Tokens | 38.000 | 2.800 |
Problemas encontrados | 4 | 6 |
Acessa histórico da sessão | ❌ | ✅ |
Os +2 problemas que a skill encontrou vieram direto do contexto da conversa: eu tinha mencionado a vulnerabilidade em queries.js antes de invocar a skill. O subagente nunca teria acesso a isso.
Tutorial Passo-a-Passo
Passo 1: Criar a estrutura da skill
Skills ficam em .claude/skills/<nome>/SKILL.md. Só isso.
mkdir -p .claude/skills/code-review
touch .claude/skills/code-review/SKILL.md
Compare com subagente:
# Subagente fica em:
.claude/agents/code-reviewer.md
A localização define o comportamento. Skill: injeta no contexto principal. Agente: janela separada.
Passo 2: Escrever o SKILL.md
Template base copiável:
---
name: code-review
description: "Revisa código com foco em segurança, performance e padrões do projeto"
---
# Code Review
## O que fazer
Revisar o diff atual (`git diff HEAD~1`) identificando:
- Problemas de segurança (SQL injection, XSS, credenciais expostas)
- Performance (queries N+1, loops desnecessários)
- Violações dos padrões do projeto (verificar CLAUDE.md)
- Inconsistências com o que foi discutido nesta sessão
## Formato do output
Para cada problema encontrado:
1. **Arquivo e linha**: onde está o problema
2. **Severidade**: Alta / Média / Baixa
3. **Descrição**: o que está errado e por quê
4. **Sugestão**: como corrigir
Ao final: resumo com contagem por severidade.
O campo description é o que o Claude usa para decidir quando carregar a skill automaticamente, escreva como o rótulo da ferramenta para o modelo.
Passo 3: Usar os campos de frontmatter que importam
disable-model-invocation: true - o mais importante:
---
name: commit-review
description: "Valida commits antes de enviar"
disable-model-invocation: true
---
Por padrão, o Claude pode invocar uma skill sozinho se achar a situação relevante. disable-model-invocation: true desativa isso, a skill só roda quando você chamar explicitamente.
Para qualquer ação com efeito colateral (commit, deploy, envio de email), esse campo é não-negociável. Você quer decidir o timing, não o modelo.
user-invocable: false - para skills internas:
---
name: context-sync
user-invocable: false
---
Faz a skill sumir do menu /. Ela continua existindo e você pode chamar pelo nome, mas não fica aparecendo na lista. Útil para skills que o Claude usa internamente e não precisam ser visíveis.
Passo 4: Invocar a skill
/code-review
Sem configuração adicional. O slash command vem direto do campo name no frontmatter.
Se quiser que o Claude invoque automaticamente quando relevante (sem disable-model-invocation: true), basta escrever um description claro o modelo usa esse campo para decidir quando acionar.
Passo 5: Decidir quando usar skill vs subagente
O fluxo de decisão que uso:
Nova automação
↓
Precisa do contexto da conversa?
→ Sim → Skill
↓
Precisa rodar em paralelo com outras tarefas?
→ Sim → Subagente
↓
Output vai ser volumoso demais pro contexto?
→ Sim → Subagente
↓
Padrão → Skill
A pergunta central que resolve 80% dos casos:
"A tarefa precisa de isolamento ou precisa do contexto que você já tem?"
Caso de Uso: Commit Review
O segundo caso que implementei como skill foi o workflow de commit os mesmos 5 passos que eu descrevia de novo toda sessão:
---
name: commit-review
description: "Workflow de commit: valida, sugere mensagem, aguarda confirmação"
disable-model-invocation: true
---
# Commit Review
Executar em sequência:
1. `git diff HEAD` — listar arquivos modificados
2. Verificar se há credenciais ou dados sensíveis expostos
3. Verificar se os testes passam para os arquivos modificados
4. Sugerir mensagem de commit seguindo o padrão do projeto
5. Aguardar confirmação antes de executar o commit
Resultado: 8 segundos. 5 passos executados. Zero chance de esquecer algum.
O disable-model-invocation: true garante que a skill nunca roda automaticamente. Commit é uma ação com efeito colateral eu quero decidir quando acontece.
Quando Subagente Ainda Ganha
Sendo honesto: tem um caso onde subagente ganha de forma clara. Paralelismo.
Skill roda no contexto principal sequencialmente. Se você tem 6 módulos independentes para refatorar, a skill processa um por vez.
Medição real:
Skill sequencial (3 módulos): 3min34s
Orquestrador com 6 subagentes em paralelo: 1min12s
Extrapolado para o projeto completo: skill levaria ~16 minutos, subagentes ~5 minutos. 3x mais rápido.
O sinal para usar subagente em vez de skill:
Tarefas independentes que podem rodar juntas (sem dependência entre si)
Output que seria volumoso demais para o contexto principal
Você precisa de um modelo diferente (ex: Haiku para cortar custo)
Contexto da sessão vira risco (dados sensíveis que a próxima tarefa não deveria ver)
Caso contrário → skill.
📚 Documentação Oficial
Próximos Passos
Hoje: Identificar um subagente que você usa para tarefa repetitiva (code review, commit, lint)
Amanhã: Migrar para skill — criar
.claude/skills/<nome>/SKILL.mdcom o template acimaEsta semana: Medir a diferença em tempo e tokens (anota os dois antes de migrar)
Próxima semana: Revisar os outros subagentes usando o fluxo de decisão do Passo 5
Adriano Viana
System Architect | AI-Native Content Creator