playbook-seo

Playbook SEO

Cette compétence transforme le SEO en un workflow d'ingénierie reproductible : trouver des requêtes que le site peut réellement gagner, donner à chaque page un objectif clair, placer les bons mots dans les bons éléments HTML, s'assurer que Google peut explorer, afficher et indexer le résultat, acquérir des liens, puis mesurer et itérer.

Elle distille ce qui a fonctionné (et ce qui a silencieusement cassé) en faisant passer un jeune site Next.js d'outils de zéro à des positions de première page sur des requêtes longue traîne. Les leçons sont généralisables à n'importe quelle stack.

L'état d'esprit, en cinq phrases

1. Le classement suit la capacité à gagner, pas les souhaits. Un jeune domaine n'atteindra pas le top 5 pour un terme générique comme "générateur de code QR" cette année ; il peut se classer en quelques semaines pour "générateur de code QR gratuit sans inscription" ou "lien de souhait d'anniversaire avec nom". Ciblez d'abord la longue traîne et laissez l'autorité thématique faire monter le terme générique plus tard.
2. Une page, une intention de recherche, un mot-clé principal. Deux pages ciblant la même requête divisent les signaux (cannibalisation) ; une page ciblant deux intentions ne sert ni l'une ni l'autre.
3. Google classe le HTML qu'il reçoit, pas l'application que l'utilisateur voit. Si le contenu, le H1, les réponses FAQ ou les liens n'apparaissent qu'après l'exécution de JavaScript, supposez qu'ils n'existent pas. Vérifiez la réponse brute du serveur à chaque fois.
4. Les bugs d'indexabilité l'emportent sur la rédaction. Un soft 404, un canonical erroné ou un noindex hérité d'une mise en page peuvent effacer des mois de travail de contenu sans aucune erreur. Vérifiez les codes de statut, les canoniques et les robots sur chaque type de page que vous touchez.
5. Mesurez avec Search Console, pas avec l'intuition. Les impressions aux positions 8–20 sont les victoires les moins coûteuses ; la position 50+ signifie un problème d'autorité ou d'intention que davantage de modifications sur la page ne résoudront pas.

Fixez les attentes de l'utilisateur honnêtement : les premières impressions pour les pages longue traîne apparaissent généralement dans 2 à 6 semaines ; les termes génériques prennent des mois et des backlinks. Le SEO "rapide" signifie choisir des combats que le site peut gagner.

Choisissez d'abord la profondeur

La plupart des demandes SEO sont petites. Choisissez le mode avant de faire quoi que ce soit, car le workflow complet coûte plusieurs fois plus de temps et de ressources qu'une petite modification ne le nécessite.

Mode rapide pour les modifications d'une ou deux pages où le mot-clé est connu ou évident : renommer une page, rédiger une méta-description, ajouter des FAQ, corriger un problème signalé, ou ajouter une page à un projet qui a déjà un modèle SEO à copier. En mode rapide :

• Ne lisez pas les fichiers de référence et ne recherchez pas le SERP en direct, sauf si une vérification ci-dessous échoue ou si vous ne pouvez vraiment pas décider.
• Suivez le modèle SEO existant du projet : son helper de métadonnées, sa configuration de contenu et ses composants de schéma.
• Effectuez la modification, puis exécutez la liste de contrôle rapide ci-dessous sur le résultat. S'il y a du HTML intégré ou servi, exécutez scripts/seo_check.py une fois dessus.
• Rapportez en quelques lignes. Mentionnez tout ce que vous avez remarqué de plus important comme une ligne "À faire aussi", sans enquêter dessus.

Liste de contrôle rapide (page modifiée uniquement) :

1. Le titre est unique, commence par le mot-clé, ≤ 60 caractères. La description fait 120–160 caractères et ne contient que des affirmations vraies.
2. Exactement un H1, et la copie principale, le H1 et les réponses FAQ sont dans le HTML du serveur (pas côté client uniquement, pas opacity:0, pas démontés).
3. La page définit son propre canonical, est indexable et se trouve dans le sitemap. Les pages cachées utilisent noindex et ne sont pas interdites dans robots.txt.
4. 3–5 liens internes sortants, et au moins un lien entrant.
5. Les données structurées correspondent au contenu visible, sans notes qui ne sont pas propres au site.

Mode complet est le workflow ci-dessous. Utilisez-le pour :

• un nouveau site, ensemble de pages ou cluster
• choisir des mots-clés lorsque la cible appropriée n'est pas claire
• diagnostiquer "pourquoi cela ne se classe-t-il pas" ou "le trafic est plat"
• un audit pré-lancement ou à l'échelle du site
• un plan hors-page

Une vérification rapide peut révéler un problème à l'échelle du site, comme un canonical hérité, un motif soft-404 ou des évaluations fabriquées. N'élargissez pas silencieusement le travail : terminez la modification demandée, placez le problème en haut de votre rapport avec une ligne sur pourquoi il est important, et proposez le passage complet. L'utilisateur décide s'il veut y investir. L'exception est lorsque la modification demandée ne peut pas fonctionner sans le correctif, par exemple lorsque la page que vous modifiez n'a pas de H1 rendu par le serveur. Dans ce cas, corrigez le minimum nécessaire et dites-le.

Workflow (mode complet)

Exécutez les phases dans l'ordre pour un nouveau site ou ensemble de pages. Pour une modification d'une seule page, effectuez au minimum les phases 3, 4 et 6. Lisez le fichier de référence lié lorsque vous atteignez une phase — chacun contient la liste de contrôle détaillée et les modèles.

Adaptez le travail à la demande. Une révision de page est une révision de page ; une carte de mots-clés est une carte de mots-clés. Effectuez le travail demandé en profondeur, et placez les opportunités adjacentes (mots-clés, idées hors-page) dans une courte liste "À faire aussi" plutôt que de produire des plans supplémentaires complets que personne n'a demandés. Les livrables supplémentaires diluent celui dont l'utilisateur a besoin et coûtent du temps.

Vérifiez avant d'affirmer. Vérifiez les faits que vous pouvez vérifier (le SERP en direct, si le nom de marque est déjà pris, ce qu'une page contient réellement, ce qu'une fonctionnalité fait réellement). Lorsque vous ne pouvez pas vérifier quelque chose — une page que vous ne connaissez que par URL, un site qui ne se charge pas, une fonctionnalité que vous n'avez pas vue — dites qu'il s'agit d'une hypothèse et dites à l'utilisateur quoi confirmer. Les suppositions confiantes sur le site de quelqu'un sont la façon la plus courante dont les conseils SEO tournent mal.

Les scripts sont pour vous. Exécutez vous-même scripts/*.py. Dans les instructions écrites pour l'utilisateur, décrivez la vérification en termes simples ou donnez une commande qu'ils peuvent exécuter sans cette compétence (curl, étapes Search Console). Référencez les chemins de script de la compétence uniquement lorsque vous savez que l'utilisateur a la compétence installée.

Phase 1 — Reconnaissance (avant de changer quoi que ce soit)

• Identifiez la stack et comment les pages sont rendues (SSR, SSG, SPA, hybride). Pour les pièges du framework, lisez la section pertinente de references/technical-seo.md (Next.js App Router a sa propre section).
• Inventoriez ce qui existe : comment les métadonnées sont définies, où vit la copie de la page, la génération du sitemap et de robots, les composants de données structurées, l'analytique. Réutilisez les modèles existants plutôt que d'en ajouter de nouveaux parallèles.
• Récupérez une page représentative de chaque type en tant que Googlebot et enregistrez la base de référence : python3 <skill-dir>/scripts/seo_check.py <url> [<url> ...] Il rapporte le statut, les longueurs du titre/de la description, le canonical, la méta robots et X-Robots-Tag, le nombre de H1, le nombre de mots visibles, les types JSON-LD, l'image OG et les signaux d'alarme comme un élément principal "Chargement…".
• Si les données Search Console sont disponibles (une exportation, un helper API, ou la compétence seo-google si installée), extrayez 90 jours de lignes requête+page et exécutez scripts/gsc_opportunities.py (voir Phase 6). Les impressions existantes vous disent ce que Google associe déjà au site.
• Recherchez des docs SEO de projet ou des notes de mémoire d'audits antérieurs et construisez dessus.

Phase 2 — Recherche de mots-clés et carte de mots-clés

Lisez references/keyword-research.md. En bref :

1. Partez du produit : ce que fait la page, qui l'utilise, les mots que les utilisateurs tapent lorsqu'ils veulent exactement cela.
2. Élargissez avec des signaux gratuits : l'autocomplétion Google et "Les gens demandent aussi", les recherches associées, les titres des concurrents, les requêtes GSC, la formulation Reddit/Quora. Utilisez des API payantes uniquement si le projet les a (par exemple, les compétences seo-dataforseo ou seo-ahrefs, si installées).
3. Classez l'intention (faire / savoir / aller / acheter) et regardez le SERP en direct pour chaque candidat. Si la première page est composée uniquement de grandes marques ou d'un type de page différent (par exemple, des listicles alors que vous avez un outil), le mot-clé n'est pas encore gagnable pour cette page.
4. Notez la capacité à gagner : des concurrents faibles (pages indiennes minces, forums, repositories GitHub, sites *.vercel.app) en première page est le signal le plus fort.
5. Vérifiez le nom de la marque : recherchez-le nu, plus npm/PyPI/GitHub/app stores si pertinent. S'il est pris, recommandez d'utiliser le formulaire de domaine ("Brand.app") de manière cohérente.
6. Produisez une carte de mots-clés : une ligne par URL avec le mot-clé principal, 3–8 termes secondaires/longue traîne, l'intention, et où chaque terme va (titre, H1, H2, intro, FAQ). Aucun mot-clé principal n'apparaît sur deux lignes, et chaque ligne de chaque tableau a une intention.

Les volumes sans outil payant sont des niveaux directionnels (très élevé / élevé / moyen / faible). Dites-le dans votre sortie au lieu d'inventer des nombres.

Phase 3 — Implantation on-page

Lisez references/on-page.md pour la liste de contrôle complète et le modèle de contenu de la page. Les essentiels pour chaque page indexable :

• Titre : unique, mot-clé principal en premier, idéalement ≤ 60 caractères y compris tout suffixe de marque, et rédigé pour gagner le clic.
• Méta-description : unique, 120–160 caractères, indique ce que l'utilisateur obtient et le différenciateur ("gratuit, sans inscription, fonctionne dans votre navigateur") uniquement lorsque c'est vrai.
• Exactement un H1 dans le HTML du serveur, correspondant à l'intention principale de la page (une variante proche du titre, pas une copie).
• Corps : répondez à la requête dans le premier paragraphe, puis ajoutez de la profondeur qu'une page concurrente n'a pas : étapes pratiques, exemples concrets, problèmes courants avec des correctifs, limitations, FAQ. Chaque section existe parce qu'un chercheur en a besoin, pas pour atteindre un nombre de mots.
• FAQ visibles dans le HTML (pas seulement dans des accordéons repliés et démontés et pas seulement en JSON-LD), formulées comme de vraies requêtes.
• Liens internes : 3–5 liens contextuels vers des pages associées et au moins un lien vers la page depuis un hub ou article pertinent. Pas de pages orphelines.
• Données structurées qui correspondent au contenu visible : voir references/structured-data.md pour les types qui génèrent encore des résultats enrichis.
• Confiance : auteur ou organisation réel, affirmations exactes, date de dernière révision qui change lorsque le contenu change, sources pour les nombres. Ne publiez jamais d'avis ou témoignages factices — Google les traite comme une fausse déclaration.

Stockez le contenu SEO de la page en tant que données (un objet de configuration typé ou des champs CMS) plutôt que de disperser des chaînes dans JSX. Cela rend les vérifications d'unicité, les tests de longueur et les révisions en masse possibles.

Phase 4 — Portes techniques (à ne pas sauter)

Lisez references/technical-seo.md. Avant de déclarer une page terminée, confirmez dans le HTML intégré ou déployé :

• Statut 200 pour les pages réelles et un vrai 404 (pas un 200 avec le texte "non trouvé") pour les URL inconnues.
• Canonical absolu auto-référencé, et aucun canonical/robots hérité accidentellement d'une mise en page parente.
• Les pages indexables sont dans le sitemap avec un lastmod honnête ; les pages noindex ne le sont pas.
• Les pages que vous souhaitez cacher utilisent noindex (méta ou X-Robots-Tag) et ne sont pas bloquées dans robots.txt, sinon Google ne peut jamais lire le noindex.
• Le contenu principal, le H1, les réponses FAQ et les liens internes sont présents dans le HTML brut (vérification du nombre de mots et du H1 de seo_check.py).
• Un hôte préféré (https, www ou apex) avec des 301 à un seul saut depuis les autres.
• Les Core Web Vitals n'ont pas régressé (LCP ≤ 2,5 s, INP ≤ 200 ms, CLS ≤ 0,1). Pour les données de terrain, utilisez PageSpeed Insights / CrUX, ou les compétences seo-performance / seo-google si installées.

Phase 5 — Off-page et distribution

Lisez references/off-page.md. Le travail on-page rend une page éligible ; les liens et la demande de marque décident jusqu'où elle ira pour tout ce qui est concurrentiel. Planifiez l'acquisition de liens en parallèle de la page, pas après :

• Construisez un actif digne de liens par cluster (outil gratuit, repository de modèle, tableau de données, guide original).
• Soumettez aux quelques annuaires et plateformes de lancement qui correspondent à l'audience, rédigés comme de véritables articles.
• Utilisez les plateformes visuelles (Pinterest, YouTube Shorts) pour les niches visuelles ; GitHub pour les publics de développeurs.
• Configurez Bing Webmaster Tools et IndexNow (l'index de Bing alimente la recherche ChatGPT et Copilot).
• N'achetez jamais de liens, ne rejoignez pas de systèmes de liens, ou ne soumettez pas en masse à des annuaires de mauvaise qualité.

Lorsque vous ne pouvez pas effectuer le travail off-page vous-même, produisez un kit prêt à l'emploi pour l'utilisateur : liste de cibles, brouillons d'articles, brouillons d'emails de sensibilisation, et un calendrier.

Phase 6 — Vérifier, déployer, surveiller

Lisez references/measurement.md.

• Réexécutez seo_check.py sur les pages intégrées ou déployées et comparez avec la base de référence de la Phase 1. Pour les modifications de mises en page ou composants partagés, comparez chaque type de page, pas seulement celui que vous avez modifié — une modification à l'échelle du site peut silencieusement altérer des pages qui se classent déjà.
• Après le déploiement : soumettez à nouveau le sitemap, demandez l'indexation uniquement pour la poignée des nouvelles URL les plus importantes, envoyez un ping à IndexNow.
• Après 2–4 semaines : exécutez python3 <skill-dir>/scripts/gsc_opportunities.py <gsc-export.json|csv> pour lister les requêtes à portée de frappe, les pages à faible CTR et la cannibalisation, puis itérez sur les titres, les sections et les liens internes pour celles-ci.

Règles durement acquises

Celles-ci proviennent de régressions réelles. Chacune a coûté des classements ou de l'indexation avant d'être découverte.

• Vérifiez ce que les crawlers reçoivent réellement. Un spinner de chargement au niveau de la route, des imports dynamiques ssr: false, ou un fondu qui commence à opacity: 0 peuvent laisser le HTML du serveur avec seulement "Chargement…" alors que le navigateur semble parfait. Les crawlers IA n'exécutent pas JavaScript du tout.
• Les animations d'entrée cachent le héros. Les bibliothèques d'animation (framer-motion initial={{ opacity: 0 }}, AOS, GSAP) rendent leur état de départ côté serveur, donc le H1 et l'intro sont livrés invisibles jusqu'à l'hydratation, retardant le LCP. Utilisez initial={false} ou une animation CSS uniquement pour tout ce qui se trouve au-dessus de la ligne de flottaison ; grep le HTML intégré pour opacity:0.
• Les corps CMS ajoutent un deuxième H1. Le Markdown qui commence par # Titre sous un H1 au niveau de la page le duplique. Abaissez les H1 du corps en H2 dans le moteur de rendu.
• Soft 404 du SSR en streaming. Une fois qu'une réponse streamée a commencé, un notFound() ultérieur ne peut pas changer le 200. Rejetez les slugs inconnus avant le rendu (paramètres statiques avec paramètres dynamiques désactivés), ou retournez un noindex explicite depuis la branche d'absence de métadonnées.
• Canoniques hérités. Un canonical dans une mise en page racine fuit dans chaque page qui ne définit pas le sien. Un soft 404 qui l'hérite devient un doublon indexable d'une page réelle.
• "API down" n'est pas "aucun résultat". Le code qui décide notFound() ou noindex doit distinguer un échec de récupération d'un résultat vide, ou une panne désindexe des pages réelles.
• Contenu caché. Les accordéons qui démontent les panneaux fermés suppriment les réponses FAQ du HTML. Gardez-les montés (hidden="until-found" ou CSS) afin qu'ils soient explorables et trouvables par la recherche dans la page.
• Les composants partagés sont un rayon d'explosion. Lorsqu'une page se classe bien, modifiez les composants SEO partagés derrière des props d'adhésion et comparez le HTML intégré des autres pages avant et après.
• Évaluations ou témoignages fabriqués. Un nombre d'étoiles dur ou un témoignage collé à partir d'un autre site sont une fausse déclaration dès leur publication. Supprimez-les ou rendez-les réels.

Fichiers de référence

• references/keyword-research.md — Recherche et cartographie des mots-clés
• references/on-page.md — Contenu de page, titres, méta, FAQ, liens internes, données structurées
• references/technical-seo.md — Indexabilité, rendu, canoniques, sitemaps, robots, performances
• references/structured-data.md — Types de schéma qui valent la peine d'être implémentés
• references/off-page.md — Acquisition de liens, distribution, lancement
• references/measurement.md — Suivi Search Console, opportunités GSC, itération

Scripts

• scripts/seo_check.py — Auditeur de page unique / par lot
• scripts/gsc_opportunities.py — Analyse d'exportation Search Console pour les requêtes à portée de frappe et la cannibalisation

Dépendances et installation

Si vous installez ce skill pour la première fois :

pip install requests beautifulsoup4 lxml

Les scripts s'exécutent en Python 3 et nécessitent les modules ci-dessus. Les chemins sont relatifs au répertoire du skill ; lorsqu'ils sont invoqués depuis un répertoire de projet, utilisez <chemin-vers-skill>/scripts/seo_check.py.