# Spec — Skill `seo-eeat`

**Date** : 2026-05-27
**Statut** : Brouillon validé par l'utilisateur, prêt pour implémentation
**Cible d'implémentation** : agent `skill-creator` (jamais à la main — cf. `global-rules.md` §1)

## Contexte

Produire une page SEO long-form orientée Google E-E-A-T à partir d'un brief Lumenia.io demande aujourd'hui un copier-coller manuel de plusieurs sources (fichiers Lumenia, scrapes concurrents) dans une conversation Claude, suivi de l'exécution d'un prompt master 6 phases (voir `tmp/seo/eeta-flow.md`). Ce flow est solide mais :
- nomme "YTG" un format qui est en réalité Lumenia.io (incohérence à corriger) ;
- exige des étapes mécaniques manuelles (détecter les fichiers d'entrée, scraper 7 URLs) ;
- n'a pas de point d'arrêt révisable — on subit 6 phases d'affilée et on jette tout si Phase 5 dérape ;
- s'appuie sur une grille EEAT antérieure aux signaux Helpful Content 2024-2025.

Le skill `seo-eeat` packageait ce prompt en composant Claude Code, en corrigeant ces points et en automatisant les étapes déterministes.

## Objectif

Skill Claude Code déclenché par l'utilisateur ("produit une page SEO sur le brief Lumenia X", "exécute le flow EEAT", etc.) qui :

1. détecte automatiquement les fichiers Lumenia (`premium-*.txt` + `premium-*-brief.txt`) dans un dossier d'inputs ;
2. scrape 7 URLs concurrentes via Firecrawl (MCP `firecrawl` déjà disponible dans l'environnement) ;
3. exécute un flow 6 phases avec checkpoints utilisateur entre les phases coûteuses ;
4. produit un livrable Markdown publiable + sidecars d'audit, dans la langue déclarée par le brief.

## Non-objectifs (YAGNI explicites)

- ❌ Générer le brief Lumenia (Lumenia.io le produit déjà).
- ❌ Supporter YourTextGuru ou d'autres providers de brief sémantique. Lumenia uniquement.
- ❌ Publication CMS automatique.
- ❌ Forcer une langue de sortie : le skill suit `brief.language`.
- ❌ Re-rédaction itérative post-Phase 6. L'utilisateur édite à la main ensuite.

## Architecture

```
skills/seo-eeat/
├── SKILL.md                          # orchestrateur, ~200-250 lignes
└── references/
    ├── lumenia-format.md             # format des fichiers premium-*.txt + règles de parsing
    ├── eeat-rubric-2025.md           # grille EEAT 2025 + Helpful Content
    └── phase-templates.md            # templates tableaux competitors, schéma Hx, contrat output
```

**Installation** : symlink `~/.claude/skills/seo-eeat → ~/Github/Rules/skills/seo-eeat`, conforme au pattern des skills existants du repo (`nextjs-oxc`, `nextjs-rules`).

**Pourquoi cette répartition** : SKILL.md reste lisible et léger en tokens (chargé à chaque invocation). Les grilles, templates et règles de parsing vivent dans `references/`, lus à la demande quand la phase concernée en a besoin. Mettre à jour la rubrique EEAT 2026 ne touchera pas l'orchestrateur.

## Frontmatter SKILL.md

```yaml
---
name: seo-eeat
description: Pipeline de production SEO content (Lumenia + EEAT 2025). Détecte automatiquement
  les fichiers Lumenia.io (premium-*.txt) dans un dossier, scrape les URLs concurrentes via
  Firecrawl, et exécute un flow 6 phases (déconstruction SERP → analyse Lumenia → brief →
  jugement EEAT 2025 → architecture Hx → rédaction Markdown) avec checkpoints révisables.
  Sortie : page SEO complète prête à publier, dans la langue du brief. À déclencher dès que
  l'utilisateur veut produire / rédiger / générer une page SEO orientée EEAT, traiter un
  brief Lumenia.io, optimiser pour Google E-E-A-T, ou battre une SERP concurrente.
---
```

## Inputs

| Input | Source | Format | Obligatoire |
|---|---|---|---|
| Dossier d'inputs | argument utilisateur | `<dir>/premium-XXXXXXXX.txt` + `<dir>/premium-XXXXXXXX-brief.txt` | ✅ |
| Liste de 7 URLs concurrentes | argument utilisateur | array string | ✅ |

**Auto-détection** : `find <dir> -maxdepth 1 -name 'premium-*.txt'` → split par suffixe `-brief.txt` pour distinguer guide et brief.

**Si une URL ou un fichier manque** → `⚠️ MISSING INPUT: <détail>` explicite. Pas d'invention.

## Flow 6 phases avec checkpoints

| Phase | Action | Checkpoint utilisateur |
|---|---|---|
| **0. Setup** | Parser le guide Lumenia (query, language, 50 top terms, 20 2-grams, 20 3-grams, 20 named entities, grammage cible) + le brief (intent, objectives, key subjects, questions, tone, style, value prop) | ⏸ Récap inputs + langue détectée + grammage Lumenia → GO |
| **1. Déconstruction concurrentielle** | Firecrawl batch sur les 7 URLs (mode `markdown`). Pour chaque page : tableau `{URL, meta_title, meta_description, grammage_réel, structure_Hx, angle_éditorial, EEAT_forces, EEAT_faiblesses}`. Synthèse comparative 200 mots max + identification du `MAX(grammage_concurrents)` | ⏸ Valider la déconstruction avant analyse Lumenia |
| **2. Analyse Lumenia & grammage cible** | Top terms triés par priorité d'intégration, 2-grams / 3-grams prioritaires, named entities obligatoires (autorité E-E-A-T). Calcul : `grammage_final = MAX(grammage_concurrents) + 500 à 1000 mots`. Affiche : `🎯 Grammage final visé : XXXX mots` | ⏸ Valider le grammage cible |
| **3. Analyse brief** | Extrait : intent, objectifs, topics, questions (futures FAQ), ton, style, value prop. Lecture déterministe, pas de jugement | Pas de checkpoint |
| **4. Jugement EEAT 2025** | Évaluation auto-critique selon la grille `references/eeat-rubric-2025.md` : Experience (first-hand signals, exemples vécus), Expertise (vocabulaire métier, named entities), Authoritativeness (sources citées, données chiffrées), Trustworthiness (transparence, équilibre) + Helpful Content checks (people-first, satisfying experience, disclosure si AI-assisted). Score `/20`, minimum 16. Si < 16 → loop le plan (max 2 itérations), puis escalade utilisateur | ⏸ Valider le jugement EEAT avant Phase 5 |
| **5. Architecture Hx** | Structure complète H1 → H4 : H1 (keyword + angle différenciant), H2 par topic du brief, FAQ en H2 avec questions du brief en H3, conclusion. Ordre logique : définition → processus → matériaux → technologies → business → éthique → FAQ. Battre la profondeur structurelle des concurrents | ⏸ Valider l'architecture avant rédaction longue |
| **6. Rédaction finale** | Markdown publiable dans la langue du brief : meta title (≤60 chars, inclut keyword), meta description (≤155 chars, CTA implicite), slug, contenu Hx complet à grammage cible ± 5%, intégration naturelle des top terms / n-grams / entities (pas de keyword stuffing), marqueurs EEAT inline ("In practice…", "Industry data shows…", citations sourcées) | Écrit dans un fichier, pas dans le chat |

**Contrainte transverse** : Claude affiche le titre de chaque phase avant son output, conformément au prompt master existant (chain-of-thought explicite).

## Outputs

Écrits à côté du dossier d'inputs (ex: `tmp/seo/jewellery-manufacturing/`) :

| Fichier | Contenu | Format |
|---|---|---|
| `<query-slug>.md` | Page SEO publiable (Phases 5 + 6) | Markdown pur, prêt CMS |
| `<query-slug>.meta.json` | `{ meta_title, meta_description, slug, word_count, lumenia_coverage }` où `lumenia_coverage` = `{ top_terms: [{term, integrated: bool}], two_grams: [...], three_grams: [...], named_entities: [...] }` | JSON |
| `<query-slug>.workflow.md` | Trace lisible des Phases 1-5 (tableau competitors, analyse Lumenia, brief, jugement EEAT, archi Hx) pour audit et itérations futures | Markdown |

**Pourquoi des fichiers et pas une grosse réponse chat** : la Phase 6 seule peut dépasser 3000 mots. Écrire dans des fichiers évite la troncature de réponse + facilite la review section par section + sert d'archive.

**Slug** : dérivé de `brief.query` (ex: `jewellery manufacturing` → `jewellery-manufacturing`). Si un fichier existe déjà, suffixer `-v2`, `-v3`, etc.

## Garde-fous

- `⚠️ MISSING INPUT: <champ>` explicite quand un input requis manque. Jamais d'invention de fichier ou de champ absent.
- Pas de chiffres ni citations inventés : tout ce qui est cité comme source / données doit venir des named entities Lumenia, des scrapes concurrents, ou être marqué `[SOURCE TO ADD]` pour review humaine.
- Firecrawl échoue sur une URL → log le fail, continue avec les autres. Si ≥ 3 échecs sur 7 → demande à l'utilisateur de fournir des URLs de remplacement.
- Loop EEAT plafonné à 2 itérations. Au-delà, escalade : demander à l'utilisateur si on relaxe le seuil ou si on relance avec un autre angle.

## Hors-scope explicites

- ❌ Scripts utilitaires (`scripts/`) : parsing Lumenia trivial, Firecrawl via MCP. Pas de dépendance système supplémentaire.
- ❌ Génération du brief Lumenia. C'est l'outil Lumenia.io qui le produit.
- ❌ YourTextGuru ou autres providers. Refactor possible si besoin émerge, mais YAGNI maintenant.
- ❌ Fallback "dumps Markdown locaux au lieu d'URLs" : le MVP exige 7 URLs + Firecrawl. Support local possible plus tard si le besoin émerge.

## Fixture de test

`tmp/seo/jewellery-manufacturing/` (déjà présent) reste comme test fixture. Premier run du skill : sur ce dossier + 7 URLs SERP réelles à fournir. Validation manuelle des outputs.

## Étapes d'implémentation (à venir, par skill-creator)

1. Création de la structure `skills/seo-eeat/` via l'agent `skill-creator`.
2. Rédaction de `SKILL.md` (orchestrateur).
3. Rédaction de `references/lumenia-format.md`, `references/eeat-rubric-2025.md`, `references/phase-templates.md`.
4. Symlink `~/.claude/skills/seo-eeat → ~/Github/Rules/skills/seo-eeat`.
5. Dry-run sur la fixture `tmp/seo/jewellery-manufacturing/`.
6. Commit en feature branch (cf. `global-rules.md` §3), merge FF dans `dev`.