jdevalk/skills - SEO statique

SEO Statique

Audite et améliore la configuration SEO d'un site HTML statique selon neuf catégories — métadonnées d'en-tête, données structurées, qualité du contenu, images Open Graph, plans de site et indexation, découverte par les agents, performances, redirections et validation CI. Les recettes sont neutres en matière de plateforme : balises <meta> brutes, JSON-LD brut, sitemap.xml fait main, outils CI génériques. Le cadre d'audit est parallèle à celui de astro-seo mais sans la colonne vertébrale @jdevalk/astro-seo-graph.

Les recettes de code se trouvent dans AGENTS.md — lisez-le lorsque vous devez implémenter un correctif spécifique. Ce fichier contient le workflow et la liste de contrôle d'audit.

Workflow

1. Détecter le projet — confirmez qu'il s'agit d'un site statique, identifiez l'outil de construction, trouvez où appliquer les modifications.
2. Auditer — notez neuf catégories et produisez des conclusions exploitables.
3. Améliorer — générez ou modifiez des fichiers pour combler les lacunes. Les recettes se trouvent dans AGENTS.md.
4. Passage des métadonnées — invoquez metadata-check sur chaque chaîne courte générée par le skill (titres, descriptions, champs description du schéma, réponses FAQ).
5. Vérifier — exécutez toute construction, validez la sortie, rappelez à l'utilisateur les tâches non liées aux fichiers (Search Console, Bing Webmaster Tools, soumission de clé IndexNow).

---

Phase 0 : Détecter le projet

Confirmez les bases avant d'auditer :

• Il s'agit bien d'un site statique. Recherchez du HTML construit — index.html à la racine du dépôt, ou sous _site/ (Jekyll), public/ (Hugo / 11ty / Gatsby), dist/ (Vite / Astro statique), out/ (Next.js avec output: export). Si tout est rendu par le serveur (Express, PHP, routes dynamiques), ce n'est pas le bon skill — dirigez vers astro-seo pour Astro, wp-readme-optimizer pour les pages de plugins WP, ou recommandez un audit SEO générique.
• Outil de construction source. Détermine où appliquer les modifications des métadonnées d'en-tête :
  • _config.yml / _layouts/ → Jekyll
  • config.toml / config.yaml / themes/ → Hugo
  • .eleventy.js / _includes/ → 11ty
  • gatsby-config.js / src/components/SEO.* → Gatsby
  • next.config.js avec output: 'export' et pages/_document.tsx → Next.js export statique
  • astro.config.mjs → Astro (auquel cas utilisez astro-seo à la place)
  • Pas de configuration de construction, seulement des fichiers HTML → fait main ou extrait (par exemple, sortie de wp-static-clone). Modifiez le HTML directement ou utilisez un script de post-traitement.
• URL canonique du site. Recherchez l'origine de production dans le dépôt — généralement dans _config.yml, config.toml, astro.config, ou codée en dur dans une mise en page. Si elle est manquante, vide ou localhost, signalez-la comme un problème bloquant avant toute autre chose. Les canoniques, les plans de site, les URL d'images OG et les valeurs @id du JSON-LD en dérivent tous.
• Cible de déploiement. Lisez vercel.json, netlify.toml, wrangler.toml, ou public/_headers pour déterminer l'hôte. Détermine la syntaxe des redirections et des en-têtes dans la Phase 2.
• Le site est-il multilingue ? Vérifiez les sous-répertoires de locale (/en/, /nl/, /de/) ou la configuration i18n de l'outil de construction. Si oui, hreflang est important ; si non, ignorez-le.
• Qu'est-ce qui est déjà dans <head> ? Ouvrez un fichier HTML construit et inventorier : titre, description, canonique, robots, Open Graph, cartes Twitter, JSON-LD, hreflang. L'audit de la Phase 1 est plus rapide si vous pouvez référencer ce qui est présent.

Ne demandez que ce que vous ne pouvez pas détecter.

---

Phase 1 : Audit

Notez chaque catégorie sur 10. Pour chacune, donnez 2 à 4 conclusions spécifiques qui citent le HTML, la configuration ou le modèle réel. Au sein de chaque catégorie, les vérifications sont hiérarchisées :

• Obligatoire — bloqueurs de livraison. Un échec provoque une régression SEO visible.
• Recommandé — pratique standard. Ignorer coûte de la portée.
• Accessoire — tourné vers l'avenir ou situationnel. Utile mais pas fondamental pour tous les sites.

Ignorez les vérifications Accessoire pour les petits sites personnels, sauf si l'utilisateur demande le traitement complet.

1. Métadonnées d'en-tête (/10)

• Obligatoire — chaque page a un <title> et un <meta name="description">.
• Obligatoire — <link rel="canonical"> défini, avec les paramètres de suivi supprimés, dérivé de l'origine de production.
• Obligatoire — canonique omis lorsque la page est noindex (selon la recommandation de Google).
• Obligatoire — longueur du <title> 30-65 caractères, longueur du <meta name="description"> 70-200 caractères (les limites de troncature SERP ; identiques aux valeurs par défaut de metadata-check).
• Recommandé — <meta name="robots"> inclut max-snippet:-1, max-image-preview:large, max-video-preview:-1.
• Recommandé — Open Graph (og:title, og:description, og:image, og:url, og:type, og:site_name) sur chaque page.
• Recommandé — les balises Twitter Card (twitter:card) sont supprimées lorsqu'elles dupliquent Open Graph (Twitter revient automatiquement en arrière).
• Recommandé — alternatives hreflang sur les sites multilingues. Ignorer si monolingue.
• Recommandé — un seul <meta name="robots"> et un seul og:image par page (les outils hérités émettent parfois des doublons).

2. Données structurées / JSON-LD (/10)

• Obligatoire — au moins un bloc <script type="application/ld+json"> sur chaque page importante.
• Recommandé — @graph lié plutôt qu'un objet Article plat — entités connectées avec des références @id afin qu'un BlogPosting puisse pointer vers son auteur Person et son parent WebPage.
• Recommandé — WebSite, Blog / WebPage, Person / Organization, BlogPosting / Article, BreadcrumbList, ImageObject tous présents là où c'est pertinent.
• Recommandé — signaux de confiance : publishingPrinciples, copyrightHolder, copyrightYear, knowsAbout, SearchAction.
• Obligatoire — valide dans Rich Results Test et ClassySchema.

3. Qualité du contenu (/10)

• Obligatoire — chaque page a un <title> et un <meta name="description"> uniques (pas de métadonnées en double sur le site).
• Obligatoire — exactement un <h1> par page.
• Recommandé — <title> et <meta name="description"> audités via metadata-check (Phase 2.5) pour le chargement précoce, la concrétude et l'adéquation SERP.
• Recommandé — prose du corps audité via readability-check pour les articles longs individuels (ne pas auditer en masse).
• Recommandé — chaque <img> a un attribut alt (ou alt="" / role="presentation" pour les images décoratives).
• Recommandé — les liens internes utilisent des chemins relatifs à la racine (/foo/) et non absolus (https://...) — survit aux changements de domaine et aux prévisualisations.

4. Images Open Graph (/10)

• Obligatoire — chaque page a une image OG.
• Obligatoire — 1200×675 (Google Discover minimum 1200px de large, rapport 16:9).
• Recommandé — JPEG (les plateformes sociales ne prennent pas en charge WebP / AVIF de manière fiable pour OG).
• Recommandé — générée au moment de la construction (satori-cli, sharp, ImageMagick, Vercel OG, Bannerbear) plutôt que téléchargée manuellement par page — évite la dérive.
• Recommandé — URL dérivée de manière déterministe à partir du slug (par exemple /og/<slug>.jpg) afin que l'ajout d'une page obtienne automatiquement une image.
• Recommandé — chaque <img> dans le contenu du corps a un attribut alt (ou alt="" / role="presentation"). Validé en CI via html-proofer ou similaire.

5. Plans de site et indexation (/10)

• Obligatoire — /sitemap.xml (ou /sitemap_index.xml pour les plans de site fractionnés) accessible, XML valide, chaque URL renvoie 200.
• Obligatoire — robots.txt présent à la racine du site et référence le plan de site.
• Obligatoire — flux RSS existant, annoncé via <link rel="alternate" type="application/rss+xml">, contient le contenu complet des articles (pas d'extraits tronqués).
• Recommandé — fractionné par section si le site a plusieurs types de contenu (sitemap-posts.xml, sitemap-pages.xml) — plus facile à déboguer l'indexation dans GSC.
• Recommandé — <lastmod> renseigné à partir des horodatages des commits git (le plus précis), des horodatages de construction (acceptable), ou des dates de frontmatter (en dernier recours). Le mtime du système de fichiers provenant d'un checkout CI est erroné — c'est la date du checkout, pas la date du contenu.
• Recommandé — IndexNow intégré. Clé de vérification sous forme de route statique /<key>.txt à la racine du site, plus un hook de construction ou de déploiement qui POSTe les nouvelles URL vers https://api.indexnow.org/IndexNow. Conditionnez la soumission sur l'hôte de production (par exemple CF_PAGES_BRANCH=main, VERCEL_ENV=production, CONTEXT=production) — une soumission inconditionnelle envoie des pings à l'endpoint depuis des constructions locales avec des URL que l'hôte de production n'a pas encore servies, ce qui marque la clé comme invalide (403) et force la rotation.

6. Découverte par les agents (/10)

• Recommandé — endpoints de schéma (/schema/<type>.json) exposant du JSON-LD à l'échelle du corpus par type de contenu. Fichiers JSON statiques commités dans le dépôt ou régénérés par la construction.
• Recommandé — carte de schéma (/schemamap.xml) listant chaque endpoint de schéma, avec la directive Schemamap: dans robots.txt.
• Recommandé — llms.txt à la racine du site listant les pages (titre + description) pour les consommateurs LLM. Fichier texte statique ; une ligne par page.
• Recommandé — URL alternatives en markdown (/blog/post.md à côté de /blog/post/) servant du markdown propre avec frontmatter YAML afin que les agents IA puissent consommer le contenu sans analyser le HTML. Soit commitez les fichiers .md frères, soit utilisez une règle de transformation Cloudflare + Vary: Accept pour la négociation de contenu (les pages CF suppriment les en-têtes Vary personnalisés, utilisez donc la réécriture d'URL de la règle de transformation seule — recette dans AGENTS.md).
• Recommandé — catalogue d'API à /.well-known/api-catalog selon RFC 9727, en tant que application/linkset+json (RFC 9264). Liste les endpoints de schéma, la carte de schéma, le flux RSS et toutes les API spécifiques au site. Fichier JSON statique.
• Recommandé — directive Content Signals dans robots.txt (Content-Signal: ai-train=yes, search=yes, ai-input=yes ou votre politique préférée). Une ligne, brouillon IETF, faible coût.
• Recommandé — en-tête Link sur /* pointant vers les fichiers de découverte (plan de site, llms.txt, api-catalog, schemamap). Les agents lisant les en-têtes de réponse les trouvent sans analyser le HTML. Spécifique à l'hôte (_headers sur Cloudflare Pages / Netlify, vercel.json sur Vercel, configuration serveur ailleurs).
• Accessoire — carte de serveur MCP à /.well-known/mcp/server-card.json et/ou carte d'agent A2A à /.well-known/agent-card.json. Pertinent uniquement lorsque le site expose un serveur MCP ou un agent A2A.
• Accessoire — <link rel="nlweb"> pointant vers un endpoint conversationnel. L'adoption du NLWeb est précoce ; la balise est une ligne et vaut la peine d'être incluse, mais ce n'est pas un bloqueur de notation en 2026.
• Accessoire — catalogue ARD (Agentic Resource Discovery) à /.well-known/ai-catalog.json, listant ce que le domaine offre (serveur MCP, agent A2A, bundle OKF, API spécifiques au site). Brouillon v0.9, donc facultatif — mais c'est la couche de découverte à travers laquelle les cartes MCP / A2A et le bundle OKF produisent des résultats. Deux pièges : la spécification de base (Agent-Card/ai-catalog) nomme le champ media-type mediaType tandis que la couche ARD (ards-project/ard-spec) le nomme type — émettez les deux clés avec la même valeur afin que l'entrée soit valide sous l'une ou l'autre lecture (les deux spécifications exigent que les consommateurs ignorent les clés inconnues). ARD ajoute également un tableau facultatif representativeQueries d'exemples de requêtes par entrée. Fichier JSON statique.
• Accessoire — bundle OKF (Open Knowledge Format) : une arborescence de fichiers de concepts Markdown typés (un par page, chemins reflétant les URL canoniques) emballée sous forme d'un seul .tar.gz, avec des fichiers d'index entre les deux. Le service et la découverte sont explicitement des non-objectifs d'OKF — c'est à cela que sert l'entrée du catalogue ARD. Brouillon v0.9, facultatif. Il n'y a pas encore de type média enregistré, donc la chaîne provisoire est application/okf-bundle+gzip (suivi dans knowledge-catalog#111 et ard-spec#27) ; marquez-la comme provisoire, elle peut changer. Il est préférable de le générer à partir de la même source que le reste du site plutôt que d'une copie maintenue manuellement.

7. Performances (/10)

• Obligatoire — les ressources hachées servent Cache-Control: public, max-age=31536000, immutable (ou équivalent) afin qu'elles ne soient téléchargées qu'une seule fois.
• Recommandé — police web principale préchargée en woff2 via <link rel="preload" as="font" crossorigin>.
• Recommandé — en-tête de réponse No-Vary-Search supprime les paramètres UTM de la clé de cache (afin que /?utm_source=x et / partagent une entrée de cache).
• Recommandé — aucun JavaScript bloquant le rendu sur la première peinture (différez ou asynchronisez les scripts non critiques).
• Recommandé — les images utilisent des formats modernes (WebP / AVIF pour le contenu de la page ; JPEG uniquement pour les cartes OG) et loading="lazy" en dessous de la ligne de flottaison.
• Recommandé — tous les Core Web Vitals Lighthouse / PageSpeed dans le vert : LCP < 2,5 s, INP < 200 ms, CLS < 0,1.

8. Redirections et gestion des erreurs (/10)

• Obligatoire — _redirects / vercel.json / configuration serveur maintenus pour chaque URL qui a jamais existé et a été déplacée.
• Obligatoire — 301 et non 302 pour les déplacements permanents.
• Obligatoire — 404.html (ou équivalent) renvoie un statut 404, pas 200. Vérifiez avec curl -I sur une URL délibérément erronée.
• Recommandé — suggestion de correspondance floue sur la page 404 (« vouliez-vous dire… ? ») pour les fautes de frappe dans les URL. Implémentation statique : pré-construisez un index JSON des slugs valides, correspondance floue côté client.

9. Validation CI (/10)

• Obligatoire — vérificateur de liens brisés en CI. linkinator ou lychee sur chaque push qui touche au contenu. Liens internes et externes — les internes attrapent les régressions de construction, les externes attrapent la pourriture des liens. Planifiez une exécution hebdomadaire pour les vérifications externes uniquement.
• Recommandé — validation HTML via html-proofer ou W3C Validator — attrape le balisage mal formé qui casse les robots d'exploration.
• Recommandé — Lighthouse CI sur chaque push, avec des seuils de score (par exemple SEO ≥ 95, Performance ≥ 80).
• Recommandé — validation JSON-LD en CI via le validateur JSON-LD Schema.org (pas de CLI officielle ; passez par un script Node qui POSTe vers l'API).
• Recommandé — validation de la longueur des titres et descriptions en CI : un petit script qui parcourt le HTML construit, extrait <title> et <meta name="description">, signale tout ce qui est hors limites.

---

Phase 2 : Améliorer

Appliquez les recettes correspondant aux éléments de la phase 1 notés en dessous de 7/10. Les recettes de code détaillées se trouvent dans AGENTS.md. Principes généraux :

• Préférez les approches basées sur la construction aux approches manuelles (par exemple, générateur d'images OG dans le pipeline de construction plutôt que téléchargement manuel).
• Utilisez la configuration de l'outil de construction lorsque c'est possible ; revenez au HTML statique uniquement lorsque la configuration ne peut pas exprimer la balise (par exemple, og:image dans la configuration Hugo).
• Si le site est multilingue, traitez chaque langue de manière indépendante et marquez les URL alternatives (ne placez pas de contenu japonais dans le flux RSS allemand).

---

Phase 2.5 : Vérification des métadonnées

Exécutez metadata-check sur chaque titre de page, description, champ description du schéma et réponse FAQ que vous avez généré. Cela attrape les erreurs de casse, les doublons, les valeurs trop courtes / trop longues et le bourrage de mots-clés. Il s'agit d'une opération distincte car les correctifs SEO passent parfois par une chaîne d'outils (par exemple, générateur de titre dans la construction → fichier de locale → modèle) qui peut introduire des régressions longtemps après la Phase 2.

---

Phase 3 : Vérifier

1. Construisez le site (jekyll build, hugo, npx @11ty/eleventy, npx gatsby build, npm run build, etc.).
2. Vérifiez la sortie — ouvrez un échantillon de pages construites, confirmez que les balises <head> apparaissent comme prévu.
3. Validez le plan de site — curl <site>/sitemap.xml et confirmez qu'il est bien formé et couvre les pages.
4. Vérifiez robots.txt — accessible, référence le plan de site.
5. Rappelez à l'utilisateur que certaines tâches SEO ne sont pas dans le dépôt et doivent être effectuées manuellement :
   • Soumettre le plan de site à Google Search Console.
   • Soumettre le plan de site à Bing Webmaster Tools.
   • Configurer la clé de vérification IndexNow dans le fournisseur de domaine / DNS (si applicable).
   • Vérifier les redirections de domaine (le cas échéant).
   • Ajouter un en-tête hsts pour les certificats SSL.

⚠️ Ne modifiez pas les fichiers de configuration de déploiement (ex. vercel.json, netlify.toml) sans confirmer avec l'utilisateur qu'ils sont prêts à accepter un changement de configuration. Ce fichier contrôle la configuration de production.

---

Résumé des raccourcis

• Jekyll — _config.yml pour les valeurs globales, _layouts/default.html (ou similaire) pour les balises <head>.
• Hugo — config.toml / config.yaml pour les paramètres, themes/<theme>/layouts/_default/baseof.html pour le modèle <head>.
• 11ty — .eleventy.js pour la configuration, _includes/layout.njk (ou similaire) pour les balises <head>.
• Gatsby — gatsby-config.js pour les métadonnées du site, src/components/SEO.jsx (ou similaire) pour le composant <head>.
• Next.js statique — next.config.js avec output: 'export', pages/_document.tsx pour les balises <head> globales.
• HTML pur / WordPress statique — écrivez directement dans un fichier de mise en page central ou utilisez un script de post-traitement (par exemple, un court script Node qui parcourt la sortie construite et injecte des balises).

---

Documentation complète des recettes dans AGENTS.md.