Riligar marketing ads

RiLiGar Marketing Ads

Camada de inteligência para gestão de tráfego pago. Diagnostica contas, gera relatórios visuais, audita campanhas e aplica Quality Gates com benchmarks do mercado brasileiro.

Não executa ações na API diretamente — delega para skills de execução:

• Meta Ads: skill riligar-marketing-ads-meta (SDK oficial facebook-business)
• Google Ads: skill riligar-marketing-ads-google (SDK oficial google-ads)
• Google Analytics: skill riligar-marketing-analytics-ga4 (GA4 Data API)

Se a skill de execução não estiver instalada, orientar o usuário a instalar.

Setup

Na primeira vez, rodar:

/riligar-marketing-ads setup

O setup:

1. Detecta se o RiLiGar OS está instalado (lê _contexto/empresa.md se existir)
2. Verifica quais skills de execução estão disponíveis (riligar-marketing-ads-meta, riligar-marketing-ads-google, riligar-marketing-analytics-ga4)
3. Cadastra contas do cliente no contas.yaml
4. Testa conexões

Comandos

Comando	O que faz	Quando usar
/riligar-marketing-ads setup	Configura contas e testa conexões	Primeira vez
/riligar-marketing-ads diagnostico	Health Score + KPIs + alertas automáticos	Check diário (5 min)
/riligar-marketing-ads relatorio	Dashboard HTML com benchmarks BR	Entrega pro cliente (semanal/mensal)
/riligar-marketing-ads auditoria	Análise profunda com Quality Gates	Revisão mensal
/riligar-marketing-ads historico	Registra e consulta otimizações e hipóteses	Após cada ação

Cadastro de contas (contas.yaml)

Arquivo: contas.yaml (na raiz da skill)

Antes de executar qualquer comando, o Claude DEVE ler este arquivo para resolver nomes de clientes para IDs de conta.

Se não houver contas cadastradas, guiar o setup.

Referências (carregar sob demanda)

Arquivo	Quando carregar
references/benchmarks-br.md	Diagnóstico, relatório e auditoria
references/quality-gates.md	Auditoria e diagnóstico

O Claude DEVE ler o arquivo de referência relevante ANTES de executar o comando.

Aprendizados (memória persistente)

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

O Claude DEVE:

1. Ler aprendizados.md no início de QUALQUER comando (diagnóstico, relatório, auditoria)
2. Quando o usuário corrigir algo, perguntar: "Quer que eu registre isso nos aprendizados pra não esquecer nas próximas vezes?"
3. Quando o usuário pedir ("lembra disso", "registra", "anota"), registrar imediatamente
4. Ser proativo: se o usuário pedir pra refazer ou ajustar algo que já foi gerado, perguntar se quer registrar a correção
5. Não duplicar — verificar se já existe regra similar antes de adicionar

Cada skill de execução (riligar-marketing-ads-meta, riligar-marketing-ads-google, riligar-marketing-analytics-ga4) tem seu próprio aprendizados.md pra regras específicas da plataforma. O do riligar-marketing-ads é pra regras gerais (formato de relatório, preferências de visualização, etc).

Regras gerais

1. NUNCA usar MCPs: toda execução DEVE ser via scripts Python das skills RiLiGar (riligar-marketing-ads-meta, riligar-marketing-ads-google, riligar-marketing-analytics-ga4). Nunca usar fb-ads-mcp-server, adloop ou qualquer outro MCP de terceiro. Isso garante consistência e independência.
2. Benchmarks BR: sempre usar benchmarks do mercado brasileiro (não americano)
3. Terminologia PT-BR: nunca usar termos em inglês no output (spend → gasto, reach → alcance, etc)
4. Números sempre: alertas e recomendações devem ter números específicos, nunca vagos
5. Comparativo: sempre comparar com período anterior quando possível
6. Priorizar: ordenar alertas e recomendações por impacto financeiro (maior economia primeiro)

Detecção do Python correto (OBRIGATÓRIO)

Antes de rodar qualquer script, detectar qual python3 tem os SDKs instalados. Rodar UMA VEZ no início da sessão e reutilizar o caminho:

# Detectar Python com facebook-business (Meta Ads)
PYTHON=$(python3 -c "import facebook_business; print('OK')" 2>/dev/null && echo "python3" || \
  (/opt/homebrew/bin/python3 -c "import facebook_business; print('OK')" 2>/dev/null && echo "/opt/homebrew/bin/python3") || \
  echo "NONE")

Se NONE: orientar o usuário a instalar o SDK (pip3 install facebook-business).

Depois de detectar, SEMPRE usar esse Python pra todos os scripts da sessão:

$PYTHON ~/.claude/skills/riligar-marketing-ads-meta/scripts/read.py accounts

Por que isso é necessário: no Mac existem dois Pythons (system e Homebrew). Os SDKs ficam no Homebrew (/opt/homebrew/bin/python3) mas o python3 do PATH pode ser o system (que não tem os pacotes). Detectar uma vez evita erros.

Detecção de skills de execução

Antes de executar, verificar quais skills estão disponíveis:

# Meta Ads
ls ~/.claude/skills/riligar-marketing-ads-meta/SKILL.md 2>/dev/null && echo "META_OK"

# Google Ads
ls ~/.claude/skills/riligar-marketing-ads-google/SKILL.md 2>/dev/null && echo "GOOGLE_OK"

# GA4
ls ~/.claude/skills/riligar-marketing-analytics-ga4/SKILL.md 2>/dev/null && echo "GA4_OK"

Se nenhuma skill estiver instalada, orientar:

• Meta Ads: git clone https://github.com/duduesh/riligar-marketing-ads-meta ~/.claude/skills/riligar-marketing-ads-meta
• Google Ads: (em breve)
• GA4: (em breve)

Tabela de terminologia PT-BR

Inglês	Português
spend	gasto
reach	alcance
impressions	impressões
clicks	cliques
conversions	conversões
cost per lead	custo por lead (CPL)
click-through rate	taxa de cliques (CTR)
cost per click	custo por clique (CPC)
cost per mille	custo por mil (CPM)
frequency	frequência
return on ad spend	retorno sobre investimento (ROAS)
budget	orçamento
ad set	conjunto de anúncios
ad creative	criativo
landing page	página de destino
conversion rate	taxa de conversão
quality score	índice de qualidade
search terms	termos de busca
negative keywords	palavras-chave negativas
audience	público
placement	posicionamento
daily budget	orçamento diário
lifetime budget	orçamento vitalício