SEO Monitoring

seo-monitoring : résumé de performance (GSC)

Le compteur du système : produit chaque semaine l'état mesuré du référencement du client (positions, clics, impressions, mouvements) sous forme d'un snapshot JSON daté + un rapport client en français.

Division du travail : monitoring RÉSUME la performance (ce qui s'est passé) ; content-refresh ANALYSE ce qui est optimisable (decay, stagnation, opportunités) en lisant les exports et l'historique déposés ici. Aucun check n'existe dans les deux skills, et la GSC n'est collectée qu'une fois, ici.

Règle universelle : aucune entreprise, domaine ou mot-clé n'est hardcodé. Tout vient de clients/<slug>/client.json, du contexte client et de outputs/monitoring/keywords.json.

Source de données : la GSC, et rien d'autre

La Search Console est la seule source de ce skill : ce sont les données réelles de Google (positions moyennes, clics, impressions, CTR), gratuites et à la source. Aucun fallback : tant que la GSC du client n'est pas connectée, le monitoring est "en attente de connexion GSC" et le rapport le dit tel quel. On ne remplace jamais des données mesurées par des estimations tierces.

Deux conséquences pratiques :

• Un export marqué _simulated: true (réserve de démo seo-collect) produit un snapshot marqué simulated, jamais présenté à un client.
• Le jour où la GSC est branchée, le premier run crée la baseline ; les mouvements apparaissent au deuxième.

Architecture hybride : deux couches

1. Couche agent (CE SKILL.md) : récupérer les données GSC (gsc-mcp), les déposer en export daté, maintenir la watchlist, rédiger le rapport.
2. Couche script (scripts/monitor.py) : le diff mécanisable. État de la watchlist, mouvements vs snapshot précédent (positions avec seuil ±2, % de clics avec garde-fou baseline ≥20), mouvements par page, totaux, historique par mot-clé.

Procédure de l'agent

Étape 1 : déposer l'export GSC du run

Récupérer via gsc-mcp, sur site_url = client.gsc_property, les 28 derniers jours :

• par query (get_search_analytics, dimension query, ~250 lignes max) : query, clicks, impressions, ctr, position ;
• par page (dimension page, ~100 lignes) : page, clicks, impressions, ctr, position.

Écrire outputs/monitoring/gsc-YYYY-MM-DD.json :

{
  "gsc_property": "sc-domain:...",
  "date": "YYYY-MM-DD",
  "period_days": 28,
  "queries": [{"query": "...", "clicks": 0, "impressions": 0, "ctr": 0.0, "position": 0.0}],
  "pages": [{"page": "https://...", "clicks": 0, "impressions": 0, "ctr": 0.0, "position": 0.0}]
}

(Le script accepte aussi le format de la réserve seo-collect : top_queries / top_pages.)

GSC non connectée pour ce client : ne rien déposer, lancer quand même le script (il sort en code 2 avec le message "en attente de connexion GSC") et le signaler dans le rapport ou sur la carte. C'est la SEULE réponse correcte : pas de source de remplacement.

Étape 2 : maintenir la watchlist outputs/monitoring/keywords.json

La GSC remonte toutes les queries qui génèrent des impressions ; la watchlist sert à suivre nommément les mots-clés STRATÉGIQUES, y compris ceux qui n'impriment pas encore (pages à créer). Seed au premier run depuis :

1. La stratégie de contenu (outputs/keyword/<date>/strategy.md ou .json) : mot-clé cible de chaque page à créer et quick win.
2. Les contenus produits (outputs/content/*/) : mot-clé principal de chaque brief/article, target_url une fois publié.
3. Les demandes du owner ou du client.

Format :

{
  "keywords": [
    {"keyword": "...", "target_url": "https://... ou null", "source": "strategy|article|owner"}
  ]
}

À chaque run : ajouter les nouveaux contenus publiés. Retirer uniquement sur demande explicite (l'historique d'un mot-clé retiré reste dans history.json). Un mot-clé de watchlist absent des queries GSC = "pas d'impressions" (pas encore visible), ce qui est une information en soi.

Étape 3 : lancer le socle script

python seo/skills/seo-monitoring/scripts/monitor.py <slug>
python seo/skills/seo-monitoring/scripts/monitor.py <slug> --force

Idempotent par jour (snapshot déjà présent : le script s'arrête, --force pour relancer). Coût : zéro, la GSC est gratuite.

Étape 4 : rédiger le rapport de performance

Écrire outputs/monitoring/rapport-YYYY-MM-DD.md, en français, dans la voix du système (sobre, chiffres et URLs, pas d'adjectifs). C'est un RÉSUMÉ de ce qui s'est passé, pas une liste de recommandations :

1. Vue d'ensemble : clics et impressions de la période, X mots-clés suivis dont Y avec position et Z en page 1, snapshot comparé.
2. Mouvements queries (jugement, pas un dump du JSON) : entrées en page 1, progressions et chutes notables, sorties, premiers signes de vie des contenus publiés (impressions qui démarrent). Ignorer le bruit (±1 position, volumes faibles).
3. Mouvements pages : les pages qui ont gagné ou perdu des clics de façon significative.
4. Pipeline de contenu : les mots-clés de la watchlist qui n'impriment pas encore (les pages à créer/venir), sans en tirer de conclusion avant plusieurs runs.

Si une analyse d'optimisation est demandée ("qu'est-ce qu'on améliore ?"), ce n'est pas ce rapport : pointer vers /content-refresh scan <client> qui lit ces mêmes données et produit la queue priorisée.

Jamais : présenter des données simulées comme réelles, promettre des résultats futurs, extrapoler une tendance depuis 2 snapshots, conclure sur un mot-clé à moins de 10 impressions.

Tools (harness-aware)

En Claude Code : ToolSearch: "select:mcp__gsc-mcp__get_search_analytics" (et get_search_by_page_query pour le détail d'une page). Dans les autres harness (Hermes inclus) : l'accès GSC équivalent configuré pour le client. Pas d'accès GSC = code 2 = monitoring en attente, on n'improvise pas une autre source.

Contrat

Entrée : client.json (gsc_property) + export GSC déposé par l'agent. Sorties :

Consommateurs : content-refresh (source 1 de son scan : exports, snapshots et history déposés ici, il ne re-fetch jamais la GSC), le futur récap hebdomadaire (lit history.json + le dernier rapport).

Sur Hermes

Scheduled job hebdomadaire sur le profil worker SEO : "Run /seo monitoring : dépose l'export GSC, lance le script, rédige le rapport". Le lancer AVANT le scan refresh de la semaine (le scan lit l'export du monitoring). Le rapport peut être déposé en commentaire d'une carte dédiée "Monitoring" du board (visible client), jamais créer une carte par mouvement. Tant que la GSC du client n'est pas connectée, le job tourne et rapporte "en attente de connexion GSC" : le branchement GSC est le seul déclencheur qui active les chiffres.