juanesal-lab/mapa-calor

O que mapa-calor faz?

Dos diagnósticos que se complementan:

Parte	Pregunta que responde	Fuente	Script
Videos	¿En qué segundo se va la gente de mi anuncio?	Meta Graph API (solo GET)	scripts/retencion_videos.py
Landings	¿La gente baja, lee y toca, o se va arriba?	Microsoft Clarity Data Export API	scripts/landing_clarity.py
Conexión	¿Está todo conectado?	las dos	scripts/conexion.py

Los scripts están en la carpeta scripts/ dentro de la carpeta de esta skill (Claude Code la muestra como "Base directory for this skill"; normalmente ~/.claude/skills/mapa-calor). En los comandos de abajo, $SK es esa carpeta. Usa python3 (o python en Windows).

Qué hacer según lo que pidan

• /mapa-calor sin nada, o la primera vez → corre conexion y luego pregunta si quiere videos, landing o todo.
• /mapa-calor conexion → python3 "$SK/scripts/conexion.py". Si falta algo, guía paso a paso con el README (sección «Conectar Meta» / «Conectar Clarity»). Si no sabe su act_: python3 "$SK/scripts/conexion.py" --cuentas.
• /mapa-calor videos → python3 "$SK/scripts/retencion_videos.py" (últimos 7 días, anuncios activos). Opciones: --periodo last_14d, --desde AAAA-MM-DD --hasta AAAA-MM-DD, --todos (incluye apagados), --png mapa.png, --video archivo.mp4 (hoja de los primeros 4 s, un cuadro cada 0,5 s).
• /mapa-calor landing → python3 "$SK/scripts/landing_clarity.py". Opciones: --url /products/x, --meta (cruza con CTR de enlace y carritos de Meta), --solo-cache, --cuota.
• /mapa-calor todo → primero videos, después landing con --meta, y cierra con un diagnóstico conjunto.
• Sin conexión o para practicar → cualquiera de los dos con --entrada <archivo.json> (hay ejemplos inventados en ejemplos/ del repositorio).

Cómo interpretar (dilo en palabras simples, con el número al lado)

Videos

1. Mira la columna 3s del mapa: es el % que sigue viendo a los 3 segundos.
   • < 25 % → el gancho falla. Recomendación concreta: rehacer los primeros 2,5 s.
   • 25–39 % → regular. Probar una versión con el producto en el primer cuadro.
   • ≥ 40 % → el gancho funciona; buscar la siguiente fuga (el script la marca: «pasado el gancho…»).
2. El producto (o el problema que resuelve) debe aparecer antes del segundo 2,5. Los videos que lo muestran en el segundo 0 retienen más. Si el usuario tiene el archivo del video, sugiere --video y mira la hoja de cuadros (léela con la herramienta de imágenes) para decir qué se ve justo donde se cae la gente.
3. Caer mucho del segundo 0 al 1 es normal en el feed: compara los videos entre sí, no contra el 100 %.
4. Menos de 100 impresiones → no concluir. Dilo claro y no recomiendes apagar ni escalar ese video.
5. Une retención con ventas: buen gancho + 0 compras → el freno puede ser la landing (sugiere /mapa-calor landing).

Landings

• pierde_arriba (scroll medio < 21 %) → arreglar la primera pantalla: titular claro, foto del producto en uso, beneficio y precio visibles sin bajar. Si además el CTR de enlace es ≥ 1,5 %, el anuncio sí trae gente: el freno es la página.
• friccion (rabia > 5 %, muertos > 20 % o quickback > 25 %) → abrir el mapa de calor VISUAL en Clarity (el enlace sale en el informe) y buscar lo que tocan y no responde.
• retiene / oferta_precio (scroll ≥ 30 % pero < 4 carritos por cada 100 vistas) → el problema es oferta o precio.
• creativo (página bien, CTR < 1,5 %) → cambiar el gancho del anuncio, no la página.
• muestra_chica (< 30 visitas) → no concluir.
• La imagen del mapa de calor (dónde tocan, hasta dónde bajan) solo se ve en el panel de Clarity → Heatmaps. La skill da los números y el enlace; no inventes lo que muestra la imagen.

Termina siempre con 3 acciones concretas como máximo, ordenadas por impacto, y di qué medir después («en 3 días vuelve a correr /mapa-calor videos y mira si la columna 3s subió»).

Reglas que no se rompen

• Nunca imprimas, copies ni guardes un token. No hagas echo $META_TOKEN, no leas el .env en voz alta, no pegues tokens en archivos del repositorio. Si el usuario pega un token en el chat, dile que lo guarde en el Llavero o en ~/.mapa-calor/.env y que, por seguridad, lo regenere más adelante.
• Solo lectura. Esta skill nunca crea, pausa ni edita anuncios. Si piden cambiar algo en Meta, explica qué hacer en el Administrador de anuncios; no lo hagas tú.
• Cuida la cuota de Clarity (10 llamadas/día por proyecto). El script ya guarda caché (3 h) y se frena en 8. No uses --forzar salvo que el usuario lo pida y sepa que gasta 1 llamada. Para volver a mirar los mismos datos usa --solo-cache. Para saber cuántas van: --cuota.
• No saques conclusiones con muestras chicas (< 100 impresiones en video, < 30 visitas en landing).
• Si un script falla, lee el mensaje (ya viene en español con la solución) y guía al usuario; los errores comunes están en el README («Errores comunes»).