Um agente de marketing digital do zero: os arquivos, a árvore e o passo a passo

O agente que conversa e o agente que entrega

Quase todo mundo que me mostra "o agente que eu montei" me mostra a mesma coisa: um prompt grande, colado numa caixa de texto, que responde muito bem sobre o assunto e não produz nada. Você pergunta sobre calendário editorial e ele explica o que é um calendário editorial. Bonito. Inútil.

A diferença entre esse e um agente que trabalha não está no modelo nem no tamanho do prompt. Está na estrutura de arquivos. Um agente de verdade é uma pasta com quatro ou cinco arquivos de texto, cada um com um papel diferente, lidos em momentos diferentes.

Neste texto eu monto um do zero, na frente de você. É um agente de marketing digital: educado, focado em executar tarefa — calendário, e-mail, anúncio, página —, e não em palestrar sobre marketing.

Todos os arquivos estão aqui, inteiros. Se você copiar os cinco para uma pasta e abrir o Claude Code dentro dela, o agente funciona. Não tem passo escondido.

As quatro peças de um agente

Antes da árvore, o modelo mental. Um agente é composto de quatro coisas, e cada uma vira um tipo de arquivo:

• Identidade — quem ele é, como decide, o que recusa. É o system prompt dele. Vira o arquivo do agente.
• Contexto — o que ele sabe sobre o seu mundo: produto, público, tom, histórico. Vira o CLAUDE.md.
• Procedimento — como se faz uma tarefa específica, com a régua e os limites. Vira uma skill, carregada só quando o assunto aparece.
• Gatilho — como a pessoa pede. Vira um slash command.

Se você é de desenvolvimento, a analogia mais próxima é essa: o agente é a classe, a skill é o módulo que ele importa sob demanda, o comando é a CLI, e o CLAUDE.md é a configuração de ambiente que todo mundo lê ao subir.

O erro mais comum é empilhar as quatro coisas num prompt só. Funciona por uma semana. Depois o prompt tem 400 linhas, o modelo passa a ignorar o meio dele, e você não consegue mais mudar uma regra sem quebrar outra.

A árvore

Esta é a estrutura completa do nosso exemplo — uma loja fictícia de ferramentas para marcenaria:

ferro-e-cia/
├── CLAUDE.md                          # contexto do projeto, lido sempre
├── marketing/
│   ├── publicado/                     # o que já foi ao ar
│   └── saida/                         # onde o agente escreve
└── .claude/
    ├── agents/
    │   └── marketing.md               # QUEM: identidade, método, limites
    ├── skills/
    │   └── campanha-de-lancamento/
    │       ├── SKILL.md               # COMO: o procedimento, sob demanda
    │       └── referencias/
    │           └── canais.md          # limites de formato por canal
    └── commands/
        └── campanha.md                # ATALHO: /campanha, para a pessoa

Três coisas para reparar antes de escrever qualquer linha:

A pasta .claude/ é a máquina; a pasta marketing/ é o produto. O agente lê a primeira e escreve na segunda. Manter isso separado é o que te deixa versionar a máquina no Git sem misturar com a saída dela.

Cada arquivo é carregado num momento diferente. O CLAUDE.md entra sempre. O arquivo do agente entra quando ele é chamado. A skill entra quando o assunto aparece. O comando entra quando a pessoa digita. Isso não é firula de organização: é o que mantém a janela de contexto livre para o trabalho de verdade.

Nada aqui é código. São cinco arquivos de texto. A parte difícil é decidir o que escrever neles, não a sintaxe.

Passo 1 — o contexto do projeto (CLAUDE.md)

Este arquivo mora na raiz e é lido em toda sessão, por qualquer agente. Ele responde uma pergunta só: em que mundo estamos?

# Contexto do projeto

Somos a **Ferro & Cia**, loja online de ferramentas manuais para marcenaria amadora.

- **Público:** adultos de 30 a 55 anos que trabalham na garagem, nos fins de semana.
- **Oferta principal:** kit iniciante de entalhe, R$ 480, frete grátis acima de R$ 300.
- **Tom:** de oficina — direto, sem gíria de startup, sem promessa de resultado.
- **Canais:** e-mail (lista de 4.200 pessoas), Instagram, Google Search.
- **O que não fazemos:** desconto relâmpago, contagem regressiva falsa, citar concorrente pelo nome.

## Onde as coisas ficam

- `marketing/saida/` — peças novas, ainda não publicadas.
- `marketing/publicado/` — o que já foi ao ar. Consulte antes de escrever para não repetir gancho.

Duas regras que eu aprendi apanhando aqui:

Seja específico ou não escreva. "Tom profissional e moderno" não muda uma vírgula na saída do modelo. "Sem gíria de startup, sem promessa de resultado" muda tudo, porque é uma instrução verificável.

Escreva o que vocês não fazem. A lista de limites é a parte deste arquivo que mais economiza retrabalho. É o que impede o agente de escrever "últimas 24 horas!" numa loja que não usa urgência falsa.

Passo 2 — o agente (.claude/agents/marketing.md)

Aqui mora a identidade. O arquivo tem duas partes: um cabeçalho em YAML entre ---, e o corpo em Markdown, que é literalmente o system prompt do agente.

---
name: marketing
description: >
  Executa tarefas de marketing digital: calendário editorial, texto de anúncio,
  assunto e corpo de e-mail, página de captura, roteiro de vídeo curto,
  descrição de produto e relatório simples de campanha.
  Use sempre que o pedido for produzir uma peça de marketing pronta para publicar,
  ou revisar uma peça existente contra o objetivo dela.
tools: Read, Write, Edit, Glob, Grep, WebFetch, WebSearch
model: sonnet
---

# Marketing digital

Sou o agente de marketing digital deste projeto. Recebo um objetivo e devolvo peça
pronta — arquivo salvo, com título, corpo e chamada para ação. Não devolvo lista de
sugestões sobre o que poderia ser feito.

## Como eu trabalho

1. **Leio o contexto antes de escrever.** `CLAUDE.md` na raiz e os arquivos de
   `marketing/publicado/` que forem do mesmo canal — para não repetir gancho.
2. **Pergunto uma vez só.** Quando faltar objetivo, público ou prazo, pergunto os três
   juntos e sigo. Sem resposta, adoto a hipótese mais conservadora, escrevo a peça e
   deixo a hipótese anotada no rodapé do arquivo.
3. **Termino com artefato.** Toda tarefa gera arquivo em
   `marketing/saida/<AAAA-MM-DD>-<assunto>.md`. Trabalho sem arquivo salvo não está feito.
4. **Dou variações onde o canal testa.** Anúncio e assunto de e-mail saem em três
   versões numeradas, cada uma com uma linha dizendo qual hipótese ela testa.
5. **Fecho com o próximo passo.** Uma frase: o que publicar, onde, e o que olhar depois.

## Como eu falo com a pessoa

Educado e direto. Uso "você", trato pelo nome quando ele aparece no contexto, explico
jargão de marketing na primeira vez que ele aparece e recuso adjetivo vazio.

Quando o pedido vai contra o objetivo declarado, eu digo o porquê em duas linhas —
e entrego assim mesmo o que foi pedido, com a alternativa ao lado. A decisão é da pessoa.

## Como eu escrevo as peças

Frase curta. Verbo no começo. Um benefício concreto por parágrafo. Número só quando o
número existe e veio do contexto ou de uma fonte que eu abri nesta sessão.

## Meus limites

- Nada de promessa de resultado, urgência falsa ou depoimento que não me foi dado.
- Eu escrevo o arquivo; quem publica é a pessoa. Não disparo e-mail nem posto nada.
- Sem dado de mercado sem fonte. Na falta, escrevo "sem dado" e sigo.

Agora o que importa em cada campo do cabeçalho — é aqui que a maioria erra:

name é como você chama o agente. Minúsculo, sem espaço.

description é roteamento, não bio. Este é o campo que o agente principal lê para decidir se delega a tarefa para este agente aqui. Ele precisa dizer quando usar, com as palavras que a pessoa vai usar no pedido. "Especialista sênior em marketing digital com foco em growth" é uma bio e não roteia nada. A lista de tarefas concretas acima roteia. Se o seu agente "nunca é chamado", o problema quase sempre está nesta linha.

tools é menor privilégio. Você lista só o que ele precisa. O nosso lê, escreve, procura arquivo e consulta a web — e não recebe Bash, porque um agente que escreve texto não tem por que executar comando na sua máquina. Omitir o campo dá acesso a tudo; é o padrão cômodo e é o padrão errado.

model escolhe o motor. Tarefa de redação com regra clara vai bem em modelo intermediário; deixe o mais caro para quando você medir que precisa.

E o corpo? Repare que ele não tem uma linha sobre o que é marketing digital. O modelo já sabe. O corpo do agente serve para o que o modelo não tem como adivinhar: seu método, seu formato de saída, seu jeito de falar e o que ele deve recusar. Toda linha que ensina o modelo a fazer o trabalho dele é linha desperdiçada.

Um detalhe que muda o resultado mais do que parece: o item 3. "Termino com artefato" é o que transforma um conversador num executor. Sem uma regra explícita de que a tarefa termina em arquivo salvo, o comportamento padrão é despejar texto na tela e esperar você fazer o resto.

Passo 3 — a skill (.claude/skills/campanha-de-lancamento/SKILL.md)

Skill é procedimento guardado numa gaveta. Ela tem um cabeçalho pequeno, sempre visível, e um corpo que só entra no contexto quando o assunto aparece de verdade.

Isso resolve um problema real: você tem 15 procedimentos escritos e não cabe (nem convém) manter os 15 dentro do agente o tempo todo.

---
name: campanha-de-lancamento
description: Monta uma campanha de lançamento completa — calendário editorial, e-mails,
  anúncios e página de captura — a partir de um produto, uma data e um público.
  Use quando o pedido envolver lançar, relançar ou divulgar algo com data marcada.
---

# Campanha de lançamento

Campanha é um calendário com peças penduradas nele. O calendário vem primeiro; nenhuma
peça é escrita antes de existir data.

## A ordem

1. **Fixe as três datas:** abertura, fechamento e o envio de maior peso (véspera do fechamento).
2. **Monte o calendário** em `marketing/saida/<AAAA-MM-DD>-campanha-<produto>.md`, uma linha
   por peça: data, canal, formato, objetivo da peça, estado.
3. **Escreva as peças** na ordem do calendário, cada uma em seu próprio arquivo.
4. **Feche com a lista de publicação:** o que sobe em cada dia, por quem, e o que conferir antes.

## A régua de cada peça

- **E-mail** — 120 a 220 palavras, uma ideia, um link, assunto de até 45 caracteres.
- **Anúncio** — três variações, gancho na primeira linha, benefício, chamada.
- **Post de rede** — 80 a 150 palavras, abre pelo problema, fecha pela ação.
- **Página de captura** — uma tela, uma promessa, três provas, um formulário.

Limites de formato por canal estão em `referencias/canais.md`. Leia antes da primeira peça.

E o arquivo de referência que ela cita, em .claude/skills/campanha-de-lancamento/referencias/canais.md:

# Canais — limites e formatos

- **E-mail:** assunto até 45 caracteres, pré-cabeçalho até 90. Um link por e-mail.
- **Instagram:** legenda até 2.200 caracteres; as 125 primeiras aparecem antes do "mais".
  Carrossel de 5 a 8 cartões.
- **LinkedIn:** até 3.000 caracteres; o feed corta na terceira linha. Sem pilha de hashtag.
- **Reels / Shorts:** roteiro de 30 a 45 segundos, gancho nos 2 primeiros.
- **Google Search:** título até 30 caracteres por campo (3 campos), descrição até 90 (2 campos).
- **Página de captura:** um objetivo por página, um formulário, sem menu de navegação.

A regra de ouro da skill é a mesma da description do agente: o cabeçalho é o índice, o corpo é o conteúdo. Escreva a description com os verbos que a pessoa vai usar ("lançar", "divulgar", "relançar"), senão a gaveta nunca abre.

E repare que o corpo tem procedimento, não teoria. Ele diz em que ordem fazer, onde salvar e com que régua — coisas que só existem na sua casa. Nada ali explica o que é uma campanha.

Passo 4 — o comando (.claude/commands/campanha.md)

O comando é ergonomia humana. Ele existe para você não ter que reescrever o mesmo pedido de três parágrafos toda vez.

---
description: Monta uma campanha de lançamento com o agente de marketing
argument-hint: <produto> - <data de lançamento> - <público>
---

Use o agente `marketing` para montar a campanha de lançamento descrita abaixo.

PEDIDO: $ARGUMENTS

Antes de escrever qualquer peça:

1. Leia `CLAUDE.md` e o que houver em `marketing/publicado/` do mesmo canal.
2. Confirme produto, data e público. Faltando algum, pergunte os três de uma vez e siga.
3. Monte o calendário editorial primeiro. Peça nenhuma antes do calendário existir.

Entregue os arquivos em `marketing/saida/` e termine com a lista do que publicar em cada dia.

$ARGUMENTS é substituído pelo que você digitar depois do comando. argument-hint é o texto que aparece na sugestão enquanto você digita — cortesia com o seu eu de daqui a três meses.

Pense no comando como um script de shell: ele não tem inteligência nova, ele fixa uma sequência que você já sabe que funciona.

Passo 5 — rodar

Monte a pasta, abra e chame:

mkdir -p ferro-e-cia/marketing/saida ferro-e-cia/marketing/publicado
cd ferro-e-cia
# copie os cinco arquivos deste post para cá, respeitando a árvore
claude

Aí, dentro da sessão, os dois jeitos de acionar:

/campanha kit iniciante de entalhe - lançamento em 15/09 - marceneiros de fim de semana

ou, em linguagem natural, sem comando nenhum:

Use o agente marketing para escrever três variações de anúncio do kit de entalhe
para o Google Search.

O primeiro pedido dispara a skill (tem "lançamento" e data). O segundo não precisa dela: é peça avulsa.

Como saber se funcionou. Não é pela resposta bonita na tela — é pelo disco:

ls marketing/saida/
# 2026-08-17-campanha-kit-entalhe.md
# 2026-08-17-email-abertura.md
# 2026-08-17-anuncio-search.md

Se apareceu arquivo, o agente executou. Se não apareceu, ele conversou — e a regra do "termino com artefato" precisa ficar mais explícita no arquivo dele.

O que quebra na prática

Cinco coisas que eu vi darem errado, em ordem de frequência:

O agente nunca é chamado. É sempre a description. Reescreva-a começando por "Use quando…" e coloque as palavras do pedido real dentro dela.

A skill nunca abre. Mesma causa, mesmo remédio, no cabeçalho da skill.

Ele responde em vez de entregar. Falta a regra do artefato, ou ela está no meio de um parágrafo. Regra de saída merece item numerado e verbo no imperativo.

Ele inventa número. "78% dos consumidores preferem…" sai lindo e é ficção. Por isso o limite explícito no arquivo do agente. Mesmo assim, confira todo número antes de publicar — essa é a parte que continua sendo sua.

Ele fica genérico. Quase sempre é CLAUDE.md vago. Lixo entra, lixo sai: o agente não conhece o seu público, ele repete com fluência o que você escreveu sobre ele.

O que este agente não faz

Sendo honesto, porque a internet anda cheia de promessa: este agente escreve peça, e escrever peça é a parte barata do marketing.

Ele não sabe se a sua oferta é boa. Não mede resultado — quem lê o painel é você. Não sabe o que o seu cliente respondeu no WhatsApp semana passada, a menos que você conte. E não substitui a decisão de para quem vender e por quanto, que é onde as campanhas realmente se ganham ou se perdem.

O que ele faz é tirar de você as quatro horas de digitação que separam a decisão da publicação. Na minha semana, isso é bastante.

Na segunda-feira de manhã

1. Crie a pasta e copie os cinco arquivos. Vinte minutos, sem escrever uma linha de código.
2. Reescreva o CLAUDE.md com o seu negócio de verdade — principalmente a lista do que vocês não fazem.
3. Peça a coisa mais chata que você faz toda semana. Não o lançamento do ano; a peça repetitiva.
4. Olhe o arquivo que saiu e corrija o agente, não a peça. Toda correção que você faria de novo vira uma linha no .claude/agents/marketing.md. É assim que ele fica seu.

Um agente não nasce pronto: ele fica bom no terceiro ajuste, e o ajuste mora num arquivo de texto que você versiona igual a qualquer outro. Essa é a boa notícia inteira — não é mágica, é repositório.