Que fait Heraut SEO ?
Le heraut (héraut) est celui qui fait connaître un domaine au monde. Quand personne ne l'entend, cette skill enquête sur les raisons, avec une preuve pour chaque affirmation, et renvoie un plan que le propriétaire peut exécuter dans l'ordre.
Elle est née d'un cas réel : un site avec 58 000 URL et 1 000 articles générés, un pilote de contenu dépensant chaque jour, zéro impression de blog. La réponse ne se trouvait pas là où le pilote regardait (réécriture de pages) mais dans la qualité, l'autorité et la demande au niveau du site. La méthode ci-dessous est conçue pour trouver ce genre de réponse plutôt que de confirmer la première hypothèse.
Les règles
- Lecture seule, partout. Aucun changement en production, aucune écriture en base de données, aucun redémarrage, rien soumis à Google (pas de demande d'indexation, pas de sitemap ajouté ou supprimé). L'enquête décrit ; le plan est appliqué plus tard, un changement décidé à la fois.
- Preuve pour chaque affirmation. Commande, nombre, date, fichier. Marquer ce qui est MESURÉ et ce qui est SUPPOSÉ. Un échantillon n'est pas un comptage : donner n.
- Soigner le site. Une requête à la fois, une pause d'au moins 1,5 s (
politesse.delai_s). Les petits serveurs souffrent lors des audits. - API payantes derrière un plafond.
budgets.dataforseo_usdetbudgets.perplexity_usdsont respectés par les scripts avant chaque appel ; chaque coût est enregistré. Signaler le total dépensé. - Aucun secret dans les sorties. Nommer l'endroit où une clé se trouve, jamais sa valeur. Les scripts lisent les clés depuis l'environnement ou depuis des fichiers env nommés dans la configuration.
Où se trouvent les choses
Scripts dans scripts/ (généralement ~/.claude/skills/heraut-seo/scripts), bibliothèque standard Python uniquement, openssl pour les tokens Google. Chaque script prend --config <site.json> --dossier <dossier d'enquête> et écrit du CSV et du JSON, plus un resume.json à lire en premier.
| Script | Piste | Ce qu'il fait |
|---|---|---|
sitemap.py | code | arbre complet du sitemap, chaque URL typée et langues, honnêteté du lastmod, doublons |
gsc.py performance | 16 mois par mois et type de page, 28 jours vs précédent, requêtes, pays, sections | |
gsc.py sitemaps | sitemaps soumis, erreurs, en attente, dernière lecture par Google | |
gsc.py echantillon / inspecter / analyser | Inspection d'URL stratifiée (quota 2000/jour, reprenable), couverture par type, évolution depuis un précédent run | |
ga4.py | canaux sur un an, Google organique alors et maintenant, assistants IA, part robot-like | |
pages.py | code | lecture des pages d'un échantillon : langue, canonique, hreflang, robots, mots, JSON-LD, liens vers le blog, Googlebot vs navigateur |
logs.py | serveur | vrai Googlebot (DNS vérifié) par jour, par type, gaspillage, temps de réponse, première visite des URL suivies |
ttfb.py | serveur | time to first byte par type, chaud, froid et origine |
dataforseo.py | externe | SERPs réelles, mots-clés classés, backlinks du site et des concurrents, volumes, bilan |
perplexity.py | externe | recherche approfondie datée et sourcée (Agent API, effort) |
L'enquête, étape par étape
0. Cadrage (10 minutes, avec le propriétaire si nécessaire)
- Écrire la question du propriétaire avec ses mots, et les symptômes avec des chiffres (impressions, clics, articles publiés, argent dépensé).
- Trouver ce qui est déjà connu : audits précédents, notes, le pipeline de contenu et sa base de données. Les traiter comme des hypothèses à vérifier, pas comme des faits à recopier.
- Construire le fichier site à partir de
config.example.json: domaine, sitemap, langues, types de pages sous forme d'expressions régulières de chemin (la partie la plus importante : chaque comptage est par type), sections à suivre (le blog), propriété Search Console, identifiant GA4, chemin de la clé du compte de service, marchés (codes de localisation DataForSEO), 3 à 6 concurrents, 15 à 30 requêtes réelles que les gens taperaient, budgets. - Vérifier l'accès avant de commencer :
gsc.py sitemapsrépond, GA4 répond, les logs sont lisibles (souvent seulement par root et le groupeadm: demander au propriétaire, ne jamais contourner un refus).
1. Quatre pistes en parallèle
Créer le dossier enquete-YYYY-MM-DD/ à côté des autres fichiers d'audit du site, y écrire BRIEF.md à partir de references/brief.md, puis lancer quatre investigateurs (sous-agents) à la fois, chacun avec le brief et son fichier de piste. Chacun écrit volet-<piste>.md avec un résumé de 10 lignes en haut, et ses données brutes à côté.
| Piste | Fichier | Question clé |
|---|---|---|
| references/track-google.md | Est-ce que Google connaît les pages, les explore, les conserve ? Est-ce que ça s'améliore ou empire ? | |
| Serveur | references/track-server.md | Est-ce que le vrai Googlebot vient, que lit-il, y a-t-il quelque chose qui le ralentit ou le bloque ? |
| Code et contenu | references/track-code-content.md | Que trouve Google quand il lit le site : combien de pages, quelle finesse, quel maillage, quelle honnêteté ? |
| Externe | references/track-outside.md | Qui gagne les vraies recherches, avec quelle autorité, et y a-t-il une demande pour ce que le site écrit ? |
Exécuter sitemap.py en premier (les autres échantillonnent à partir de lui), puis les pistes. gsc.py inspecter peut prendre des heures sur un échantillon complet : l'exécuter en arrière-plan.
2. Synthèse
Lire les quatre rapports, puis construire la réponse avec references/cause-tree.md : il liste les causes observées en pratique, la mesure qui confirme ou exclut chacune, et les pièges (un audit technique qui revient propre ne signifie pas que le site va bien).
Écrire le rapport selon references/report.md : réponse courte d'abord, situation, complication, question, arbre des causes avec les preuves sur chaque branche, pourquoi le programme actuel ne fonctionne pas, le plan par phases avec un « fait quand » pour chaque étape, KPIs à 30, 60, 90 jours, décisions pour le propriétaire, limites de l'enquête, sources. Le publier sous forme de page quand la session le permet (privée par défaut), sinon sous forme de fichier HTML.
3. Passation
- Donner au propriétaire le lien, le diagnostic central en cinq lignes, le coût de l'enquête, ce qui n'a pas pu être mesuré.
- Ensuite les décisions, une à la fois, chacune avec le fait qui la sous-tend et une recommandation. Appliquer chaque étape décidée avant de demander la suivante.
- Sauvegarder le verdict et la règle de fonctionnement qu'il implique (par exemple « pas de nouveau contenu avant que les pages centrales soient indexées ») là où le projet conserve sa mémoire.
L'exécuter sur un autre serveur ou site
Installer la skill sur la machine qui a les accès (clé Search Console, logs), copier config.example.json dans le dossier du site, le remplir, exécuter les étapes 0 à 3. Conserver un dossier par date d'enquête pour que la prochaine exécution puisse comparer : gsc.py analyser --avant <old inspection.jsonl> montre URL par URL ce qui est entré ou sorti de l'index.
Ré-exécuter l'enquête 60 à 90 jours après le début du plan. Entre les exécutions, une inspection quotidienne tournante de 50 à 100 URL est le moyen le plus économique de voir l'index bouger.
Ce que cette skill ne fait pas
Elle ne modifie pas le site, n'écrit pas de contenu, ne demande pas d'indexation, ni n'achète de liens. Elle ne juge pas le produit ou le modèle économique, seulement si la recherche peut y amener des visiteurs. Les scores des outils SEO (rank, spam score, trafic estimé) sont des modèles, pas des mesures : le dire quand on les cite.