feat(seo/geo): split into parallel seo + geo agents with shared resources

Refactor the monolithic seo-analyzer into two specialist agents orchestrated in parallel by the /seo skill, plus a standalone /geo skill for AI-only audits. Changes - agents/seo-analyzer.md: refocused on classical engines (Google, Bing, DuckDuckGo). Adds Core Web Vitals 2.0 (LCP/INP/CLS + VSI), CSP + full security headers, hreflang audit, video SEO (transcripts), accessibility as ranking signal, image/video sitemaps. - agents/geo-analyzer.md: new agent for AI engines (ChatGPT, Claude, Perplexity, Gemini, Google AI Overviews, Copilot). Covers AI crawler policy, llms.txt/llms-full.txt, Schema.org for AI extraction (QAPage, Speakable, Person+Article, Organization graph), entity SEO (Wikidata, sameAs, Knowledge Panel), content shape (Definition Lead, TL;DR, Q->A, citable stats, freshness), AI visibility testing. - agents/resources/: shared knowledge base referenced by both agents — ai-crawlers-2026.md (25+ bots, training vs retrieval categories, permissive/restrictive templates), llms-txt-template.md, geo-schemas.md (incl. deprecated list: ClaimReview, CourseInfo, etc. removed June 2025), entity-seo.md, content-shape-for-ai.md, ai-visibility-tools.md, automation-catalog.md. - skills/seo/SKILL.md: becomes parallel dispatcher. Collects context once (depth + business), spawns both agents in a single message for concurrent execution, merges envelopes into unified SEO.md. Includes authoritative file-ownership matrix to prevent parallel-edit races. - skills/geo/SKILL.md: new standalone wrapper for GEO-only audits. Scoring - Combined score: GLOBAL = 0.80 * SEO + 0.20 * GEO (local B2C), 0.75 * SEO + 0.25 * GEO (SaaS/national/content). - GEO axis weight raised from 5% (old) to first-class dimension. Policy - AI crawlers: permissive default (maximise AI citations). Restrictive template available for premium/regulated content. - Every user action in SEO.md section 11 must cite automation options from automation-catalog.md. Tools - WebFetch + WebSearch added to allowed-tools of both skills and both agents (needed for live CWV via PageSpeed API, AI visibility testing, Wikidata/Knowledge Panel lookups, competitor analysis). Research basis (2026 state of the art validated via WebSearch): - Core Web Vitals 2.0 (VSI signal, Google core update March 2026) - AI Overviews trigger on ~48% of Google searches - ClaimReview + 6 other schema types deprecated June 2025 - Definition Lead Architecture (CMU KDD 2024, +impression score) - Citations + stats add up to 40% AI visibility (Aggarwal 2024) - Wikidata grounds every major LLM (ChatGPT, Claude, Gemini, Perplexity) Backup - agents/seo-analyzer.md.bak kept for rollback reference. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-21 16:16:30 +02:00
parent 53d04db480
commit 95347d2e47
13 changed files with 4003 additions and 499 deletions
@@ -1,15 +1,24 @@
 ---
 name: seo
 description: |
-  Full SEO audit and optimization for any web project. Detects framework,
-  audits all SEO signals (meta, OG, structured data, sitemap, robots.txt,
-  headings, alt attrs, canonicals, hreflang), applies fixes directly in code,
-  and generates a strategic SEO guide.
+  Full SEO + GEO audit and optimization for any web project.
+  Runs the seo-analyzer (classical search — Google, Bing, DuckDuckGo)
+  and geo-analyzer (AI search — ChatGPT, Perplexity, Claude, Gemini,
+  Google AI Overviews, Copilot) IN PARALLEL, then consolidates their
+  output into a unified SEO.md report.
+  Covers: meta, OG, JSON-LD (classical + GEO-optimised schemas),
+  sitemap, robots.txt (including AI crawlers), llms.txt, headings,
+  alt attrs, canonicals, hreflang, Core Web Vitals, entity SEO
+  (Wikidata, sameAs, Knowledge Panel), content shape for AI extraction,
+  AI visibility monitoring.
  Trigger: "seo", "referencement", "optimize for search", "audit SEO",
  "meta tags", "structured data", "JSON-LD", "sitemap", "robots.txt",
-  "Google ranking", "local SEO", "referencement local", "fiche Google".
+  "Google ranking", "local SEO", "referencement local", "fiche Google",
+  "AI search", "GEO", "llms.txt", "ChatGPT visibility", "Perplexity",
+  "Google AI Overview".
+  For GEO-only audit → use /geo.
  For code-only bugs → use /bugfix. For feature work → use /feat.
-argument-hint: optional keywords/scope, e.g. "local SEO plombier 91 94 77"
+argument-hint: optional keywords/scope, e.g. "local SEO plombier 91 94 77" or "SaaS B2B content strategy"
 allowed-tools:
  - Read
  - Edit
@@ -18,11 +27,325 @@ allowed-tools:
  - Grep
  - Glob
  - Agent
+  - WebFetch
+  - WebSearch
 ---

-Load and follow strictly:
- $HOME/.claude/agents/seo-analyzer.md
+# /seo — parallel SEO + GEO dispatcher

-Execute the SEO-ANALYZER agent on the following target:
+This skill orchestrates TWO specialist agents running in parallel, then
+merges their output into a single `SEO.md` report. It is the main
+entry point for any SEO/GEO work on a web project.

-$ARGUMENTS
+## STEP 0 — Collect shared context (ONCE)
+
+Before spawning any agent, collect the context both agents need.
+This avoids asking the user the same questions twice.
+
+### Audit depth
+
+Ask once:
+```
+AUDIT DEPTH — choose one:
+
+  LOCAL  — Code-only analysis. No external calls.
+           Covers: markup, meta, JSON-LD, sitemap, robots.txt,
+           llms.txt, content shape audit, legal, security headers,
+           schemas for AI, entity signals (code-observable).
+
+  FULL   — LOCAL + live HTTP audit, Core Web Vitals (PageSpeed API),
+           external presence (GMB, social, directories), AI visibility
+           testing, competitor analysis, Wikidata / Knowledge Panel check.
+
+Which depth? (LOCAL / FULL)
+```
+
+If `$ARGUMENTS` contains `local`/`code-only`/`quick`/`rapide` → default LOCAL.
+If `$ARGUMENTS` contains `full`/`complet`/`externe`/`live` → default FULL.
+If `$ARGUMENTS` contains a production URL → suggest FULL.
+
+### Business context (one grouped block)
+
+**Both depths:**
+1. Activity type (B2C local / B2B national / SaaS / e-commerce / service / content/media)
+2. Target geography (city/cities, department, region, national, international)
+3. Languages served (for i18n/hreflang)
+4. Priority keywords and AI queries
+5. Intervention mode: **aggressive** (apply fixes) / **conservative** (audit-only)?
+
+**FULL depth only:**
+6. Production URL
+7. Google Business Profile URL (or "not yet")
+8. Social media URLs
+9. Known citations (PagesJaunes, Yelp, sector directories)
+10. Known competitors
+11. Known Wikidata QID / Knowledge Panel status (or "unknown")
+12. Time budget for user actions post-audit
+
+Skip questions already answered in `$ARGUMENTS`.
+
+### Plugin check (FULL only)
+
+For FULL depth, verify `WebFetch` and `WebSearch` are available.
+They are declared in this skill's `allowed-tools`, so they should
+be. If the harness reports them missing, offer to downgrade to LOCAL
+or continue with gaps.
+
+Store the collected context as a single block to pass to both agents.
+
+### File ownership (prevents parallel edit conflicts)
+
+Running two agents in parallel on the same repo is safe for ANALYSIS
+(read-only). It would race-condition on fixes if both touched the
+same file. This matrix is authoritative — pass it to both agents in
+their dispatch prompts:
+
+| File / concern | Owner | Notes |
+|---|---|---|
+| `robots.txt` | **geo-analyzer** | Classical + AI bot directives consolidated here. seo-analyzer reads only. |
+| `sitemap.xml` + image/video sitemaps | **seo-analyzer** | |
+| `llms.txt` / `llms-full.txt` | **geo-analyzer** | |
+| `.htaccess` (redirects, security headers, 404) | **seo-analyzer** | |
+| JSON-LD blocks (all schemas, all pages) | **geo-analyzer** | Owns structure + content. seo-analyzer flags NAP inconsistencies vs GMB, geo-analyzer reconciles. |
+| Meta tags (title, description, OG, Twitter, canonical, robots meta) | **seo-analyzer** | |
+| Heading hierarchy (H1 presence/count, level skips) | **seo-analyzer** | Structure only. |
+| H1/H2 content rewrite (Definition Lead, question-style) | **geo-analyzer** | Semantic rewrite for AI extraction. Batch G5 confirmation-gated. |
+| TL;DR / summary blocks insertion | **geo-analyzer** | |
+| Legal pages (mentions légales, confidentialité, CGV) | **seo-analyzer** | |
+| CMP / cookie banner integration | **seo-analyzer** | |
+| Images (alt, width/height, compression, WebP/AVIF) | **seo-analyzer** | |
+| hreflang | **seo-analyzer** | |
+| Footer links (legal + service/city pages) | **seo-analyzer** | |
+| New city/service pages | **seo-analyzer** | Batch D confirmation. |
+| Video transcripts | **seo-analyzer** (user action) | |
+
+If either agent detects a finding in a file it doesn't own, it emits
+a "CROSS-AGENT NOTE" in its envelope; the dispatcher forwards it to
+the owning agent at merge time. No direct cross-agent fix.
+
+## STEP 1 — Spawn both agents IN PARALLEL
+
+Issue both `Agent` tool calls **in the same message** (parallel tool
+calls). The harness runs them concurrently.
+
+```
+Agent(subagent_type="seo-analyzer")
+prompt: """
+Dispatched from /seo. Context:
+
+AUDIT DEPTH: <LOCAL|FULL>
+BUSINESS CONTEXT:
+  Activity type: ...
+  Geography: ...
+  Languages: ...
+  Priority keywords: ...
+  Intervention mode: ...
+  Production URL: ... (FULL only)
+  GMB URL: ...
+  Social URLs: ...
+  Known citations: ...
+  Known competitors: ...
+  Time budget: ...
+
+You are the classical-SEO half of a parallel SEO+GEO audit. Do NOT
+audit GEO/AI signals (llms.txt, AI crawlers, QAPage/Speakable schemas,
+entity SEO, content shape for AI, AI visibility) — the geo-analyzer
+agent runs in parallel and owns those.
+
+FILE OWNERSHIP (authoritative, prevents parallel-edit conflicts):
+- YOU OWN (read+write): sitemap.xml, image/video sitemaps, .htaccess,
+  meta tags (title, description, OG, Twitter, canonical, robots meta),
+  heading structure (H1 count, level skips), legal pages, CMP, images
+  (alt/dimensions/compression), hreflang, footer links, new city/service
+  pages.
+- YOU READ-ONLY: robots.txt (geo-analyzer owns), JSON-LD blocks
+  (geo-analyzer owns structure; you flag NAP inconsistencies), llms.txt.
+- CROSS-AGENT NOTES: if you find issues in files you don't own, emit
+  them in your envelope under "CROSS-AGENT NOTES TO geo-analyzer:"
+  — the dispatcher forwards.
+
+Execute your agent spec at ~/.claude/agents/seo-analyzer.md starting
+at STEP 2 (skip STEP 0 and STEP 1 — context is provided above).
+
+At STEP 13, emit the STRUCTURED ENVELOPE for merging (not a
+standalone SEO.md). Do NOT write any SEO.md file yourself — the
+dispatcher will merge your output with geo-analyzer's output.
+"""
+
+Agent(subagent_type="geo-analyzer")
+prompt: """
+Dispatched from /seo. Context:
+
+AUDIT DEPTH: <LOCAL|FULL>
+BUSINESS CONTEXT:
+  (same block as above)
+
+You are the GEO/AI half of a parallel SEO+GEO audit. Do NOT audit
+classical SEO signals (meta tags, Core Web Vitals, hreflang, image
+compression, classical legal compliance) — the seo-analyzer agent
+runs in parallel and owns those. Your focus is AI-engine retrieval:
+llms.txt, AI crawlers in robots.txt, QAPage/Speakable/Person+Article
+schemas, entity SEO (Wikidata, sameAs, Knowledge Panel), content
+shape for LLM extraction, AI visibility testing.
+
+FILE OWNERSHIP (authoritative, prevents parallel-edit conflicts):
+- YOU OWN (read+write): robots.txt (all directives — classical + AI),
+  llms.txt, llms-full.txt, JSON-LD blocks (all schemas, all pages),
+  H1/H2 content rewrite for Definition Lead, TL;DR / summary blocks,
+  content shape changes.
+- YOU READ-ONLY: sitemap.xml, .htaccess, meta tags, heading structure
+  (seo-analyzer owns structure), legal pages, images, hreflang.
+- CROSS-AGENT NOTES: if you find issues in files you don't own, emit
+  them in your envelope under "CROSS-AGENT NOTES TO seo-analyzer:"
+  — the dispatcher forwards.
+
+Execute your agent spec at ~/.claude/agents/geo-analyzer.md starting
+at STEP 2 (skip STEP 0 and STEP 1 — context is provided above).
+
+At STEP 14, emit the STRUCTURED ENVELOPE for merging (not a
+standalone GEO.md). Do NOT write any GEO.md or SEO.md file yourself —
+the dispatcher will merge your output with seo-analyzer's output.
+"""
+```
+
+## STEP 2 — Merge envelopes into SEO.md
+
+Both agents return structured envelopes keyed by SEO.md section
+numbers. Consolidate them into a single `SEO.md` at project root
+(or `docs/SEO.md` if that convention exists).
+
+### Combined score calculation
+
+Per user decision:
+- **Local B2C**: `GLOBAL = 0.80 × SEO_score + 0.20 × GEO_score`
+- **SaaS / national / content**: `GLOBAL = 0.75 × SEO_score + 0.25 × GEO_score`
+
+### Final SEO.md structure
+
+```markdown
+# Audit SEO + GEO — <Project Name>
+
+**Date** : <YYYY-MM-DD>
+**Version** : v<N> (incremented on each run)
+**Agents** : seo-analyzer + geo-analyzer (parallel)
+**URL** : <production URL>
+**Depth** : LOCAL | FULL
+**Score SEO (classique)** : XX.X / 20
+**Score GEO (IA)**        : XX.X / 20
+**Score global pondéré**  : XX.X / 20 (<weights explained>)
+
+---
+
+## 0. Alertes majeures (conformité + risques SEO/GEO)
+<Merged from both agents — legal blockers, catastrophic issues>
+
+## 1. Notes globales (/20 par axe + pondérée)
+<SEO scoring table from seo-analyzer + GEO scoring table from geo-analyzer + combined score>
+
+## 2. Audit technique (HTTP, CWV, sécurité)
+<From seo-analyzer>
+
+## 3. Audit on-page (meta, headings, content, images, video, a11y, i18n)
+<From seo-analyzer>
+
+## 4. SEO local / NAP
+<From seo-analyzer>
+
+## 5. Présence externe (GMB, réseaux sociaux, citations)
+<From seo-analyzer — FULL only>
+
+## 6. Analyse concurrentielle
+<From seo-analyzer — FULL only>
+
+## 7. Optimisation GEO / IA
+<From geo-analyzer — full dedicated section with sub-sections:>
+### 7.1 AI crawlers policy
+### 7.2 llms.txt / llms-full.txt
+### 7.3 Schema.org pour extraction IA (QAPage, Speakable, Person, Article+author)
+### 7.4 Entity SEO (Wikidata, @id, sameAs, Knowledge Panel)
+### 7.5 Content shape pour extraction IA (Definition Lead, TL;DR, citations, fraîcheur)
+### 7.6 Visibilité IA (tests — FULL only)
+
+## 8. Plan d'action — QUICK WINS (< 7 jours)
+<Merged from both agents — AUTO + USER, dedupe overlaps>
+
+## 9. Plan d'action — MOYEN TERME (1-3 mois)
+<Merged>
+
+## 10. Plan d'action — LONG TERME (3-6 mois)
+<Merged>
+
+## 11. Actions utilisateur requises
+<Merged — EVERY entry includes "Automatisation possible avec: <tools>"
+ per ~/.claude/agents/resources/automation-catalog.md>
+
+## 12. Recommandations gratuites (outils, méthodes, budget 0 EUR)
+<Merged — GSC, PageSpeed, Schema validator, manual AI-visibility spreadsheet, etc.>
+
+## 13. Synthèse 90 jours — objectifs réalistes
+<Combined measurable targets: review count, ranking positions, traffic,
+ AI mention rate, Wikidata presence>
+
+## 14. Annexe — informations non-auditables automatiquement
+<Merged — what couldn't be checked, why>
+
+## 15. Log des modifications appliquées par les agents
+<Merged change logs from both agents, grouped by batch>
+
+---
+
+## Historique
+<Previous audit summaries preserved here>
+```
+
+### Deduplication rules
+
+Both agents may surface overlapping findings (e.g. JSON-LD presence,
+Legal compliance). Merge rule:
+
+- **Hard dedupe**: identical finding text → keep one, credit both agents
+  in a `<sub>Detected by: seo-analyzer, geo-analyzer</sub>` line
+- **Complementary findings**: both agents see the same feature from
+  different angles (classical ranking + AI extraction) → keep both,
+  group under the same section
+- **Conflicting findings**: rare — if one agent says "remove schema X"
+  and the other says "keep schema X", flag explicitly in §0 and let
+  the user decide
+
+## STEP 3 — Console summary
+
+```
+SEO + GEO AUDIT COMPLETE (parallel dispatch)
+URL                        : <url>
+FRAMEWORK                  : <name + rendering>
+DEPTH                      : LOCAL | FULL
+
+NOTE SEO (classique)       : XX.X / 20
+NOTE GEO (IA)              : XX.X / 20
+NOTE GLOBALE (pondérée)    : XX.X / 20
+
+CHANGEMENTS APPLIQUES  (N) : voir SEO.md §15
+ACTIONS UTILISATEUR    (N) : voir SEO.md §11 (avec automatisation)
+CONFORMITÉ LÉGALE          : OK | <N> blockers → §0
+ALERTES MAJEURES           : <short list>
+
+PROCHAINE ÉTAPE            : <highest-priority immediate action>
+```
+
+## Rules
+
+- **Parallel dispatch is mandatory.** Both Agent calls MUST be in the
+  same message so the harness runs them concurrently. Sequential
+  dispatch doubles wall-clock time and is explicitly forbidden.
+- **Context collected once.** STEP 0 runs before any agent call.
+  Do not let either agent re-ask the user questions that STEP 0
+  already answered.
+- **Neither agent writes SEO.md.** Only the dispatcher (this skill)
+  writes the consolidated report. Agents return envelopes.
+- **Merge, don't overwrite.** On re-run, previous SEO.md's Historique
+  section is preserved. Current content moves to Historique with
+  summary (date + score + key changes).
+- **Every user action has automation options.** Per user CLAUDE.md,
+  mandatory from `automation-catalog.md`.
+- **Scoring weights per user decision**: GEO = 20% local B2C, 25%
+  SaaS/national/content. Combined score formula is explicit in §1.