✨ ¿Qué hace?
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]
🚦 Sistema de benchmarks semáforo
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).
🎯 Tipos de campaña soportados
| 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.
🧠 Metodología 3 Q's
1️⃣ ¿Qué pasó?
Métricas principales comparadas contra tu objetivo (no benchmarks genéricos). Ejemplo:
"ROAS 2.1x vs objetivo 4x → 47% por debajo 🔴"
2️⃣ ¿Por qué pasó?
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
3️⃣ ¿Qué haremos?
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).
⚡ Inicio rápido
Requisitos
- Claude Code instalado
- Python 3.7+
- Token de Meta con permisos de solo lectura:
ads_read + business_management
🔌 Instalación
Opción A — Plugin (recomendado, funciona en CLI y VS Code)
Dentro de Claude Code:
/plugin marketplace add felipeverce/3Qs
/plugin install 3qs@3qs
O 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/
▶️ Uso
- 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.
📁 Estructura del proyecto
