Communitygithub.com

shimo4228/readme-writer

Skill Claude Code : écrit et améliore les README destinés aux humains — l'entrée canonique unique pour les humains, la recherche et les résumés IA. Contrepartie orientée humains du llms-txt-writer. Lint structurel déterministe + revue LLM holistique sans score (AKC ADR-0008 Code-LLM Layering).

Qu'est-ce que readme-writer ?

Ce skill permet d'écrire et d'améliorer les fichiers README orientés humains. Son principe central est que le README sert d'entrée canonique unique pour les humains, mais constitue également la seule surface sur laquelle un LLM peut s'appuyer de manière fiable via un grounding par URL (recherche IA, chat). Le skill doit donc concilier un format court et visuel pour les humains avec un « plancher informatif minimal » qui permet à un LLM de reconstruire le projet en lisant uniquement le README. Il est conçu pour l'agent Claude Code et sépare les vérifications structurelles (effectuées par un linter Python déterministe `readme_lint.py`) des évaluations sémantiques holistiques (réalisées par un LLM sans attribuer de score numérique). Le skill suit le principe 'Code-LLM Layering' et évite les scores de qualité chiffrés, privilégiant des retours concrets et actionnables (sous forme de diff) pour un humain. Il utilise Mermaid comme format de diagramme prioritaire (car textuel), interdit les badges de vanity, impose des textes alternatifs sur toutes les images, et applique un budget de longueur flexible basé sur le déplacement des informations profondes vers des docs séparées plutôt qu'un nombre de mots fixe.

Compatible avec✓Claude Code~Codex CLI✓Cursor✓Antigravity
npx skills add shimo4228/readme-writer

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

readme-writer — Compétence README orientée humains

Compétence pour écrire et améliorer les README destinés aux humains. Alors que llms-txt-writer prend en charge la surface dédiée à l'IA, cette compétence assume l'entrée canonique unique pour la surface humaine.

Ajout important : le README est également la seule surface sur laquelle un LLM peut s'appuyer de manière fiable via un chemin de grounding (coller une URL de dépôt dans une recherche/chat IA). Par conséquent, un README doit être à la fois « court et visuel pour les humains » tout en conservant un petit « plancher informatif » permettant à un LLM de reconstruire le projet en lisant uniquement le README — concilier ces deux exigences est le défi central de cette compétence.

Quand l'utiliser

  • Créer ou améliorer README.md / README.ja.md
  • Soigner « la première page d'atterrissage humaine » d'un dépôt/projet
  • Corriger un README existant « trop mécanique et insuffisamment humain » / « trop superficiel pour qu'un LLM puisse le saisir »
  • Quand on souhaite un README court et priorisant le visuel sans perdre le plancher informatif

À ne pas utiliser pour :

  • Documents dédiés à l'IA comme llms.txt / llms-full.txt / FAQ (→ llms-txt-writer)
  • Articles, essais, blogs ou toute prose longue (→ writing-ecosystem)
  • Conception de graph.jsonld (→ jsonld-knowledge-graph)

L'axe est « ATTENTION humaine × INFORMATION du LLM »

Le vrai dilemme d'optimisation d'un README n'est pas « informations pour humains vs informations pour LLM ». C'est l'attention humaine (court, accrocheur, scannable) × les informations pour le LLM (reconstructible avec le seul README). Les deux convergent vers les mêmes actions (voir ci-dessous) : il ne s'agit pas d'un compromis mais d'une conception qui gagne sur les deux tableaux.

Le README est la seule surface lue avec certitude (mais pas « la seule »)

  • Les crawlers de recherche/résumé IA ne lisent pratiquement pas llms.txt (plusieurs études de logs de 2026 montrent une majorité de zéro requête ; les principaux fournisseurs de recherche ont officiellement déclaré ne pas le supporter).
  • graph.jsonld est traité comme du texte brut en fetch direct et ne remplace pas les faits du README (expérience contrôlée).
  • Par conséquent, ne pas alléger le README en supposant que « la couche machine backstoppe » les informations.

Cependant, une calibration importante : « le LLM ne lit que le README » est trop forte. La formulation correcte est : « dans un grounding générique par URL collée ou recherche, le README est la seule surface que le LLM peut supposer avec certitude d'avoir ». D'autres voies existent (l'index de recherche a déjà chunké d'autres fichiers, le suivi de liens depuis le README, l'exposition de l'arborescence via connecteur GitHub/API, les connaissances du pré-entraînement). La conclusion la plus forte s'applique au grounding web anonyme en direct et au fetch direct d'atterrissage. En revanche, un agent de codage routé (Claude Code, Cursor, etc.) lit llms.txt à la demande, donc llms.txt reste utile comme assurance pour le canal agentique — mais pas comme point d'entrée pour la recherche IA.


Pourquoi séparer le « lint structurel » et la « revue holistique » ?

La qualité d'un README mêle deux types de propriétés. Suivant le Code-LLM Layering (la structure appartient à 100 % au code, le sens appartient au LLM), on sépare les propriétaires. Le critère de décision est when-code-when-llm : « un même octet peut-il avoir un sens différent selon le contexte ? »

PropriétéExempleTypePropriétaire
StructurelNombre de H1 / niveaux de titres / présence d'alt-text / résolution des liens locaux / noms de fichiers raster / nombre de badges / DOI dans <details> / ligne de prose après H1structurelcode (readme_lint.py)
SémantiqueL'accroche captive-t-elle ? / clarté de la proposition de valeur / le LLM peut-il reconstruire le projet avec le seul README ? / fluidité narrative / les badges sont-ils de la vanity ?sémantiqueRevue holistique LLM

Aucun score numérique basé sur des métriques de recherche n'est créé pour le README. Les ratios de sections de llms.txt (ski-ramp, etc.) sont des signaux déterministes validés par des études de citation LLM, mais « est-ce une bonne entrée ? » pour un README relève d'un jugement sémantique sans équivalent déterministe connu. Importer des métriques de surface IA (densité d'entités, etc.) dans un README humain est un anti-pattern.

Mais la « lisibilité IA structurelle » est activement adoptée (règle double face)

« Ne pas importer les métriques de surface IA » n'est qu'à moitié vrai. Le principe est : « on peut optimiser comment une idée est transmise (sans limite d'intensité). On ne déforme jamais ce qu'est l'idée. »

  • Adopté (intensité illimitée) : hiérarchie des titres, conception de l'information, ancrage des entités (noms d'auteurs / ORCID / DOI / identifiants canoniques dans la prose) / ancrage des termes propres ou inventés / accroche « réponse d'abord » / tableau « en un coup d'œil ». Ce sont des zones de convergence qui profitent à la fois aux humains et au LLM via le chemin de grounding.
  • Interdit : keyword stuffing, attributs gonflés, farming de titres interrogatifs, déversement de glossaires, distorsion des affirmations pour correspondre à une fonction de récompense de retrieval. Les citations et les stars ne sont pas des indicateurs de succès, donc il n'y a même pas d'objectif à servir par une distorsion.

Plancher minimal de lecture LLM (petit, non négociable, à ne pas faire gonfler)

Règle : si un LLM lit uniquement ce README (ni llms.txt, ni graph), il doit pouvoir reconstruire le projet avec le seul texte.

Éléments du plancher (en prose / markdown / Mermaid. Image seule / contenu dans <details> / contenu uniquement dans un lien sont interdits) :

  1. Phrase d'identité (1-2 premières phrases, lisibles seules) : « X est une {catégorie} qui fait {quoi} pour {qui} »
  2. Problème résolu / public cible / points de différenciation
  3. Faits canoniques : nom réel / langage/stack/statut. Pour les dépôts de recherche/DOI : DOI + comment citer (BibTeX / CITATION) + définition de 3 à 6 concepts centraux qui soutiennent le vocabulaire
  4. Un seul exemple concret : pour du code, signature de fonction + extrait minimal exécutable (pas l'implémentation complète — cela gonflerait et provoquerait des hallucinations) / pour la recherche, l'affirmation centrale + 2-3 chiffres clés
  5. Carte des liens vers les docs profondes : pointeurs uniquement. Ne pas placer de faits porteurs dans les liens / llms.txt / graph uniquement

Piège le plus important : le plancher est un petit noyau non négociable. Si on applique trop fort « ne coupe pas, restructure », les informations se réfugient dans Mermaid / <details> / sections plancher, et le README se gonfle en un faux llms-full.txt. L'objectif humain était court. Couper ou relocaliser sans pitié tout ce qui n'est pas le plancher (→ budget de longueur).

Lors de la création de graph.jsonld / llms.txt à partir du README, ne pas utiliser la prose du README comme source structurelle. Les identifiants et les arêtes du graphe doivent être dérivés de CITATION.cff / .zenodo.json / un petit manifeste en frontmatter (la copie parallèle manuscrite dérive).

Les métasurfaces de GitHub (description du dépôt, topics, social-preview, fichier CITATION, release, metadata de package) font également partie du plancher efficace pour le grounding. Ne pas les configurer dans le corps du README (cela relève de gh repo edit / release-doi), mais vérifier qu'elles sont présentes comme checklist.


Visuel d'abord (Mermaid en priorité, raster en dernier)

La bonne interprétation de « court et visuel » est « compresser le mur de prose en une structure scannable ». Il ne s'agit pas de transformer la prose en image. Et « Mermaid d'abord » ≠ « tout en Mermaid » — d'abord, filtrer ce qui mérite un diagramme. Choisir un format qui ne s'écrase pas sur mobile (petite largeur) et que le LLM peut récupérer.

Choix du format

ContenuFormat optimalRaison
3 étapes linéaires / simple énumérationprose / liste / petit tableauLisible sur tous les appareils (surtout mobile). Pas assez de valeur pour un diagramme
Vraiment une forme de graphe (relations, multi-branchements, matrice)Mermaid (TD vertical)La source est textuelle et lisible par LLM. Le défilement vertical est naturel sur mobile, horizontal (LR) s'écrase
Grand diagramme / complexeSVG commité (zoom/pan possible) / division en sous-systèmesUn Mermaid géant atteint ses limites même sur desktop et s'écrase sur mobile
UI réelle / résultats d'exécution / photoraster (PNG/JPG/WebP/GIF)Seulement ce que Mermaid ne peut pas représenter

Ajouter impérativement un équivalent textuel d'une phrase à chaque diagramme (règle stricte). C'est ce qui garantit « atteint les humains ET les LLM » : cela sauve à la fois l'humain sur mobile dont le diagramme est écrasé, l'extracteur LLM qui saute les blocs ```mermaid comme du code opaque, et le lecteur d'écran. Le diagramme est un bonus visuel au-dessus, pas le seul porteur de l'information.

Points clés pour Mermaid

  • GitHub le rend natif en SVG adapté au thème. La source est textuelle (diffable, ~10 tokens/arête) et lisible par les crawlers text-only qui ne voient pas les pixels. Transformer en Mermaid les structures noyées dans la prose/les graphes (matrice de concepts, liant de phases, étapes de pipeline) raccourcit et augmente la densité d'information.
  • Priorité mobile : TD (vertical). Le LR horizontal se brise facilement sur les petites largeurs.
  • La limite de rendu est basée sur les caractères (maxTextSize par défaut 50 000) + les arêtes, pas sur le nombre de nœuds (« 50-100 nœuds max » est une légende urbaine). Si on s'approche de la limite, diviser en sous-systèmes. Les README de projets spéciaux ne sont pas rendus.
  • Un extracteur pourrait laisser tomber Mermaid, donc garantir le sens séparément via l'équivalent textuel ci-dessus.

Raster / autres

  • Le raster ne doit pas porter d'informations essentielles. alt-text obligatoire (plancher strict : le chemin textuel ne lit que l'alt = une image sans alt est invisible pour le LLM. Ce n'est pas qu'une question d'accessibilité.).
  • Pour dark/light : <picture><source media="(prefers-color-scheme: …)"><img alt="…"></picture>. L'<img alt> est doublement porteur.
  • Commiter les assets image dans le dépôt et utiliser des chemins relatifs. Éviter les hotlinks externes (rupture du camo) et les <svg>/<embed>/<object> inline/animés (sanitizés par GitHub).
  • 2 à 4 badges à haut signal seulement (CI / version / license / DOI pour les dépôts de recherche). Éviter les badges de vanity. Limiter le nombre pour que la ligne de badges ne devienne pas trop haute sur les petites largeurs.
  • Dépôt CLI : asciinema → agg GIF + légende d'une phrase. Dépôt UI : capture d'écran/GIF + alt-text.

Pour les rares diagrammes sur mesure, utiliser Claude Artifacts / la compétence svg/diagram de Claude Code pour générer un SVG commitable et le placer dans assets/.


Budget de longueur (pas d'objectif de mots)

Aucun objectif de nombre de mots (« 500-1500 mots, le sweet spot », « un README visuel augmente les stars (étude GitHub) » sont tous deux rejetés comme fabriqués/référence manquante). À la place :

  • Above-the-fold (premier écran = juger en 30 s si c'est pour soi) : hero optionnel → H1 → tagline d'une ligne (proposition de valeur = ligne la plus sûrement extraite par un LLM) → ≤4 badges fonctionnels → faits du plancher → quick start copiable. La justification profonde vient après.
  • L'ordre varie selon le type de dépôt : « quickstart → justification » est pour les logiciels. Pour les articles, datasets, concepts, dépôts d'essais DOI, cela ne s'applique pas. Ne pas imposer un ordre fixe ; respecter seulement « identité + faits canoniques avant la justification profonde ». Le lint identity_lead ne vérifie structurellement que l'existence d'une phrase d'accroche, sans imposer d'ordre.
  • La quantité totale dépend d'une variable : le site de docs canoniques / les ADR absorbent-ils la profondeur ? Déplacer le « pourquoi » profond / les justifications de conception vers les ADR / docs/ / llms-full.txt / l'article déposé, et mettre un pointeur d'une ligne dans le README (déplacement de l'explication selon Diátaxis). C'est le traitement direct du « README de 450 lignes pour un dépôt de recherche ».
  • <details> est uniquement pour le volume secondaire (tableau d'options, FAQ, dépannage, glossaire complet). Il organise le champ visuel humain tout en restant accessible au LLM. Mais n'y mettez pas le plancher (perte de primauté + pas de Ctrl+F. Le chemin raw-markdown le lit, mais le résumeur de page rendue peut déprioritiser le contenu plié).

Workflow (Filtre code → Revue LLM → Validation humaine)

1. Filtre code — readme_lint.py (déterministe, structurel uniquement)

uv run --directory ~/.claude/skills/readme-writer python -m scripts.readme_lint "$ARGUMENTS"

Argument : chemin absolu du README. --json pour une sortie lisible par machine. Le code de sortie est la porte gérée par le code (0 = propre ou warnings uniquement / 1 = erreur de sévérité présente / 2 = non trouvé ou trop grand).

Éléments inspectés (issues concrètes, pas de scores. 2 niveaux de sévérité) :

Erreur (bloque la porte, structure dure)

  • single_h1 — exactement 1 H1
  • heading_levels — pas de saut de niveau de titre
  • alt_text — toutes les images ont un alt (plancher strict : pas d'alt = invisible pour le LLM)
  • local_link — les liens locaux relatifs / sources d'images existent

Avertissement (conseil, ne bloque pas la porte) — détecté structurellement mais « est-ce vraiment un problème ? » est un jugement, donc seule la surface est signalée. Le jugement sémantique est laissé à la revue LLM :

  • raster_diagram_hint — nom de fichier de raster ressemblant à un diagramme (architecture/flow/diagram/pipeline etc. en .png/.jpg/.webp/.gif) → suggérer la conversion en Mermaid. SVG, captures d'écran, logos sont exclus
  • badge_budget — trop de badges (défaut >6). Jugement uniquement sur le nombre (vanité ou non = LLM)
  • details_floor_leak — token DOI / BibTeX / CITATION dans <details> (indice de fuite du plancher. « Est-ce vraiment du plancher ? » = jugement LLM)
  • identity_lead — pas de phrase d'accroche en prose entre H1 et la première section (pas d'ordre imposé. L'absence de H1 est gérée par single_h1)
  • doi_citation_pairing — DOI présent mais pas de how-to-cite (section Citation / BibTeX / CITATION.cff) (pas imposé pour les dépôts non-recherche — ne se déclenche que si DOI présent)

2. Revue holistique LLM (rubrique comme lentille, pas de score, signal d'abord)

Une fois le lint passé, Claude lit le README de manière holistique et produit des constats concrets + un diff concret avec les lentilles suivantes :

  • 🚩 README-only recovery (vaisseau amiral, plus grand levier) — Lire uniquement le texte du README et vérifier si on peut reconstruire (identité / public / problème / différenciation / DOI et citation si pertinent / 3-6 concepts clés / 1 exemple / lien vers la suite). Lister les manques concrets (« le public cible n'est pas écrit », etc.). Pas de score. C'est l'opérationnalisation même du « plancher minimal de lecture LLM ».
  • Accroche : Quoi / Qui / Pourquoi — Le premier écran donne-t-il « quoi, pour qui, pourquoi s'y intéresser » ?
  • Accroche humaine / proposition de valeur — La valeur est-elle exprimée concrètement, pas en termes abstraits ?
  • Narration / scannabilité — Paragraphes, titres, listes, Mermaid sont-ils suivables par un humain ?
  • Vérification de la concision (le plus important contrôle inverse) — Le hors-plancher est-il relocalisé ? Les informations sont-elles conservées dans Mermaid / <details> / plancher au point de gonfler en faux llms-full.txt ?
  • Pertinence visuelle — Les diagrammes sont-ils en Mermaid ? (si raster, a-t-il un équivalent textuel ou une conversion Mermaid ?). Les badges sont-ils à haut signal (pas de la vanity) ?
  • Cohérence des faits — Les affirmations contredisent-elles la couche machine (llms.txt / graph.jsonld) ? → délégué à context-sync

Pourquoi pas de score (signal d'abord + dissolution de l'échafaudage) : ne produire que des « informations qui changent l'action suivante ». Accroche : 6/10 ne change pas l'action. « L'accroche ne dit pas à qui elle s'adresse » change l'action. La sortie est au format diff, divisée en éléments que l'on peut accepter/rejeter par y/n. Pour séparer auteur et relecteur, il est souhaitable d'exécuter la revue dans un processus agent distinct de l'implémenteur (même principe que editor / essay-reviewer).

3. Vérification de cohérence des faits → context-sync

La vérification que les faits du README correspondent à llms.txt / llms-full.txt / graph.jsonld (éviter le cloaking) est de la responsabilité de context-sync. Cette compétence ne la réimplémente pas.

4. Validation humaine

Un humain approuve le diff et l'applique.


Ce que cette compétence NE FAIT PAS (limites)

  • N'écrit pas llms.txt / llms-full.txt (→ llms-txt-writer)
  • Ne conçoit pas graph.jsonld (→ jsonld-knowledge-graph)
  • Ne détecte pas / ne synchronise pas la dérive cross-surface (→ context-sync / release-doi)
  • N'édite pas d'articles / essais (→ writing-ecosystem)
  • Ne configure pas la description / topics / social-preview du dépôt (fait par gh repo edit / release-doi. Cette compétence ne fait que les présenter comme checklist)
  • Ne produit pas de score de qualité / grade / note

Anti-patterns

  • Ne donner qu'un score numérique sans proposition concrète (piège du type « recommandeur »)
  • Faire juger par le LLM ce qui relève du lint structurel / remplacer un jugement sémantique par une regex (voir when-code-when-llm)
  • Réutiliser des métriques numériques de surface IA (ski-ramp, densité d'entités, farming de titres interrogatifs) dans un README humain (baisse de lisibilité)
  • Interpréter « priorité visuelle » comme une transformation de la prose en image (le diagramme raster est invisible pour un LLM text-only = cacher des informations aux agents. Utiliser Mermaid)
  • Appliquer trop fort « ne coupe pas, restructure » et transformer le README en faux llms-full.txt (le plancher est petit ; au-dessus, couper / relocaliser sans pitié)
  • Alléger le plancher du README en supposant que la couche machine (llms.txt/graph) backstoppe (elle n'est pas lue par le chemin de grounding)
  • Dériver llms.txt/graph de la prose du README (dérive. Dériver depuis un manifeste)
  • Ajouter des faits / des arguments marketing pour les humains (atteinte à l'authenticité + contradiction avec la couche machine = cloaking. L'emballage peut changer, pas l'affirmation)

Vérification

cd ~/.claude/skills/readme-writer
uv sync --dev
uv run pytest tests/ --cov=scripts --cov-report=term-missing

fixtures/sample_clean.md (0 issues, exemple de bonne pratique utilisant Mermaid) et fixtures/sample_issues.md (exemple déclenchant les 9 vérifications) permettent de vérifier le comportement de base.


Liens connexes

  • llms-txt-writer — Le pendant écrivain pour la surface IA (avec son geo_check.py basé sur des métriques de recherche). Cette compétence est pour la surface humaine.
  • when-code-when-llm — L'axe de décision structurel / sémantique
  • context-sync — Cohérence des faits / dérive entre README et couche machine (la vérification des faits y est déléguée)
  • jsonld-knowledge-graph — Conception de graph.jsonld
  • writing-ecosystem — Orchestrateur de prose longue orientée humains
  • inspiration.md — Origine de la conception, provenance des recherches primaires, sources des preuves externes (séparé du corps de SKILL.md pour la portabilité)

Skills associés