Criei um subagent do Claude Code do zero: o .md, as tools e como agendo com /loop e cron

Passei os últimos dias montando subagents do Claude Code e queria dividir o esqueleto. A doc oficial é boa, mas ninguém junta num lugar só a parte de criar o agente + dar skills + agendar com cron.

O que é um subagent

Uma instância paralela do Claude, com janela de contexto própria, system prompt focado e tools restritas. O agente principal delega uma tarefa, o subagent resolve isolado e devolve só o resultado. Isso preserva o contexto da conversa principal e ainda deixa limitar o que cada worker pode fazer.

O arquivo

Um subagent é um Markdown com frontmatter YAML em .claude/agents/<nome>.md (projeto, versionado no git) ou ~/.claude/agents/ (global):

---
name: researcher
description: Pesquisa e coleta contexto sobre um tema. Devolve um briefing em JSON. Use antes de gerar conteúdo.
tools: Read, WebSearch, WebFetch
model: sonnet
---
Você é um agente de pesquisa. Ao receber um tema, valide as fontes, extraia
os pontos principais e devolva TUDO como JSON, sem prosa fora do objeto.

• description é o gatilho: o Claude lê isso pra decidir quando delegar.
• tools restringe (omitir = herda todas). Menos tool = mais previsível e seguro.
• model roteia custo: haiku pra leitura/triagem, sonnet/opus pra geração.

Skills: dar habilidades ao agente

Skill é um procedimento reutilizável em .claude/skills/<nome>/SKILL.md. Carrega sozinha quando a description casa, ou você chama com /nome. disable-model-invocation: true deixa manual-only; context: fork roda a skill dentro de um subagent.

Agendar com headless + cron

O pulo do gato é rodar sem digitar nada:

claude -p "pesquisa o tema e devolve um briefing" --agent researcher \
  --permission-mode acceptEdits --allowedTools "Read,Bash" --output-format json

Envolve isso num script + cron (ou launchd no macOS) e o agente trabalha sozinho. Dentro da sessão também dá pra usar /loop.

Orquestração (e quem manda ainda é você)

Dá pra montar uma linha de montagem de subagents: um pesquisa e devolve briefing JSON, outro consome e gera o rascunho, um terceiro revisa antes de fechar. Cada etapa é um subagent com contrato JSON entre elas, e é isso que torna o fluxo previsível e fácil de depurar.

Mas tem um ponto que nenhuma automação dispensa: a responsabilidade final é sua. O agente executa a etapa, mas quem comanda precisa auditar a saída e validar se está tudo conforme o esperado antes de confiar nela. Subagents e skills automatizam o trabalho pesado; a decisão, a revisão e a qualidade continuam nas suas mãos. No fim, o trabalho é seu: eles só aceleram as etapas.

Escrevi o passo a passo completo (config avançada, tabela subagent × skill × MCP e a parte de schedule) aqui: https://www.techknow.com.br/post/claude-code-agents-subagent

Como vocês estão orquestrando subagents? Curioso pra saber quem já botou cron em cima disso, e principalmente como vocês revisam a saída deles.