readme-writer

Rédige ou réécrit un README de projet qui convertit les visiteurs en utilisateurs et contributeurs - accroche d'une ligne, badges, démarrage rapide en 60 secondes, exemples concrets, fonctionnalités, FAQ, contribution et licence - et le lint pour détecter les sections manquantes, les liens relatifs cassés, les ancres de table des matières sans titre correspondant, le texte alternatif manquant et un premier bloc de code tardif. À utiliser lorsque l'utilisateur demande d'écrire, améliorer, relire ou restructurer un README, dit que personne ne comprend ou ne suit le projet, ou prépare un lancement open-source.

Qu'est-ce que readme-writer ?

Le skill **readme-writer** pour agents IA (Claude Code, Cursor, Codex) automatise la création, la révision et la réécriture de fichiers README pour les projets open-source. Son objectif principal est de transformer un simple visiteur en utilisateur ou contributeur actif en moins d'une minute. Il structure le README autour d'une accroche percutante, d'un démarrage rapide copiable, de badges à jour, d'exemples réels et de sections essentielles (fonctionnalités, FAQ, contribution, licence). Le skill analyse d'abord le code source (manifestes, CLI, licence) pour collecter des faits précis, puis interroge l'utilisateur uniquement sur ce que le code ne peut révéler (public cible, différenciation). Il applique un linting strict via un script Python (`scripts/readme_lint.py`) qui vérifie la présence de titres, d'accroches, de blocs de code précoces, de badges, de sections obligatoires, et détecte les liens relatifs cassés, les ancres de table des matières non valides, le texte alternatif manquant et les textes fictifs. Le skill produit un diff pour les réécritures, un rapport de lint final et une liste de points à valider manuellement (GIF, captures, benchmarks). Il est particulièrement utile pour les lancements de projets, les versions 1.0, ou lorsque le projet attire des visites mais peu de contributions.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/saizul/oss-maintainer-skills/tree/HEAD/skills/readme-writer

Installed? Explore more Productivité et collaboration skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

Demander à votre IA préférée

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

Documentation

Rédacteur de README

Un README n'a qu'une seule mission : faire passer un visiteur de « qu'est-ce que c'est ? » à une première commande fonctionnelle en moins d'une minute, puis lui montrer comment aller plus loin et comment aider.

Quand l'utiliser

  • Écrire un README pour un nouveau projet, ou réécrire un README trop succinct ou décousu
  • Relire un README avant un lancement ou une version 1.0
  • L'utilisateur dit que le projet reçoit des visites mais pas d'étoiles, d'installations ou de contributeurs

Quand ne pas l'utiliser

  • Documentation de référence d'API (générez-la depuis le code ; liez-la depuis le README)
  • Longs tutoriels ou documentation d'architecture : placez-les dans docs/ et créez des liens

Workflow

  1. Recueillir les faits avant d'écrire. Lisez le manifeste (pyproject.toml, package.json, composer.json, Cargo.toml...), l'aide --help de la CLI ou le point d'entrée principal, la documentation existante et la licence. Trouvez la véritable commande d'installation et un exemple concret. N'inventez jamais de drapeaux, de sorties, de benchmarks ou de fonctionnalités.

  2. Ne demander à l'utilisateur que ce que le code ne peut pas révéler : à qui s'adresse le projet, le seul problème qu'il résout, et pourquoi il est meilleur que l'alternative évidente. Si l'utilisateur n'est pas disponible, rédigez une accroche neutre à partir du code et marquez-la pour révision.

  3. Linter le README actuel (s'il existe). scripts/ est relatif à ce skill :

    python3 scripts/readme_lint.py README.md
    python3 scripts/readme_lint.py README.md --json --strict
    
  4. Écrire en suivant la structure de structure.md, en partant du modèle. L'ordre compte : titre + badges, accroche, (image de démo), démarrage rapide, fonctionnalités, utilisation/exemples, configuration, FAQ, feuille de route, contribution, licence.

  5. Appliquer les règles d'écriture :

    • Accroche : une phrase, moins de 200 caractères, pas de mots pompeux. Modèle : « <nom> est un <catégorie> qui <fait X> pour <public>, <différenciateur clé>. »
    • Premier bloc de code avant la ligne 60. Chaque commande doit être copiable et réelle.
    • Afficher la sortie après les commandes lorsque cela aide (# => ... ou un bloc séparé).
    • Utiliser des tableaux pour les options et comparaisons, des listes pour les fonctionnalités (avantage en premier).
    • Créer des liens, ne pas coller : les documentations longues, les journaux de modifications et les références d'API vont ailleurs.
    • Chaque image doit avoir un texte alternatif ; préférer un SVG ou un court GIF du flux principal.
  6. Badges. N'utilisez que des badges vrais et maintenus, dans cet ordre : état CI, dernière version (PyPI/npm/Packagist/release), téléchargements (optionnel), licence. Exemples dans structure.md.

  7. Relinter jusqu'à ce qu'il n'y ait plus d'erreurs. Résolvez les avertissements ou dites à l'utilisateur pourquoi.

  8. Vérifier les liens que le linter ne peut pas vérifier : les URL absolues et les ancres. Testez en cliquant ou expliquez ceux qui n'ont pas été vérifiés.

Résultat

  • Le nouveau README.md ou la version mise à jour (affichez un résumé des différences pour les réécritures).
  • Le résultat final du lint.
  • Une courte liste des faits que vous n'avez pas pu vérifier et des espaces réservés que l'utilisateur doit remplir (GIF de démo, captures d'écran, chiffres de benchmark).

Règles de lint

RègleNiveauSignification
titleerreur/avertissementexactement un H1
pitcherreur/avertissementune courte phrase sous le titre
badgesavertissementaucun badge trouvé
installerreur/avertissementsection d'installation (ou démarrage rapide), avec un bloc de code
quickstarterreur/avertissementsection utilisation, démarrage rapide ou exemple, avec du code
codeerreuraucun bloc de code du tout
scrollavertissementpremier bloc de code après --max-scroll lignes (par défaut 60)
contributing, licenseavertissementsection manquante
faq, tocinfosuggéré
alt-textavertissementimage sans texte alternatif
broken-linkerreurlien relatif vers un fichier manquant, ou lien vide
broken-anchorerreurlien #ancre (table des matières) qui ne correspond à aucun titre ou id/name HTML, en utilisant les règles de slug de GitHub
placeholderavertissementtexte TODO, TBD ou lorem ipsum laissé

Sortie 1 en cas d'erreur (et en cas d'avertissement avec --strict).

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Skills associés