Claude Code: skills, subagentes, hooks e workflows — qual usar em 2026

O Claude Code hoje tem oito maneiras diferentes de mudar o próprio comportamento — e a maioria dos times usa apenas uma. Em um estudo com 2.853 repositórios públicos que continham arquivos de configuração de agente, 90,6% tinham um arquivo de contexto como o CLAUDE.md, 5,5% tinham uma skill e 4,6% tinham um subagente (arXiv, fevereiro de 2026). Ou seja: a esmagadora maioria escreveu suas convenções em um arquivo e parou por aí.

O problema é que CLAUDE.md, regras e skills são pedidos — o modelo lê e normalmente obedece, mas não há garantia. Um hook, por outro lado, é uma garantia: dispara em um evento do ciclo de vida, aconteça o que acontecer, e o código de saída 2 bloqueia a ação. Saber a diferença entre cada primitivo — e quando apagá-lo — é o que separa um setup que trava de um que escala.

Os oito primitivos em uma única tabela

Os documentos oficiais espalham essas comparações por seis abas e três páginas. Aqui estão os oito primitivos em um só lugar — e a última coluna é a que diz o que você pode, de fato, confiar:

Skills vs Subagentes: contexto é toda a diferença

Uma skill é texto que o Claude lê. Um subagente é um segundo Claude. A descrição de uma skill fica no seu contexto em toda sessão (limitada a 1.536 caracteres na listagem) e o corpo carrega quando ela é usada — tudo acontece na sua janela, com seu histórico e suas ferramentas. O subagente ganha a própria janela, o próprio prompt de sistema, a própria lista de ferramentas e, muitas vezes, o próprio modelo. Ele faz o trabalho e devolve um resumo.

Essa diferença decide tudo: o custo de cada um, o que cada um enxerga e o que cada um pode quebrar. A regra é curta: use skill quando o Claude deve saber algo ou seguir um procedimento (como escrevemos rotas de API, o checklist de release, as convenções de nomenclatura). Use subagente quando o trabalho produz saída que você não vai reler (buscas, logs, ruído de revisão) ou quando precisa de outro modelo ou um conjunto de ferramentas mais estreito.

---
name: code-reviewer
description: Revisa código quanto a arquitetura, performance e padrões. Use proativamente.
tools: Read, Glob, Grep, Bash
model: opus
skills:
  - code-review
  - security-reviewer
---
Você é um especialista em revisão de código. Revise todos os arquivos do
changeset atual e produza um relatório por severidade.

Quando o Claude entrega um diff de 40 arquivos a esse subagente, os 40 arquivos carregam na janela dele — e a sua recebe só seis achados de volta. As duas skills pré-carregadas são as mesmas que você poderia rodar com /code-review na conversa principal. Mesma checklist, sala diferente.

Hooks vs Skills: pedido versus garantia

A documentação oficial é direta: o Claude trata CLAUDE.md e a memória automática “como contexto, não configuração aplicada”. Para bloquear uma ação independentemente do que o modelo decidir, use um hook PreToolUse. Um hook é uma entrada no settings.json: um evento, um matcher e um comando. O comando recebe o evento como JSON na entrada padrão e responde com um código de saída. Saída 0 significa sem objeção; saída 2 significa bloqueado, e o que você escreveu no stderr volta ao Claude como motivo.

#!/bin/bash
# .claude/hooks/protect-files.sh
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

for pattern in ".env" "prisma/migrations/" "terraform/"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2   # exit 2 = bloqueia; stderr vira o feedback do Claude
  fi
done
exit 0     # exit 0 = sem objeção; fluxo normal de permissão

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/protect-files.sh" }
        ]
      }
    ]
  }
}

Segredos, migrações já aplicadas e infraestrutura: peça ao Claude para “adicionar um comentário ao .env” e a edição é bloqueada antes de acontecer. O mesmo formato em um evento PostToolUse roda o Prettier em todo arquivo que o Claude tocar. A regra final: convenções vão no CLAUDE.md, guardrails vão em hooks.

Slash commands agora são skills

Se você aprendeu Claude Code em 2025, escrevia comandos como arquivos Markdown em .claude/commands/. Eles ainda funcionam, mas foram incorporados às skills. Um arquivo em .claude/commands/deploy.md e uma skill em .claude/skills/deploy/SKILL.md criam o mesmo /deploy. O que a forma de skill adiciona é uma pasta para arquivos de apoio e duas chaves de frontmatter que respondem “quem tem permissão para disparar isso”:

---
name: deploy
description: Deploy da branch atual para o Cloud Run após o checklist passar.
disable-model-invocation: true  # só você roda /deploy; o Claude nunca auto-invoca
---

Use disable-model-invocation: true para qualquer coisa com efeitos colaterais: deploys, releases, migrações de banco. O custo de contexto é zero até você digitar o comando. A chave espelhada, user-invocable: false, esconde a skill do menu / para que só o Claude a carregue — ideal para material de referência.

Plugins são embalagem, não primitivo

Um plugin não faz nada sozinho. É uma pasta com um manifesto em .claude-plugin/plugin.json e qualquer mistura de skills/, agents/, hooks/ e um .mcp.json. Instale e cada parte interna fica disponível, com skills no namespace /plugin-name:skill para que dois plugins possam enviar um /review cada um. O gatilho para construir um é específico: um segundo repositório precisa do mesmo setup. Até lá, mantenha tudo solto em .claude/.

Workflows vs Subagentes: um ajudante ou um script que roda muitos

Um subagente é um ajudante que você despacha. Um workflow é um script que despacha muitos ajudantes e devolve uma resposta. Você descreve a tarefa, o Claude escreve o script, você aprova, e ele roda em segundo plano enquanto você continua trabalhando. Nada no meio do caminho cai na sua janela.

Workflows chegaram em 28 de maio de 2026, na v2.1.154. Dois números para guardar: uma execução pode usar até 1.000 agentes, mas apenas 16 rodam ao mesmo tempo. “Centenas de agentes em paralelo” significa centenas por execução, não simultâneos.

> ultracode: audite todos os route handlers em src/app/api em busca de
queries Prisma que pulam o escopo organizationId, e verifique cada achado

const found = await agent('Liste todos os route.ts sob src/app/api/.', {
  schema: { type: 'object', required: ['files'],
    properties: { files: { type: 'array', items: { type: 'string' } } } },
})
const findings = await pipeline(found.files, file =>
  agent(`Cheque ${file}: toda query Prisma está escopada por organizationId?`, { label: file }))
const verified = await pipeline(findings.filter(Boolean), f =>
  agent(`Verifique adversarialmente este achado. Retorne null se não valer: ${JSON.stringify(f)}`, { label: 'verify' }))
return verified.filter(Boolean)

Leia de cima para baixo: um agente lista as rotas, um agente por rota verifica, e um agente por achado tenta derrubá-lo. Você recebe só os achados que sobreviveram. O maior exemplo público é a reescrita do Bun de Zig para Rust: cerca de um milhão de linhas em 11 dias, aproximadamente 50 workflows, por volta de US$ 165 mil em preço de API e 19 regressões conhecidas. O criador do Zig, Andrew Kelley, chamou o resultado de “um milhão de linhas de slop não revisado”. Um workflow escreve um milhão de linhas; revisá-las continua sendo trabalho seu.

Qual primitivo usar: a tabela de gatilhos

Apague o que o modelo não precisa mais

Cada regra, skill e subagente que você adiciona é um remendo para algo que o modelo não conseguia fazer de forma confiável na época. Modelos melhoram. Um setup que só cresce acaba carregando remendos para problemas que já sumiram — uma regra que custa contexto a cada request para evitar um erro que o modelo parou de cometer, ou um subagente de revisão que gasta tokens para pegar o que o modelo agora acerta de primeira.

O próprio time de harness da Anthropic enfrentou isso em escala: adicionaram um segundo agente para julgar o trabalho do primeiro, porque agentes que se autoavaliam “tendem a elogiar o próprio trabalho com confiança”. Ajudou, mas o arranjo completo custou mais de vinte vezes uma execução solo — US$ 200 contra US$ 9 — e só compensava em tarefas que o modelo não resolvia sozinho. Quando o Opus 4.6 chegou, eles apagaram um componente inteiro que o novo modelo não precisava mais.

A versão prática é simples: após cada lançamento de modelo, desligue uma regra ou skill por uma semana. Se nada regredir, apague. Seu harness deve encolher conforme o modelo melhora — e o único jeito de saber se o seu faz isso é testando.

Perguntas frequentes

Devo usar skill ou subagente? Skill para conhecimento e procedimentos que o Claude deve seguir na sua janela; subagente para trabalho isolado cuja saída você não vai reler, ou que precisa de outro modelo.

Hook substitui o CLAUDE.md? Não. CLAUDE.md guarda convenções (pedidos); hooks guardam guardrails (garantias). São complementares.

Quantos agentes um workflow roda por vez? Até 1.000 por execução, mas no máximo 16 simultâneos.

Plugin é obrigatório para compartilhar meu setup? Só quando um segundo repositório precisa do mesmo conjunto. Até lá, mantenha em .claude/.

Agent teams já estão estáveis? Não — são experimentais e desligados por padrão. Habilite com CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.