🧩 O que é uma skill
Uma skill é uma capacidade reutilizável que o Claude Code carrega sob demanda. Na prática, é um arquivo SKILL.md: um frontmatter com name e description, mais um corpo em Markdown com os passos e arquivos de referência opcionais.
A description é o gatilho: quando a tarefa que você pede bate com ela, a skill ativa sozinha e injeta os passos no contexto. Você ensina uma vez, usa sempre — sem reescrever o procedimento a cada conversa.
💡 Dica prática
Pense na skill como um colega que já sabe o procedimento. Você não explica de novo — só diz "faz aquilo" e a description reconhece o pedido. Quanto melhor a descrição, mais certeiro o gatilho.
ensina uma vez
carrega ao precisar
frontmatter + passos
a description ativa
🕵️ O que é um subagente
Um subagente é uma instância separada do Claude, com a sua própria janela de contexto, o seu próprio system prompt e as suas próprias ferramentas. Ele recebe uma tarefa, trabalha isolado e devolve só o resultado — para que o contexto do agente principal continue limpo.
É um trabalhador dedicado. O que ele lê, baixa e processa fica no contexto dele, não no seu. Você só recebe o resumo do que importa — o equivalente a delegar uma pesquisa pesada sem afogar a conversa.
Recebe a tarefa
O agente principal delega um trabalho específico — "pesquise a empresa X", "varra esse setor" — com instruções claras.
Trabalha isolado
Lê dezenas de páginas, roda buscas, processa dados — tudo no contexto próprio dele. Nada disso polui o seu thread.
Devolve o resumo
Retorna só a conclusão — os achados que interessam. O agente principal segue com o contexto enxuto e focado.
contexto próprio
prompt + tools próprios
só o que importa
protege o principal
⚖️ Skill vs agente: quando cada um
A confusão mais comum é usar agente onde bastava skill — e sobre-engenheirar. A regra é simples. Skill é uma capacidade que você dá ao agente principal (gerar um PPTX, rodar um diagnóstico). Subagente é um trabalhador separado para um trabalho que queima muito contexto ou precisa de isolamento (varrer a web, pesquisar uma empresa).
Regra de bolso: mesmo thread + procedimento reutilizável → skill. Thread separado + trabalho pesado ou independente → subagente.
✓ Vira SKILL quando…
- ✓É um procedimento que se repete no mesmo thread
- ✓Você quer dar uma capacidade ao agente principal
- ✓O resultado fica na conversa (deck, diagnóstico, SOW)
- ✓Não queima muito contexto para rodar
✓ Vira AGENTE quando…
- ✓O trabalho queima muito contexto (varrer a web)
- ✓Precisa de isolamento — não quer poluir o thread
- ✓É independente e pode rodar em paralelo
- ✓Você só quer o resumo de volta, não o caminho
💡 Na dúvida, comece com skill
Subagente é mais poder, mas também mais peça móvel. Se a tarefa cabe no mesmo thread sem afogar o contexto, faça skill. Promova para subagente só quando o isolamento ou o volume de contexto pedirem.
capacidade
delegação pesada
→ skill
→ subagente
🔬 Anatomia de uma skill (SKILL.md)
Uma skill é um arquivo só. No topo, um frontmatter YAML com name e description. Abaixo, um corpo em Markdown com os passos. Veja o esqueleto mínimo de uma skill de diagnóstico de IA.
// .claude/skills/diagnostico-ia/SKILL.md
--- name: diagnostico-ia description: Use ao diagnosticar a maturidade de IA de uma empresa descrita em texto — gera maturidade 1-5, quick wins e roadmap 30/60/90. --- # Diagnóstico de IA ## Passos 1. Ler a descrição da empresa. 2. Pontuar a maturidade de IA (1-5). 3. Listar 3 quick wins (esforço × impacto). 4. Sugerir um roadmap 30/60/90.
id curto — o nome da skill, usado para referenciá-la. Sem espaços, direto ao ponto.
o gatilho — descreve quando usar a skill. É o que o Claude lê para decidir se ativa.
os passos — o procedimento em Markdown que o agente segue depois de ativar.
💡 A description é a parte mais ignorada
É a peça mais importante e a mais negligenciada. Uma description vaga ("ajuda com estratégia") nunca ativa na hora certa. Diga quando usar, com gatilhos concretos — é isso que faz a skill aparecer sozinha.
id curto
o gatilho
os passos
tudo num SKILL.md
📁 Onde skills e subagentes vivem
Tudo mora numa pasta .claude/. Skills ficam em .claude/skills/<nome>/SKILL.md; subagentes em .claude/agents/<nome>.md. A escolha é entre escopo de projeto (vai junto no Git) e escopo pessoal (vale em todo projeto seu).
📦 Do projeto (.claude/)
- ✓Vive na raiz do repositório do projeto
- ✓Vai junto no Git — todo o time herda
- ✓Ideal para a Fábrica: versionada com o código
🏠 Pessoal (~/.claude/)
- ✓Vive na sua home — fora de qualquer repo
- ✓Vale em todo projeto que você abrir
- ✓Ideal para ferramentas suas, de uso geral
// estrutura do projeto
.claude/
├── skills/
│ ├── diagnostico-ia/SKILL.md
│ └── gerar-entregavel/SKILL.md
└── agents/
├── pesquisador-empresa.md
└── redator-estrategia.md
um SKILL.md cada
um .md cada
vai no Git
vale em tudo
💎 O ecossistema de recursos reutilizáveis
Aqui está o porquê de tudo isso virar ativo. Cada skill e cada agente é construído uma vez e reusado para sempre. Juntos, eles formam as engrenagens da Fábrica — o seu arsenal.
É a tese "entrada mínima, saída máxima" virada código. O esforço vai para a construção, não para a entrega. Quanto mais peças você acumula, mais a Fábrica entrega sozinha — e o custo marginal de cada novo cliente despenca.
💡 Construa o arsenal, não o entregável
Toda vez que você fizer uma tarefa à mão, pergunte: "isso vira skill ou agente?". Se sim, transforme — e nunca mais refaça. O entregável é descartável; a peça reutilizável é o que se acumula e te dá alavancagem.
reusar sempre
peças da Fábrica
se acumula
custo marginal ↓
✅ Resumo do módulo
🎯 Missão 3.1 — Mapeie seu arsenal
Liste as suas tarefas e classifique cada uma como skill ou subagente:
- 3 tarefas repetitivas suas que viram skill (ex.: diagnosticar empresa, gerar deck, escrever SOW).
- 2 tarefas que viram subagente (ex.: pesquisar uma empresa na web, varrer um setor inteiro).
Sucesso: 3 skills + 2 agentes mapeados. O que você ganhou: o desenho do seu arsenal — o que construir nas próximas aulas.
Próximo módulo:
3.2 — Construa sua primeira skill (diagnostico-ia)