# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Nature du dépôt Atelier d'authoring de skills Claude Code — pas une application. Aucun build, aucun test, aucun gestionnaire de paquets. Le « code » ici est du Markdown avec frontmatter YAML consommé par le runtime Claude Code. Pas de dépôt git initialisé à ce jour. Proposer `git init` avant toute réorganisation lourde de fichiers, pour que le versionning ait un filet. ## État actuel | Chemin | Nature | |---|---| | `seo-preparation-semantique/` | Skill **v2.0** — carte d'une page à écrire. Le Mode Audit en a été retiré | | `seo-audit-semantique/` | Skill **v1.0** — audit d'un contenu existant, avec script de comptage bundlé | | `docs/superpowers/specs/` | Specs de design validées, une par sujet | | `.claude/settings.local.json` | Active le serveur MCP `next-devtools` (non versionné) | ### Les deux skills forment une chaîne `seo-audit-semantique` **appelle** `seo-preparation-semantique` par sous-agent pour générer la carte de référence à laquelle il compare le contenu. Deux invariants à ne pas casser en modifiant l'un ou l'autre : - **Le générateur de carte ne voit jamais le contenu audité.** S'il le voyait, la carte s'alignerait sur ce qui est déjà écrit : l'audit ne trouverait plus rien et validerait la page par construction. L'échec est silencieux — le rapport a l'air excellent et ne dit rien de vrai. - **Les déclencheurs ne se chevauchent pas.** Les formulations d'audit (« qu'est-ce qui manque à ma page », « pourquoi elle ne ranke pas ») appartiennent au seul `seo-audit-semantique`. Les remettre dans la `description` de la préparation ferait se disputer les deux skills sur les mêmes phrases. Design de référence : `docs/superpowers/specs/2026-07-29-audit-semantique-design.md`. Il documente aussi les 9 défauts du Mode Audit d'origine que cette architecture corrige — utile avant de « simplifier » quoi que ce soit. ### Où atterrissent les livrables — jamais dans ce dépôt Ce dépôt contient les outils, pas leurs productions. Les sorties des skills vont dans `~/Documents/SEO//`, avec quatre types figés : ``` ~/Documents/SEO// ├── audits/ ← seo-audit-semantique, un dossier par couple -- ├── cartes/ ← seo-preparation-semantique, réutilisables entre audits ├── pages/ ← rédaction en aval └── briefs/ ← inputs fournis par le client ``` Le couple **page + requête** dans le chemin d'un audit est structurant, pas cosmétique : une même page auditée sur deux requêtes produit deux audits non comparables. Les ranger ensemble ferait du second le « v2 » du premier, et le delta de re-audit inventerait des P0 résolus et des régressions. C'est le seul endroit où une erreur de rangement corrompt un résultat. ### Le comptage est déterministe, par choix `seo-audit-semantique/scripts/count_density.py` mesure les occurrences plutôt que de les laisser estimer par le modèle, parce qu'un LLM se trompe régulièrement d'un facteur deux sur un texte de 2000 mots et que toute la couche C2 en dépend. Le partage : le modèle décide **quoi** compter (variantes de surface, homographes à écarter), le script décide **combien**. Le script gère déjà accents, tirets, casse, frontières de mots et chevauchements de variantes — vérifier `references/counting-script.md` avant d'ajouter un pré-traitement qui existe déjà. ## Chaîne d'installation des skills Ce dépôt est l'emplacement **canonique** de ses skills : elles sont servies directement d'ici, par symlink vers `~/.claude/skills/`. Les deux liens existent déjà. ```bash # Vérifier ce qui est exposé au runtime ls -la ~/.claude/skills # Exposer une nouvelle skill de ce dépôt ln -s /Users/humperdoo/Documents/skills/ ~/.claude/skills/ ``` Éditer un fichier ici modifie donc le skill actif immédiatement — pas d'étape de publication, et pas de copie qui pourrait diverger. C'est aussi pourquoi le point d'entrée doit rester `/SKILL.md` : le symlink pointe sur le dossier, et un chemin de version dedans casserait le lien à chaque incrément. D'autres skills maison de l'utilisateur vivent ailleurs (`~/Github/Rules/skills/` pour `seo-eeat`, `nextjs-oxc`, `nextjs-rules` ; `~/.agents/skills/` pour `seo-geo`). Ce dépôt ne les remplace pas, il coexiste. ## Convention de structure d'une skill Calquée sur `~/Github/Rules/skills/seo-eeat/`, la référence maison : ``` / ├── SKILL.md # frontmatter (name + description) EN TÊTE, puis le corps ├── references/ # fichiers chargés à la demande, pas dans le contexte initial │ ├── .md │ └── .md └── versions/ # archives, jamais chargées par le runtime └── v1.0-source.md ``` Le frontmatter doit ouvrir le fichier. S'il est précédé de quoi que ce soit — même une ligne de titre — il n'est pas lu et le skill ne se charge pas. C'est le défaut qui affectait la version brute de `seo-preparation-semantique`. `SKILL.md` reste le point d'entrée court ; tout ce qui est volumineux (templates de phases, rubriques de scoring, formats de fichiers d'entrée) part en `references/` pour ne pas saturer le contexte au chargement. La `description` du frontmatter est ce qui déclenche la skill — elle doit énumérer les formulations utilisateur réelles, pas résumer le contenu. ## Règles de travail sur ce dépôt ### Toute création ou modification de skill passe par `skill-creator` Non négociable (règle globale de l'utilisateur). Invoquer le skill `skill-creator:skill-creator` — jamais écrire ou éditer un `SKILL.md` à la main. ### On n'écrase jamais un fichier — versionning v1.x Les fichiers de ce dépôt sont des sources de vérité éditoriales, pas du code régénérable. Toute évolution crée une **nouvelle version datée**, l'ancienne reste lisible. - Incrément `v1.1`, `v1.2`, … pour un ajout ou un affinage à périmètre constant. - Incrément majeur (`v2.0`) pour un changement de pipeline ou de contrat de sortie. - Ni `Write` ni `Edit` destructif sur une version déjà publiée : on écrit la version suivante à côté. **Forme retenue** : `SKILL.md` est toujours la version courante, les archives vont dans `versions/vX.Y-<étiquette>.md`. Un dossier par version (`v1.0/SKILL.md`) casserait le symlink `~/.claude/skills/` à chaque incrément — le chemin du point d'entrée doit rester stable. ### Sous-dossiers cohérents Un dossier par skill, nommé exactement comme le `name` du frontmatter (kebab-case). Les docs brutes non encore converties restent identifiables comme telles et ne se mélangent pas aux `SKILL.md` finalisés. ## Domaine métier — SEO sémantique Les skills de ce dépôt relèvent d'un pipeline SEO en plusieurs maillons, à ne pas confondre : - **`seo-preparation-semantique`** (ici, en cours) — produit la *matière sémantique brute* : carte d'entités pondérées, lexique, gaps, sans scraping SERP. Ne rédige pas. - **`seo-eeat`** (`~/Github/Rules/skills/seo-eeat`) — pipeline de rédaction en aval, à partir de briefs Lumenia + scraping Firecrawl. - **`seo-geo`** (`~/.agents/skills/seo-geo`) — optimisation pour moteurs génératifs et schema markup. Frontière à respecter lors de l'authoring : la préparation sémantique s'arrête avant la rédaction (pas de H1 final, pas de hook, pas d'architecture Hn, pas de prose). Élargir son périmètre créerait un doublon avec `seo-eeat`. Vocabulaire récurrent, défini inline dans `seo-preparation-semantique.md` (section « Concepts mobilisés ») : Triade SERP, Information Gain, Confidence Score, Freshness Guard, Action Engine flag, pureté vectorielle, Surprise Gap, Structural Information GEO. Se référer à cette section plutôt que de re-définir ces termes.