agentleFS
dantedelao89dantedelao89/analisis-competencia-ads/.claude/skills/competitive-ads-extractor/SKILL.md

competitive-ads-extractor

Skill0 starsChanged 6 months agoMITView on GitHub

Extrae anuncios reales de competidores desde Meta Ad Library (Facebook + Instagram) usando Apify, descarga los videos y los analiza con Gemini 3 Flash Preview (transcripción + traducción al español + desglose escena por escena con timestamp + visual + audio + on-screen text + rol narrativo). Úsalo cuando el usuario pegue un link de Facebook (incluyendo facebook.com/<página>, facebook.com/profile.php?id=..., o cualquier formato de página de Facebook), mencione una marca/competidor, o pida "extrae ads", "analiza la publicidad de X", "qué está corriendo X", "scrapea ads", "bájame los videos", "transcríbeme los videos", "qué dicen los videos" o cualquier variante.

  • Reads credentials

54 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use twitter-algorithm-optimizer, agent-deep-links and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • trendinuxSkill

    twitter-algorithm-optimizer

    Analyze and optimize tweets for maximum reach using Twitter's open-source algorithm insights. Rewrite and edit user tweets to improve engagement and visibility based on how the recommendation system ranks content.

    Also in 18 projects that use this

  • ComposioHQSkill

    agent-deep-links

    Build, validate, and troubleshoot deep links for Codex, Cursor, VS Code, Visual Studio, and similar tools. Use when users ask for clickable links (especially in Slack) that open threads, files, folders, or app settings.

    Also in 3 projects that use this

  • ComposioHQSkill

    helium-mcp

    Search real-time news with bias scoring, get live stock/ETF/crypto data with AI analysis, ML options pricing, balanced news synthesis, and meme search via the Helium MCP server.

    Also in 3 projects that use this

  • petestewartSkill

    datadog-logs

    Query Datadog logs via the Logs Search API v2. Use when the user asks to "check the logs", "search logs", "find errors in Datadog", "look up logs for", "show me production logs", "check for errors", "search Datadog", or any request involving log search, error investigation, or production debugging that requires Datadog log data.

    Also in 3 projects that use this

  • OpenAISkill

    notion-meeting-intelligence

    Prepare meeting materials with Notion context and Codex research; use when gathering context, drafting agendas/pre-reads, and tailoring materials to attendees.

    Also in 5 projects that use this

  • +7 more from ComposioHQ

The file

We split this skill into the rules it gives an agent

7 rules. 0 are common, 5 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 48 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    NO le pidas el link antes de tener las llaves validadas.

    line 56
  2. Very specific:

    🛑 ESPERA SU CONFIRMACIÓN EXPLÍCITA: No ejecutes NADA más hasta que el alumno diga "listo", "ya está", "terminé", "ok" o similar.

    line 125
  3. Distinctive:

    🛑 ESPERA EL LINK: No avances hasta tener el link de la página de Facebook.

    line 182
  4. Distinctive:

    No scrapea TikTok ni LinkedIn (solo Meta = Facebook + Instagram).

    line 396
  5. Very specific:

    No estima performance real (spend/impressions solo vienen en ads políticos / EU).

    line 397
  6. Distinctive:

    No usa navegador. Todo por API.

    line 398
  7. Distinctive:

    No sube datos extraídos a ningún lado.

    line 399

“Common” is measured: kept by at least 6 in 10 of the 48 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Competitive Ads Extractor

⚠️ EL USUARIO ES 100% PRINCIPIANTE. No le pidas que abra una terminal extra, ni que ejecute comandos. Tú haces TODO.

🇲🇽 IDIOMA: ESPAÑOL NEUTRAL MEXICANO. Usa "tú", "puedes", "haz", "dile", "necesitas". NUNCA uses "vos", "tenés", "decís", "podés", "andá", "hacé".


🚨 REGLAS CRÍTICAS (lee antes de hacer cualquier cosa)

REGLA 1 — Las llaves SIEMPRE están en .env, NUNCA en el shell environment

❌ NO hagas esto:

echo $APIFY_TOKEN  # ← INCORRECTO, el shell environment está vacío cada vez

✅ SIEMPRE haz esto antes de usar las llaves:

set -a && source .env && set +a

Cada llamada a Bash que ejecutes es una sesión nueva. Las variables NO persisten entre llamadas. Por lo tanto, antes de cada comando que necesite las llaves, debes cargar el .env explícitamente.

REGLA 2 — Las URLs de página de Facebook SÍ funcionan directamente

El actor apify/facebook-ads-scraper acepta TODOS estos formatos sin transformación:

✅ https://www.facebook.com/aivideoskool
✅ https://www.facebook.com/martinvelardefilm
✅ https://www.facebook.com/profile.php?id=61577852912181
✅ https://www.facebook.com/ads/library/?...&q=keyword
✅ https://www.facebook.com/ads/library/?...&view_all_page_id=...

❌ NUNCA le digas al alumno "esa URL es la página, no la Ad Library, necesito el formato facebook.com/ads/library/...". ESO ES FALSO. El actor resuelve la página directamente.

Si el alumno te pasa facebook.com/martinvelardefilm → úsalo TAL CUAL en startUrls.

REGLA 3 — Flujo lineal estricto después del clone

Cuando el alumno acabe de clonar el repo, sigue este flujo en este orden exacto. No te saltes pasos.

  1. Pídele que configure el .env (instrucciones abajo)
  2. Espera su confirmación ("ya lo hice", "listo", "ok")
  3. Valida las llaves con fix_env.py + grep
  4. Confírmale que están bien y pídele el link del competidor
  5. Recibe el link (cualquier formato de Facebook) y ejecuta el pipeline

NO le pidas el link antes de tener las llaves validadas. NO le pidas las llaves "exportadas en el shell".


🎬 FLUJO COMPLETO PASO A PASO

Paso 0 — Detecta dónde estás parado

Cuando el alumno inicia conversación o pega un link, antes de hacer cualquier cosa, verifica el estado del proyecto:

# ¿Existe el .env?
test -f .env && echo "ENV_EXISTS" || echo "ENV_MISSING"
# Si existe, ¿tiene las llaves?
test -f .env && grep -qE "^APIFY_TOKEN=apify_api_" .env && echo "APIFY_OK" || echo "APIFY_FALTA"
test -f .env && grep -qE "^GEMINI_API_KEY=AIza" .env && echo "GEMINI_OK" || echo "GEMINI_FALTA"

Decide el flujo según el resultado:

EstadoQué hacer
ENV_MISSINGIr a Paso 1 (guía de creación del .env)
ENV_EXISTS pero alguna faltaIr a Paso 2 (auto-fix y validación)
Ambas OKIr directo al Paso 3 (pedir URL del competidor)

Paso 1 — Guía al alumno a crear el .env (si no existe)

Dile EXACTAMENTE este mensaje (adáptalo al tono pero mantén la estructura):

👋 ¡Bienvenido! Antes de poder analizar a tus competidores, necesitas configurar dos llaves gratuitas. Hazlo así:

📋 Paso 1 — Renombra el archivo de ejemplo a .env

En tu carpeta del proyecto vas a encontrar un archivo llamado .env.example. Cámbiale el nombre a .env (quita el .example).

  • En Mac/Linux: en la Terminal corre mv .env.example .env
  • En Windows: click derecho → Renombrar → déjalo como .env
  • En VS Code / tu editor: click derecho sobre el archivo → Renombrar

🔑 Paso 2 — Consigue tus 2 llaves gratuitas

🔵 Apify (para descargar los anuncios de Facebook):

  1. Crea cuenta gratis en https://console.apify.com/sign-up
  2. Ve a https://console.apify.com/settings/integrations
  3. Copia el token que empieza con apify_api_...

🟡 Google Gemini (para analizar los videos):

  1. Entra a https://aistudio.google.com/apikey
  2. Haz click en "Create API key"
  3. Copia la llave (empieza con AIza...)

📝 Paso 3 — Pega las dos llaves dentro del archivo .env

Abre el archivo .env con cualquier editor de texto (TextEdit en Mac, Notepad en Windows, o tu VS Code). Vas a ver dos líneas — reemplaza los placeholders con tus llaves reales, dejando el formato exacto:

APIFY_TOKEN=apify_api_aqui_va_tu_token
GEMINI_API_KEY=AIza_aqui_va_tu_llave

⚠️ Sin espacios alrededor del =, sin comillas. Si te equivocas con el formato, no te preocupes — yo lo arreglo automáticamente.

✅ Paso 4 — CONFÍRMAME cuando hayas terminado

Cuando ya hayas (1) renombrado el archivo a .env y (2) pegado tus dos llaves dentro, escríbeme literalmente "listo" (o "ya está", "terminé", "ok"). En cuanto me confirmes, yo abro el archivo, reviso que las llaves estén bien escritas, arreglo cualquier espacio o error de formato, y valido contra Apify y Google que de verdad funcionen. Si algo está mal te aviso para que lo corrijas.

🛑 ESPERA SU CONFIRMACIÓN EXPLÍCITA. No ejecutes NADA más hasta que el alumno diga "listo", "ya está", "terminé", "ok" o similar. NO valides el .env antes de que confirme — podrías leerlo a medio editar.


Paso 2 — Auto-fix y validación (SOLO después de que el alumno confirme "listo")

Cuando el alumno confirme que ya configuró el .env, ejecuta estos comandos en orden:

# 0. Primero verifica que el archivo .env exista (puede que renombró mal)
test -f .env && echo "ENV_OK" || echo "ENV_MISSING"
ls -la .env.example .env 2>/dev/null

Si el archivo .env NO existe pero .env.example sí existe:

Veo que el archivo sigue llamándose .env.example. Necesito que le quites el .example para que quede solo como .env. ¿Lo renombro yo por ti?

Si el alumno dice que sí (o lo hace él mismo), ejecuta mv .env.example .env solo si tiene contenido real (no placeholders). Si todavía tiene placeholders, recuérdale pegar sus llaves reales primero.

# 1. Saneamiento automático del .env (arregla espacios, comillas, CRLF, etc.)
python3 scripts/fix_env.py

# 2. Validar formato de las llaves
test -f .env && grep -qE "^APIFY_TOKEN=apify_api_" .env && echo "APIFY_FORMAT_OK" || echo "APIFY_FORMAT_BAD"
test -f .env && grep -qE "^GEMINI_API_KEY=AIza" .env && echo "GEMINI_FORMAT_OK" || echo "GEMINI_FORMAT_BAD"

# 3. Validar que las llaves funcionen REALMENTE contra los servicios
set -a && source .env && set +a
APIFY_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "https://api.apify.com/v2/users/me?token=$APIFY_TOKEN")
GEMINI_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "https://generativelanguage.googleapis.com/v1beta/models?key=$GEMINI_API_KEY")
echo "APIFY: $APIFY_STATUS"
echo "GEMINI: $GEMINI_STATUS"

Interpretación:

  • APIFY: 200 = funciona · 401 = token mal · 402 = sin saldo · otro = inválido
  • GEMINI: 200 = funciona · 400/403 = llave inválida

fix_env.py arregla automáticamente: espacios alrededor del =, comillas envolventes ("..." o '...'), espacios al final de línea, saltos CRLF de Windows. No tienes que pedirle al alumno que corrija formato — el script lo hace. Solo le pides corregir si la llave en sí es inválida.

Si APIFY_FORMAT_BAD o GEMINI_FORMAT_BAD: el placeholder sigue ahí o pegó algo mal.

Veo que la llave de [Apify/Gemini] todavía tiene el placeholder o algo raro. ¿Puedes abrir el archivo .env otra vez y verificar que la línea diga APIFY_TOKEN=apify_api_... (o GEMINI_API_KEY=AIza...) con tu llave real? Pégala de nuevo y avísame.

Si APIFY != 200 o GEMINI != 200: la llave tiene formato correcto pero el servicio la rechaza.

Mmm, la llave de [Apify/Gemini] tiene buen formato pero el servidor me devuelve [código]. Suele significar que la copiaste incompleta o que es de otra cuenta. ¿La sacas de nuevo de [link directo] y la pegas en .env? Cuando termines, dime "listo" otra vez.

Si ambas devuelven 200:

✅ ¡Perfecto, las dos llaves están funcionando!

Ahora pásame el link de la página de Facebook del competidor que quieres analizar. Funciona con cualquiera de estos formatos:

  • https://www.facebook.com/notion
  • https://www.facebook.com/martinvelardefilm
  • https://www.facebook.com/profile.php?id=61577852912181

⚠️ No necesitas la URL de la Ad Library — solo dame la página normal del competidor y yo me encargo del resto.

🛑 ESPERA EL LINK. No avances hasta tener el link de la página de Facebook.


Paso 3 — Pipeline de extracción y análisis

Cuando el alumno te pase el link, ejecuta el pipeline. SIEMPRE carga el .env al inicio de cada bash:

3.1 — Crear carpeta y extraer ads con Apify

Sluggea el nombre de la marca a partir de la URL:

  • facebook.com/martinvelardefilm → slug = martinvelardefilm
  • facebook.com/profile.php?id=12345 → slug temporal = _tmp_12345 (renombrar después usando pageName del response)
set -a && source .env && set +a
mkdir -p competitor-ads/<slug>

curl -s -w "HTTP %{http_code} en %{time_total}s\n" \
  "https://api.apify.com/v2/acts/apify~facebook-ads-scraper/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -X POST -H 'Content-Type: application/json' \
  -d '{
    "startUrls": [{"url": "<LINK_QUE_PEGÓ_EL_ALUMNO>"}],
    "resultsLimit": 200,
    "isDetailsPerAd": true,
    "includeAboutPage": true,
    "activeStatus": "active"
  }' \
  -o competitor-ads/<slug>/ads_raw.json

IMPORTANTE: el campo startUrls recibe el link de la página tal cual lo pegó el alumno. NO lo transformes.

3.2 — Si hay > 50 ads, filtrar a top long-runners

python3 scripts/filter_top_ads.py competitor-ads/<slug> 30

(Solo si la marca tiene más de 50 ads activos — si tiene menos, sáltate este paso.)

3.3 — Generar CSV

python3 -c "
import json, csv
d = json.load(open('competitor-ads/<slug>/ads_raw.json'))
rows = []
for ad in d:
    s = ad.get('snapshot') or {}
    body = ((s.get('body') or {}).get('text') or '').strip()
    vids = s.get('videos') or []
    rows.append({
        'adArchiveID': ad.get('adArchiveID') or '',
        'pageName': s.get('pageName') or '',
        'startDate': (ad.get('startDateFormatted') or '')[:10],
        'endDate': (ad.get('endDateFormatted') or '')[:10],
        'displayFormat': s.get('displayFormat') or '',
        'collationCount': ad.get('collationCount') or 1,
        'title': s.get('title') or '',
        'ctaText': s.get('ctaText') or '',
        'linkUrl': s.get('linkUrl') or '',
        'copy': body.replace(chr(10),' / '),
        'videoHdUrl': (vids[0] or {}).get('videoHdUrl','') if vids else '',
    })
with open('competitor-ads/<slug>/ads_summary.csv','w',newline='',encoding='utf-8') as f:
    w = csv.DictWriter(f, fieldnames=list(rows[0].keys())); w.writeheader(); w.writerows(rows)
print(f'CSV: {len(rows)} filas')
"

3.4 — Descargar videos + análisis con Gemini

python3 scripts/process_all_videos.py competitor-ads/<slug>

3.5 — Clasificar audiencia (si no se hizo en 3.4)

python3 scripts/classify_audience.py competitor-ads/<slug>

3.6 — Generar informes

python3 scripts/build_analysis.py competitor-ads/<slug>
python3 scripts/build_html.py competitor-ads/<slug>

3.7 — Abrir el HTML automáticamente

open competitor-ads/<slug>/analysis.html

(En Linux usar xdg-open, en Windows usar start.)

3.8 — Resumir al alumno

🎯 Listo. Analicé N ads de <marca> (X creativos únicos, Y escenas).

Hallazgos clave:

  • <insight 1>
  • <insight 2>
  • <insight 3>

📂 Archivos generados (ya abrí el HTML en tu navegador):

  • analysis.html ⭐ informe visual
  • analysis.md versión texto
  • ads_summary.csv tabla Excel
  • videos/ los .mp4 descargados

¿Quieres analizar otro competidor o comparar varios con un dashboard?


📦 Schema del output del actor de Apify

{
  "adArchiveID": "1354041633403636",
  "pageID": "825120160874613",
  "startDateFormatted": "2026-01-30T08:00:00.000Z",
  "endDateFormatted": "2026-02-04T08:00:00.000Z",
  "collationCount": 1,
  "snapshot": {
    "pageName": "Notion",
    "body": { "text": "Copy del ad..." },
    "ctaText": "Learn more",
    "ctaType": "LEARN_MORE",
    "linkUrl": "https://...",
    "displayFormat": "VIDEO",
    "images": [{ "originalImageUrl": "..." }],
    "videos": [{ "videoHdUrl": "...", "videoSdUrl": "...", "videoPreviewImageUrl": "..." }],
    "cards": [],
    "brandedContent": { "pageName": "...", "pageProfileUri": "..." }
  }
}

Heurística de "qué funciona": ads viejos que siguen activos = los que la marca está escalando. Ordena por startDateFormatted ascendente. collationCount > 1 = variantes A/B.


🎬 Análisis profundo de videos con Gemini 3 Flash

El script scripts/process_all_videos.py ya hace todo el flujo:

  1. Lee competitor-ads/<marca>/ads_raw.json.
  2. Deduplica videos (varios ads suelen usar el mismo creativo).
  3. Descarga los .mp4 SD a videos/.
  4. Por cada video llama a gemini-3-flash-preview con prompt estructurado.
  5. Guarda video_analyses.json.

Schema del output por video:

{
  "detected_language": "en",
  "transcript_original": "...",
  "transcript_es": "...",
  "scenes_breakdown": [
    {
      "scene_number": 1,
      "timestamp_start": "0:00",
      "timestamp_end": "0:03",
      "visual": "...",
      "audio_dialogue": "...",
      "audio_dialogue_es": "...",
      "on_screen_text": "...",
      "shot_type": "...",
      "purpose": "hook / pain / solución / demo / oferta / objeción / CTA / social proof"
    }
  ],
  "hook_first_3s": "...",
  "tone": "...",
  "key_visual_elements": ["..."],
  "value_props_dichas": ["..."],
  "cta_verbal": "...",
  "price_mentioned": "...",
  "social_proof_mentioned": "...",
  "audience": {
    "audience_temperature": "cold | warm | retargeting",
    "confidence": "high | medium | low",
    "reasoning": "...",
    "signals_detected": ["..."]
  }
}

Clasificación de audiencia:

  • 🧊 cold (TOFU): explica quién/qué es la marca, hooks fuertes, define el problema, producción alta.
  • 🌡️ warm (MOFU): demos del producto, casos de uso, testimonios. Asume cierto contexto.
  • 🔥 retargeting (BOFU): asume familiaridad total. Urgencia/escasez, descuentos, CTA imperativo corto.

⚠️ Errores comunes y respuestas conversacionales

ErrorQué le dices al alumno
.env con espacios o comillasNo le dices nada — fix_env.py lo arregla automático.
Apify 401"La llave de Apify no funciona. ¿La copias de nuevo desde acá?"
Apify 402 (sin saldo)"Se acabó el saldo gratis de Apify. Carga más aquí ($5 USD mínimo) o espera al mes que viene."
Apify JSON vacío []"No encontré ads activos de esa marca. Tal vez no está pauteando, o el nombre está distinto, o está en otro país. ¿Probamos con otro nombre o me dices el país?"
Gemini 429Espera 30s y reintenta. No molestes al alumno.
Gemini 400 invalid api key"La llave de Gemini no la acepta Google. ¿La regeneras en aistudio.google.com/apikey y me la pegas?"
Timeout en ApifyReintenta con resultsLimit: 50.

🛑 Lo que NO hace esta skill

  • No scrapea TikTok ni LinkedIn (solo Meta = Facebook + Instagram).
  • No estima performance real (spend/impressions solo vienen en ads políticos / EU).
  • No usa navegador. Todo por API.
  • No sube datos extraídos a ningún lado. Todo queda local.

💡 Ejemplos de uso

  • https://www.facebook.com/aivideoskool (solo el link → todo automático)
  • "Analiza los ads de Glovo en México"
  • "Compara Rappi y PedidosYa, qué pain points usan"
  • "Bájame los videos top de Notion y dime qué hooks usan"
  • "Hazme el dashboard cross-competidor con todos los que ya analicé"

🔁 Segunda corrida (alumno que ya configuró todo)

Si .env ya tiene ambas llaves válidas, NO repitas el onboarding. Saluda corto y arranca:

👋 ¡Hola de nuevo! Detecté tus llaves, voy a analizar <marca>...

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.