RiLiGar Marketing Ads Meta

Skill completa para gestao de Meta Ads via SDK oficial (facebook-business). Substitui o MCP fb-ads-mcp-server com mais poder: duplicacao de campanhas/ads, swap de url_tags, e acesso total a API.

Setup (primeira vez)

Quando o usuario pedir para configurar, rodar setup, ou for a primeira vez usando a skill, o Claude deve guiar o setup interativo.

IMPORTANTE: Ler references/setup-meta-app.md ANTES de comecar o setup. Esse arquivo contem o passo a passo completo para criar o app no Meta Developer Dashboard, gerar o token e resolver problemas. Se o aluno mandar prints ou tiver duvidas sobre alguma tela do Facebook, consultar esse arquivo para orientar.

1. Verificar dependencias

python3 ~/.claude/skills/riligar-marketing-ads-meta/scripts/setup.py

2. Verificar .env

Checar se existe ~/.claude/skills/riligar-marketing-ads-meta/.env. Se NAO existir, criar com o template:

# RiLiGar Marketing Ads Meta — Configuracao
# Os scripts leem este arquivo automaticamente. NAO precisa adicionar ao ~/.zshrc.

# OBRIGATORIO: Token de acesso da Meta (gerar em developers.facebook.com > Graph API Explorer)
META_ADS_TOKEN=""

# OBRIGATORIO: App ID do app Meta que gerou o token (ver em developers.facebook.com > My Apps)
META_APP_ID=""

# OPCIONAL: Conta de anuncio padrao (evita ter que passar --account toda vez)
META_AD_ACCOUNT_ID=""

Depois de criar, orientar o usuario a:

1. Preencher o META_ADS_TOKEN (token de acesso)
2. Preencher o META_APP_ID (ID do app Meta — ex: 905545132380980)

IMPORTANTE: Os scripts leem o .env automaticamente. NAO precisa fazer source no ~/.zshrc. O token fica isolado dentro da skill e nao vaza pra outras sessoes do terminal.

IMPORTANTE: O app Meta DEVE estar em modo Live (nao Development) para criar dark posts e criativos via API. Se der erro "app em modo de desenvolvimento", orientar o usuario a mudar o app para modo Live no painel developers.facebook.com. Alem disso, as paginas do Facebook que serao usadas nos anuncios devem estar vinculadas/autorizadas no app.

3. Cadastro de contas (contas.yaml) — SETUP CONVERSACIONAL

Depois que o .env estiver preenchido e o setup.py passar, o Claude DEVE proativamente guiar o cadastro de contas:

1. Rodar read.py accounts para listar todas as contas disponiveis
2. Perguntar ao usuario: "Qual a tua principal conta de anuncio? Me passa o nome do cliente, e eu preencho o contas.yaml pra ti."
3. Para cada cliente, perguntar (ou buscar na API se possivel):

• Nome do cliente
• Conta de anuncio (act_XXX) — pode escolher da lista
• Page ID do Facebook
• Instagram ID e @username

1. Preencher o contas.yaml automaticamente com as respostas
2. Perguntar: "Quer cadastrar mais algum cliente?"

Esse fluxo conversacional e o jeito ideal de configurar — o usuario so responde as perguntas e o Claude preenche tudo.

Cadastro de clientes (contas.yaml)

Arquivo: ~/.claude/skills/riligar-marketing-ads-meta/contas.yaml

Antes de executar qualquer operacao, o Claude DEVE ler este arquivo para resolver nomes de clientes para IDs. Quando o usuario disser "cria campanha pra DobraLabs" ou "insights do Ronnau", consultar o contas.yaml para obter conta_anuncio, pagina_facebook e instagram_id do cliente.

Se o cliente nao estiver cadastrado, perguntar os dados e oferecer para adicionar ao arquivo.

Como usar

Todos os scripts estao em ~/.claude/skills/riligar-marketing-ads-meta/scripts/. O padrao e:

python3 <script>.py <subcomando> [argumentos]

O Claude deve interpretar o pedido do usuario e executar o script correto via Bash.

Referencia rapida de operacoes

Leitura (read.py)

Insights (insights.py)

Parametros de insights:

Targeting (targeting.py)

Criacao (create.py)

IMPORTANTE: Todas as criacoes sao feitas com status PAUSED. Revisar antes de ativar.

Edicao (update.py)

Exclusao (delete.py)

Avancado (advanced.py) -- NOVIDADES

O swap-url-tags resolve o problema de nao poder editar url_tags em criativos existentes: cria um criativo novo identico com os url_tags corretos e troca no ad.

O --deep no duplicate-campaign duplica tambem todos os ad sets e ads da campanha.

Aprendizados (memória persistente)

Arquivo: aprendizados.md (na raiz da skill, ~/.claude/skills/riligar-marketing-ads-meta/aprendizados.md)

O Claude DEVE:

1. Ler `aprendizados.md` no início de QUALQUER operação de criação (campanha, ad set, criativo, ad). Aplicar todas as regras listadas.

1. Quando o usuário corrigir algo (ex: "faltou o CTA", "tinha que ser carrossel", "botão errado"), o Claude DEVE perguntar:

"Quer que eu registre isso nos aprendizados pra não esquecer nas próximas vezes?"

1. Quando o usuário pedir explicitamente ("lembra disso", "registra isso", "anota pra próxima"), registrar imediatamente.

1. Formato de cada entrada no aprendizados.md:

   ### {DATA} — {título curto}
   **Regra:** {o que fazer sempre/nunca}
   **Contexto:** {o que aconteceu pra gerar esse aprendizado}

1. Não duplicar — antes de adicionar, verificar se já existe regra similar.

Exemplo de aprendizados.md:

# Aprendizados — RiLiGar Marketing Ads Meta

### 2026-04-03 — Sempre incluir CTA no criativo
**Regra:** Ao criar criativos (create.py creative), SEMPRE incluir call_to_action_type. Padrão: LEARN_MORE pra tráfego, SIGN_UP pra leads, SHOP_NOW pra vendas.
**Contexto:** Criou carrossel sem botão de CTA. Usuário teve que corrigir manualmente.

### 2026-04-03 — Carrossel Instagram: multi_share_end_card=false
**Regra:** Em campanhas de visita ao perfil Instagram, SEMPRE usar multi_share_end_card=false e multi_share_optimized=false.
**Contexto:** Cartão "Ver mais" sem URL quebrou o anúncio em 10 posicionamentos.

Regras de seguranca

O Claude DEVE seguir estas regras ao executar operacoes:

1. Criar sempre PAUSED -- nunca criar objetos com status ACTIVE diretamente
2. Confirmar antes de deletar -- perguntar ao usuario antes de executar delete
3. Confirmar antes de ativar -- perguntar antes de mudar status para ACTIVE
4. Ativar TODOS os niveis -- ao ativar uma campanha, SEMPRE ativar tambem todos os ad sets e ads dentro dela. Nunca ativar so a campanha e esquecer os niveis abaixo. Ordem: campaign → adsets → ads
5. Respeitar rate limits -- o SDK ja inclui delays entre operacoes de escrita (1s). Se receber erro de rate limit (codigos 17, 32, 80004), aguardar 60 segundos antes de tentar novamente
6. Orcamento com cuidado -- ao alterar daily_budget ou lifetime_budget, confirmar o valor com o usuario. Valores sao em centavos (5000 = R$50,00)
7. Nunca hardcodar tokens -- sempre usar a env var META_ADS_TOKEN
8. Nunca assumir origem de dados -- ao mostrar insights no nivel da conta, SEMPRE quebrar por campanha antes de atribuir resultados a uma campanha especifica. Nunca dizer "esse gasto e da campanha X" sem ter confirmado com insights por campanha

Padroes de campanha (CRITICO)

Arquivo: references/padroes-campanha.md

O Claude DEVE ler este arquivo ANTES de criar qualquer campanha. Ele contem regras aprendidas por tipo de campanha que evitam erros comuns (ex: carrossel sem preview, ads bloqueados em posicionamentos, etc).

Se o tipo de campanha nao estiver documentado, o Claude DEVE primeiro buscar uma campanha similar ja existente na conta e usar como template (ver fluxo abaixo).

Fluxos comuns

Criar campanha completa

Passo 0 — Diagnostico (OBRIGATORIO antes de criar)

1. Ler references/padroes-campanha.md para o tipo de campanha desejado
2. Buscar campanhas similares ja existentes na conta:

   read.py campaigns --account act_XXX --status ACTIVE
   read.py ads-by-campaign --campaign XXX
   read.py creative --id XXX

1. Extrair padroes: destination_type, promoted_object, optimization_goal,

instagram_user_id, multi_share_end_card, degrees_of_freedom_spec, etc.

1. Usar como base para a nova campanha

Passo 1-5 — Criacao

1. create.py campaign -- cria campanha PAUSED
2. create.py adset -- cria ad set PAUSED com targeting
3. create.py image ou create.py video -- sobe midia
4. create.py creative -- cria criativo com url_tags e instagram_user_id
5. create.py ad -- cria ad PAUSED com degrees_of_freedom_spec

Passo 6 — Validacao (OBRIGATORIO apos criar)

1. Ler o ad criado: read.py ad --id XXX
2. Checar preview: read.py preview --creative XXX --format all
3. Se houver problemas, corrigir ANTES de reportar sucesso

Passo 7 — Ativacao Ativar TODOS os niveis (campanha + ad sets + ads):

• update.py campaign --id XXX --status ACTIVE
• update.py adset --id XXX --status ACTIVE
• update.py ad --id XXX --status ACTIVE

Corrigir url_tags de ads existentes

IMPORTANTE: Criativos na Meta sao imutaveis. Nao da pra editar url_tags, URL de destino, imagem ou texto de um criativo existente via API. Isso vale especialmente pra criativos baseados em posts organicos (effective_object_story_id) -- a URL vem do post original e nao pode ser alterada.

O fluxo correto e duplicar o ad com criativo novo:

1. read.py ads-by-campaign --campaign XXX -- listar ads
2. read.py creatives-by-ad --ad XXX -- ver criativo atual e url_tags
3. Criar novo criativo usando o object_story_id do original + url_tags corretos
4. Criar novo ad PAUSED no mesmo ad set com o criativo novo
5. Ativar o novo ad
6. Pausar o ad antigo

Pra criativos de post organico, usar a API direta:

# Criar criativo com url_tags corretos reusando o post original
POST act_XXX/adcreatives
  name: "nome [url_tags_fix]"
  object_story_id: "PAGE_ID_POST_ID"  (do effective_object_story_id do criativo antigo)
  url_tags: "utm_source=facebook&utm_medium=cpc&utm_campaign=NOME_CAMPANHA"

# Criar novo ad PAUSED
POST act_XXX/ads
  name: "nome [url_tags_fix]"
  adset_id: MESMO_ADSET
  creative: {"creative_id": "NOVO_ID"}
  status: PAUSED
  tracking_specs: (copiar do ad original)

# Ativar novo, pausar antigo
POST novo_ad_id  status=ACTIVE
POST antigo_ad_id  status=PAUSED

Duplicar campanha para teste A/B

1. advanced.py duplicate-campaign --id XXX --deep -- copia tudo
2. update.py adset --id NOVO_ADSET --targeting '{...}' -- alterar targeting
3. update.py campaign --id NOVA_CAMPANHA --name "Teste B" -- renomear
4. Ativar quando pronto

Puxar relatorio de performance

1. insights.py campaign --id XXX --date-preset last_30d --breakdowns age,gender
2. Ou para relatorio pesado: insights.py async --id act_XXX --date-preset maximum --level ad