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
- SatyaSurisetti/Claude-skillstheir own version, first seen Nov 16, 2026
- darren469/Claude-Skillstheir own version, first seen Nov 16, 2026
- Ivan-propio/claude-skillstheir own version, first seen Nov 16, 2026
- BrightGold70/skillstheir own version, first seen Nov 8, 2026
- insight68/Skillstheir own version, first seen Nov 8, 2026
- therapys/dotagentstheir own version, first seen Nov 1, 2026
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.
trendinuxSkilltwitter-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
ComposioHQSkillagent-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
ComposioHQSkillhelium-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
petestewartSkilldatadog-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
OpenAISkillnotion-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
Other versions54 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 54
- ComposioHQ/awesome-claude-skills★ 75ksame name
- ComposioHQ/awesome-codex-skills★ 17ksame name
- composio-community/awesome-codex-skills★ 16ksame name
- Prat011/awesome-llm-skills★ 1.7ksame name
- Prorise-cool/Claude-Code-Multi-Agent★ 304same name
- ArogyaReddy/ComposioHQ-awesome-claude-skills★ 45same name
- frostant/awesome-claude-skills★ 44same name
- ammosu/awesome-claude-skills-zh-TW★ 27same name
- Hassaan146/claude-skills★ 18same name
- OpenSourceAssist/awesome-agent-skills★ 17same name
44 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
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
- Distinctive: line 56
NO le pidas el link antes de tener las llaves validadas.
- Very specific: line 125
🛑 ESPERA SU CONFIRMACIÓN EXPLÍCITA: No ejecutes NADA más hasta que el alumno diga "listo", "ya está", "terminé", "ok" o similar.
- Distinctive: line 182
🛑 ESPERA EL LINK: No avances hasta tener el link de la página de Facebook.
- Distinctive: line 396
No scrapea TikTok ni LinkedIn (solo Meta = Facebook + Instagram).
- Very specific: line 397
No estima performance real (spend/impressions solo vienen en ads políticos / EU).
- Distinctive: line 398
No usa navegador. Todo por API.
- Distinctive: line 399
No sube datos extraídos a ningún lado.
“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.
Files
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 +aCada 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.
- Pídele que configure el
.env(instrucciones abajo) - Espera su confirmación ("ya lo hice", "listo", "ok")
- Valida las llaves con
fix_env.py+ grep - Confírmale que están bien y pídele el link del competidor
- 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:
| Estado | Qué hacer |
| ENV_MISSING | Ir a Paso 1 (guía de creación del .env) |
| ENV_EXISTS pero alguna falta | Ir a Paso 2 (auto-fix y validación) |
| Ambas OK | Ir 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
.envEn 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):
- Crea cuenta gratis en https://console.apify.com/sign-up
- Ve a https://console.apify.com/settings/integrations
- Copia el token que empieza con
apify_api_...🟡 Google Gemini (para analizar los videos):
- Entra a https://aistudio.google.com/apikey
- Haz click en "Create API key"
- Copia la llave (empieza con
AIza...)📝 Paso 3 — Pega las dos llaves dentro del archivo
.envAbre el archivo
.envcon 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
.envy (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/nullSi el archivo .env NO existe pero .env.example sí existe:
Veo que el archivo sigue llamándose
.env.example. Necesito que le quites el.examplepara 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
.envotra vez y verificar que la línea digaAPIFY_TOKEN=apify_api_...(oGEMINI_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/notionhttps://www.facebook.com/martinvelardefilmhttps://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 =martinvelardefilmfacebook.com/profile.php?id=12345→ slug temporal =_tmp_12345(renombrar después usandopageNamedel 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.jsonIMPORTANTE: 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:
- Lee
competitor-ads/<marca>/ads_raw.json. - Deduplica videos (varios ads suelen usar el mismo creativo).
- Descarga los
.mp4SD avideos/. - Por cada video llama a
gemini-3-flash-previewcon prompt estructurado. - 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
| Error | Qué le dices al alumno |
.env con espacios o comillas | No 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 429 | Espera 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 Apify | Reintenta con resultsLimit: 50. |
🛑 Lo que NO hace esta skill
- No scrapea TikTok ni LinkedIn (solo Meta = Facebook + Instagram).
- No estima performance real (
spend/impressionssolo 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>...
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
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.

