kkarpushin/reels-trends

Recherche de tendances Reels

Identifie ce qui est devenu viral sur Instagram Reels pour un créneau donné sur une période choisie, et explique pourquoi, avec un rapport que l'utilisateur peut exploiter directement.

La métrique centrale est le × par rapport à la médiane de l'auteur : vues du Reel divisées par la médiane des vues des vidéos récentes de l'auteur (plancher à 1 000). Elle sépare les Reels qui ont décollé grâce au format de ceux qui sont populaires uniquement parce que le compte est grand.

Les scripts se trouvent dans ${CLAUDE_SKILL_DIR}/scripts/, les notes de référence dans ${CLAUDE_SKILL_DIR}/references/. Chaque script prend le dossier d'exécution (RUN ci-dessous) comme premier argument et affiche ce qu'il a fait et son coût.

Avant de commencer

1. Token Apify. Vérifie echo ${APIFY_TOKEN:+set} ou le fichier ~/.config/reels-trends/apify_token. Si aucun n'existe, demande à l'utilisateur de créer un token sur https://console.apify.com/settings/integrations et de le sauvegarder avec mkdir -p ~/.config/reels-trends && read -s T && echo "$T" > ~/.config/reels-trends/apify_token && chmod 600 ~/.config/reels-trends/apify_token. Sur Windows : setx APIFY_TOKEN "<token>" et redémarre le terminal. Ne jamais imprimer, journaliser ou commiter le token.
2. Paquets Python. python3 -c "import lingua, PIL" ; si ça échoue : pip install lingua-language-detector pillow (ajoute --user ou utilise un environnement virtuel si pip refuse). ffmpeg est optionnel mais fortement recommandé : sans lui, les agents étiquettent les leaders à partir des couvertures uniquement. Sur Windows, utilise python là où ce fichier dit python3.
3. Brief. Demande uniquement ce que tu ne peux pas déduire, en un message, avec les valeurs par défaut :
   • créneau, dans les mots de l'utilisateur (et quoi exclure, ex. "dentisterie, pas les étudiants en dentisterie") ;
   • marchés : pays ou langues, ou "le monde entier" ;
   • période : par défaut les 30 derniers jours ; une fenêtre qui se termine aujourd'hui est acceptable, les Reels les plus récents ont simplement moins de vues ;
   • budget en USD : par défaut 5 $ sur un plan Apify gratuit, 10-15 $ sur un plan payant ;
   • langue du rapport : par défaut la langue que l'utilisateur utilise (les chaînes UI existent pour ru et en).

Workflow

1. Dossier d'exécution et configuration

Crée reels-research/<slug-court>/ dans le projet courant (ou là où l'utilisateur le souhaite ; si le projet est un dépôt git, ajoute reels-research/ à son .gitignore) et écris config.json. Lis d'abord ${CLAUDE_SKILL_DIR}/references/config.md : il explique chaque champ et comment écrire de bonnes requêtes. L'essentiel :

• segments : un par langue ou marché, avec 8 à 30 requêtes natives pour les grands marchés (des vraies phrases tapées par les gens, noms de services, argot) et 3 à 6 pour les petits, plus min_views adapté au marché. Les requêtes en anglais ramènent du contenu du monde entier ; écris chaque requête dans sa propre langue.
• relevance_regex : les racines des mots du créneau dans chaque langue que tu recherches (un Reel doit correspondre pour être conservé).
• exclude_regex : ce qui ne doit jamais compter (services adultes, spam, significations non liées du mot du créneau).
• topics : 8 à 12 sous-thèmes avec des regex multilingues, ordonnés du plus spécifique au plus générique, plus fallback_topic.
• focus_topics : les thèmes que tu prévois de comparer entre les langues. ${CLAUDE_SKILL_DIR}/references/examples/ contient une configuration mondiale complète (massage, 19 langues) et une configuration pour petit plan gratuit.

2. Vérification du compte et coût

python3 ${CLAUDE_SKILL_DIR}/scripts/check.py RUN
python3 ${CLAUDE_SKILL_DIR}/scripts/search.py RUN --dry

check.py lit le plan et choisit le moteur : memo23 sur les plans Apify payants (filtres de date et de vues côté serveur, les échecs sont gratuits) ou hashtag sur le plan gratuit (memo23 ne sert aux comptes gratuits qu'une seule requête avec peu de résultats). Indique à l'utilisateur le plan, le moteur, le coût dans le pire cas et le budget, en une ou deux lignes. Les scripts ne démarrent jamais d'exécutions au-dessus du budget_usd restant ; ne l'augmente qu'avec l'accord de l'utilisateur.

3. Recherche et fusion

python3 ${CLAUDE_SKILL_DIR}/scripts/search.py RUN          # 5-25 min, lance-le en arrière-plan
python3 ${CLAUDE_SKILL_DIR}/scripts/merge.py RUN

Lis le résumé de la fusion avant de payer quoi que ce soit d'autre :

• beaucoup de not_in_niche : la regex est trop étroite ou les requêtes dévient ; beaucoup de Reels conservés hors-sujet : la regex est trop large ;
• une langue avec très peu de Reels : ajoute des requêtes dans cette langue et relance search.py RUN --only SEG --tag extra2, puis refusionne (les fichiers bruts s'accumulent) ;
• avec le moteur hashtag, outside_dates est souvent 70-90 % : utilise une fenêtre de 30 à 60 jours, plus de hashtags plus spécifiques, un search.hashtag_results plus grand, ou suggère un plan payant.

4. Auteurs, multiplicateur, leaders

python3 ${CLAUDE_SKILL_DIR}/scripts/profiles.py RUN --dry   # puis sans --dry
python3 ${CLAUDE_SKILL_DIR}/scripts/score.py RUN
python3 ${CLAUDE_SKILL_DIR}/scripts/leaders.py RUN

Les profils ne sont récupérés que pour les auteurs ayant un Reel au-dessus du profiles.floor_by_lang ; ajuste les seuils ou --max pour respecter le budget. Leaders = top mondial par × (avec un seuil de vues) + top par vues + top par × dans chaque langue. Vise 100 à 250 leaders pour une exécution mondiale, 30 à 80 pour un seul marché.

5. Enrichir les leaders (lance les trois en parallèle)

python3 ${CLAUDE_SKILL_DIR}/scripts/transcripts.py RUN
python3 ${CLAUDE_SKILL_DIR}/scripts/about.py RUN        # pays de chaque compte leader, plans payants uniquement
python3 ${CLAUDE_SKILL_DIR}/scripts/media.py RUN        # bandes de 4 images + couvertures ; les liens CDN expirent en jours, donc fais-le rapidement après la recherche

6. Étiquetter les leaders à partir des images

python3 ${CLAUDE_SKILL_DIR}/scripts/batches.py RUN --size 20

Il écrit work/label_prompt.md (les instructions, déjà remplies avec la taxonomie de ce créneau) et un fichier par lot de 20 leaders, et affiche les chemins BATCH et OUT. Lance un sous-agent par lot, tous dans un seul message pour qu'ils s'exécutent en parallèle, avec cette instruction :

Lis les instructions d'étiquetage dans RUN/work/label_prompt.md et suis-les exactement. Dans ces instructions, {BATCH} = et {OUT} = .

Si les sous-agents ne sont pas disponibles, étiquette toi-même les lots avec les mêmes instructions. Les étiquettes doivent provenir de l'observation des images : beaucoup de Reels dans des créneaux visuels n'ont pas de parole, et la légende ne décrit souvent pas ce qui est à l'écran. Vérifie la couverture avec python3 ${CLAUDE_SKILL_DIR}/scripts/labels.py RUN.

7. Révision avant de compter

Ouvre les images des 20 premiers leaders par × et de chaque Reel qu'un agent a signalé ou marqué comme non pertinent. Uniformise les règles entre les lots dans work/overrides.json (format dans ${CLAUDE_SKILL_DIR}/references/content.md) : par exemple, les Reels uniquement sportifs ne sont pas du massage ; les fermes de contenu qui vendent le corps d'un modèle plutôt que le service vont dans "flagged": {"<code du Reel>": "sexualisé"} ; les reposts de la vidéo de quelqu'un d'autre reçoivent "repost". Les Reels signalés restent dans les données et dans la grille du rapport (cachés par défaut) mais pas dans le tableau des formats ni dans les idées.

8. Chiffres et histoire

python3 ${CLAUDE_SKILL_DIR}/scripts/stats.py RUN

Lis le résumé et trouve 6 à 7 conclusions exploitables par un chef d'entreprise. Vérifie chaque affirmation par rapport aux données avant de l'écrire :

• une affirmation qu'il manque quelque chose dans une langue nécessite la preuve que tu as cherché dans cette langue avec les bons mots (ajoute des requêtes et relance si nécessaire) ;
• les formats avec moins de 5 leaders reçoivent une mention "peu de Reels" ;
• calcule tout chiffre supplémentaire avec un court snippet Python sur work/scored.json et work/cls/, jamais de mémoire. Écris ensuite RUN/content.json en suivant ${CLAUDE_SKILL_DIR}/references/content.md : conclusions, notes sur les formats, les thèmes et les langues, 8 à 10 idées (titre, accroche que l'utilisateur peut dire devant la caméra, pourquoi ça marche avec des chiffres, 2-3 codes de Reels en exemple) et 12 à 16 accroches pour la section "premières secondes".

9. Rapport

python3 ${CLAUDE_SKILL_DIR}/scripts/build.py RUN

Produit report/index.html (à ouvrir dans un navigateur), report/artifact.html (version corps uniquement pour publication comme artefact Claude, si l'environnement dispose d'un outil Artifact) et report/reels.json (tous les Reels avec scores et étiquettes). Indique à l'utilisateur où se trouve le rapport, le coût total de l'exécution (work/spend.jsonl), et les 3 à 5 conclusions les plus utiles en termes simples.

Lire les chiffres honnêtement

• La recherche renvoie des Reels notables, pas tous les Reels, donc les médianes sont plus élevées que celles d'un compte typique. Compare les groupes entre eux, pas avec les propres chiffres de l'utilisateur.
• × est relatif à l'auteur : les petits comptes produisent les plus grands multiplicateurs. C'est le but (la portée n'a pas besoin d'abonnés), mais dis-le.
• Le tableau des formats décrit les leaders, pas l'ensemble du créneau. Les tableaux de thèmes, de durée et d'abonnés utilisent tous les Reels.
• Les Reels des derniers jours de la fenêtre accumulent encore des vues.
• La langue n'est pas le pays. Utilise about.py pour les pays.

D'autres leçons issues d'exécutions réelles se trouvent dans ${CLAUDE_SKILL_DIR}/references/gotchas.md. Lis-le avant une exécution mondiale ou multilingue.