Plugin para Claude Code que diagnostica campañas de Meta (Facebook & Instagram Ads) aplicando la metodología de las 3 Q's y un sistema de benchmarks semáforo 🔴 🟡 🟢.
3 Q's conecta Claude Code con la Meta Marketing API y convierte los datos brutos de tus campañas en un diagnóstico accionable en 3 pasos:
1️⃣ ¿Qué pasó? → Resultados principales vs tu objetivo de negocio 2️⃣ ¿Por qué pasó? → Diagnóstico del embudo y calidad creativa 3️⃣ ¿Qué haremos? → Optimizaciones concretas priorizadas
No tienes que editar archivos, exportar variables ni pegar JSON. Pegas tu Access Token una vez y Claude conduce la conversación:
Access Token → Negocios → Campañas → Tipo → Análisis → [Conjuntos → Anuncios]
Cada métrica se evalúa contra umbrales verde / amarillo / rojo:
| 🔴 Deficiente | 🟡 Aceptable | 🟢 Óptimo |
|---|---|---|
| Acción urgente | Revisar y optimizar | Mantener / escalar |
Los benchmarks se adaptan automáticamente al tipo de campaña y al objetivo de negocio que declaras (ROAS, CPL o costo por conversación).
| Tipo | Métrica clave | Benchmarks principales |
|---|---|---|
| 🛒 Ventas | ROAS | Embudo completo: Impresiones → Clics → Landing → Checkout → Compra |
| 💬 Interacción / WhatsApp | Costo por conversación | Tasa conversión a mensajes, CTR único |
| 📋 Clientes Potenciales — Formularios | CPL | Tasa conversión del formulario instantáneo |
| 🌐 Clientes Potenciales — Sitio web | CPL | Tasa conversión landing + velocidad |
| 🏪 Reconocimiento / Tiendas físicas | Alcance / CPM | Frecuencia, calidad del creativo |
Todas las tablas incluyen además: % video 3s, tiempo promedio de reproducción, frecuencia, CPM y métricas de calidad de Meta.
Métricas principales comparadas contra tu objetivo (no benchmarks genéricos). Ejemplo:
"ROAS 2.1x vs objetivo 4x → 47% por debajo 🔴"
Se recorre el embudo paso por paso para encontrar el eslabón débil:
Impresiones → Clics salientes → Visitas p.d. → Ver contenido → Carrito → Checkout → Compra
▲
└── El % más bajo revela dónde se pierde la audiencia
Recomendaciones priorizadas por impacto, siempre aplicando las reglas del Efecto Desglose antes de pausar o escalar (nunca matar anuncios que Meta está preservando por aprendizaje).
- Claude Code instalado
- Python 3.7+
- Token de Meta con permisos de solo lectura:
ads_read+business_management
Opción A — Plugin (recomendado, funciona en CLI y VS Code)
Dentro de Claude Code:
/plugin marketplace add felipeverce/3Qs
/plugin install 3qs@3qsO vía UI: /plugin → Discover → 3qs → Install.
La extensión de VS Code solo admite instalación vía plugin.
Opción B — Skill personal (solo CLI)
cp -r skills/3qs ~/.claude/skills/- Abre Claude Code con el plugin activo.
- Escribe algo como "Analiza mis campañas de Meta del último mes".
- Pega tu Access Token una sola vez.
- Claude hace el resto: escribe
.env, ejecuta los scripts, lee los JSON y te presenta el diagnóstico.
3Qs/
├── .claude-plugin/
│ ├── plugin.json → Manifiesto del plugin
│ └── marketplace.json → Manifiesto del marketplace
├── skills/
│ └── 3qs/
│ └── SKILL.md → Lógica y metodología
├── scripts/
│ ├── _common.py → Config, helpers, paginación, retry
│ ├── fetch_businesses.py → Paso 1: negocios y cuentas
│ ├── fetch_campaigns.py → Paso 2: campañas
│ ├── fetch_insights.py → Paso 3: métricas
│ ├── fetch_adsets.py → Conjuntos de anuncios
│ └── fetch_ads.py → Anuncios individuales
└── assets/
└── banner.svg
- Entra a https://developers.facebook.com/apps/
- Crear app → nombre → caso de uso: Crear y administrar anuncios + Medir rendimiento con la API de Marketing.
- Selecciona tu portafolio comercial y crea la app.
- Herramientas → Explorador de API Graph → selecciona tu app.
- Generar token de acceso con SOLO:
ads_read+business_management.
Para uso continuo, crea un System User Token en Business Manager → Configuración → Usuarios del sistema. No expiran.
La metodología de las 3 Q's (¿Qué pasó? / ¿Por qué pasó? / ¿Qué haremos?) está basada en el trabajo de Felipe Vergara.
MIT © Felipe Vergara
Hecho con 💙 para la comunidad hispana de performance marketing.