ads-agent

ads-agent

Mundo para auditar y planificar cuentas de publicidad de pago.

Ver CLAUDE.md para contexto completo y TASKS.md para el backlog.

Claude Ads — skill instalada a nivel de proyecto

.claude/: 1 skill orquestador (ads) + 33 sub-skills + 25 agentes + 38 referencias + 12 templates de industria. Copiado desde el bundle original (repo claude-ads, instalado antes vía WSL global) — la instalación global fue borrada, esta es la única fuente ahora.

Qué hace

Sistema de operaciones de paid media “source-grounded” — cada claim (benchmark, política de plataforma, umbral) exige fuente fechada y nivel de confianza; nunca inventa contexto de cuenta faltante, pide input o marca el resultado como provisional.

12 plataformas de primera clase: Google Ads, Meta Ads, YouTube Ads, LinkedIn Ads, TikTok Ads, Microsoft Advertising, Apple Ads, Amazon Ads, Reddit Ads, Pinterest Ads, Snapchat Ads, X Ads.

Comandos (/ads <subcomando>)

Comando	Qué hace
/ads setup	Onboarding de cliente/marca/cuenta, guardrails, credenciales, instalación
/ads audit [all|<plataforma>|<scope>]	Auditoría completa o acotada (cuenta, plataforma, o scope como attribution, tracking, creative, landing)
/ads plan	Plan de campaña, canal, presupuesto, competidor o medición
/ads create	Producción de copy, imagen, video o foto de producto
/ads launch [--draft|--apply]	Draft o ejecución de lanzamiento de campaña
/ads monitor	Pacing, performance, fatiga creativa, tracking, compliance de política
/ads optimize [--draft|--apply]	Draft o ejecución de optimizaciones
/ads experiment	Hipótesis, cálculo de poder estadístico, duración, setup, readout
/ads report	Renderiza un run previo
/ads research refresh	Refresca conocimiento de plataforma + evidencia
/ads validate	Valida integridad del repo/run; también uninstall seguro
/ads status / /ads next	Madurez del sistema, capacidades, próximo bloqueante

Atajos directos (mismo routing): /ads google\|meta\|youtube\|linkedin\|tiktok\|microsoft\|apple\|amazon\|reddit\|pinterest\|snapchat\|x (audit por plataforma), /ads budget\|competitor\|math (plan/modelo financiero), /ads test (experiment), /ads dna (setup), /ads generate//ads photoshoot (create).

Cambios en cuenta real: siempre con gate

--draft (default implícito) nunca toca la cuenta — solo --apply ejecuta, y solo si pasa el “mutation gate” completo (autoridad de cuenta confirmada, draft revisado, rollback documentado). Todo run deja manifest único + artefactos verificables por herramienta, no solo afirmación de texto.

Agentes especializados (.claude/agents/)

17 audit-<plataforma>.md (uno por cada una de las 12 plataformas + audit-budget, audit-creative, audit-policy-compliance, audit-regulatory-compliance, audit-tracking) + 8 de soporte: copy-writer, creative-strategist, format-adapter, release-verifier, research-worker (slice acotado de fuentes/licencias), skill-reviewer (revisión de routing/safety con contexto fresco), source-verifier, visual-designer.

Templates de industria (ads-plan/assets/)

agency.md, b2b-enterprise.md, ecommerce.md, ecommerce-creative.md, finance.md, generic.md, healthcare.md, info-products.md, local-service.md, mobile-app.md, real-estate.md, saas.md.

CLI Python (ads/scripts/)

Paquete claude_ads_core (adapters, contracts, control_registry, models, orchestration, reporting, scoring, schemas, workflow_contracts) + scripts sueltos: analyze_landing.py, build_control_registry.py, capture_screenshot.py, fetch_page.py, generate_image.py (usa agents/openai.yaml como config de proveedor de imágenes), generate_report.py, release.py, review_evidence.py, verify_managed_install.py, verify_target_lock.py, write_install_receipt.py. Requiere pip install -r ads/scripts/requirements.txt — .venv no se copió (era Linux/WSL, 368M de binarios no portables a Windows).

/ads-run-on <world> [landing|dna] — auditar OTRO world sin instalar Claude Ads ahí

Comando propio (_shared/commands/ads-run-on.md, symlink activo en .claude/commands/), paralelo a /seo-run-on de seo-agent. Toma la production_url de otro world (registry.json) y corre /ads landing o /ads dna contra esa URL en vivo — nunca lee código local del world destino, mismo guard SSRF que ya trae ads-landing/ads-dna (bloquea IP privada/loopback/link-local/metadata).

/ads-run-on cnm-cigars landing   # CRO / message-match del homepage
/ads-run-on lippia-alba dna      # perfil de marca público (voz, tokens visuales, oferta)
/ads-run-on melloeat landing https://melloeat.com/promo-verano   # URL explícita, no el homepage

Reportes en ads-agent/reports/<world>-<subcomando>-<fecha>/.

¿Necesito configurar algo externo?

Por defecto NO — /ads audit\|plan\|report\|research corren solo con datos que pegás (exports, capturas) o production_url de otro world vía /ads-run-on. Nada de esto pide API key.

Solo hace falta configurar algo externo si querés estas 3 cosas puntuales:

Necesitás…	Configurar	Notas
/ads create//ads generate//ads photoshoot (generar imagen real, no solo brief)	Proveedor de imagen a tu elección (OpenAI, etc.) + vars ADS_IMAGE_PROVIDER/ADS_IMAGE_MODEL	Skill no trae proveedor default — sin credencial devuelve brief + needs_input, nunca inventa que generó el archivo. Ver ads/references/image-providers.md
Leer/escribir cuenta real de ads en vivo (en vez de exports pegados)	MCP por plataforma: Google Ads (google-ads-mcp-official), Amazon Ads (beta), TikTok Ads, Microsoft Advertising (waitlist). Meta/LinkedIn: MCP comercial (Adspirer, GrowthSpree/Adzviser) — no first-party	claude mcp add --scope user, documentar en _shared/docs/mcps.md. Cualquier --apply (no --draft) exige además pasar el mutation gate completo. Ver ads/references/mcp-integration.md y regla 4 de CLAUDE.md
Captura de landing page real (/ads landing, screenshots)	Playwright browser payload instalado localmente	Opcional — sin esto, análisis de landing sigue funcionando vía fetch de HTML, solo sin screenshot
Exportar reporte a PDF (/ads report)	WeasyPrint + Pango (libs de sistema)	Opcional — sin esto, reporte sigue en Markdown/HTML

Credenciales de cualquiera de estas integraciones: env var, OS keychain o secret manager — nunca en el repo, perfiles, reportes ni logs (regla dura del proyecto original, no solo sugerencia).

Evidencia y fuentes

Jerarquía: (1) material oficial de plataforma/API/regulador, (2) exports propios de cuenta + datos de experimento controlado, (3) evidencia de practicante fechada con metodología, (4) issues/PRs/repos comunitarios tras revisión de licencia. Cada finding lleva evidence_based/practitioner/ contested/folklore + confianza high/medium/low/none. Fuente vencida (refresh_due expirado) bloquea cualquier claim “release-current” hasta reverificar.