Communitygithub.com

/brag-more

Transforme le README GitHub d'un projet en une page d'accueil soignée et impressionnante — avec un héros SVG animé aux couleurs du projet, des cartes de fonctionnalités, une vidéo de démonstration, des badges vérifiés, une accroche concise, et un guide de démarrage rapide fonctionnel.

Qu'est-ce que brag-more ?

**/brag-more** est un agent spécialisé dans la transformation du README d'un projet GitHub en une page d'accueil visuellement époustouflante et persuasive. Il va bien au-delà d'une simple réécriture : il inspecte le projet en profondeur (code source, manifestes, fichiers de configuration, identité visuelle) pour produire un README qui soit à la fois vrai, fonctionnel et convaincant. L'agent génère automatiquement un héros SVG animé aux couleurs et à la typographie exactes du projet, des cartes de fonctionnalités visuelles, une vidéo de démonstration (via `/brag` si disponible), des badges justifiés par des preuves tangibles, et s'assure que toutes les commandes de démarrage rapide et d'utilisation sont vérifiées et exécutables. Il gère aussi les thèmes clair/sombre et respecte les préférences de mouvement réduit. Compatible avec tous les langages et frameworks, il nécessite simplement l'accès aux outils du système (git, node, python, etc.) pour inspecter et éventuellement produire une vidéo. Son véritable atout est sa rigueur : chaque affirmation, chaque badge, chaque commande est validée par une inspection réelle du code source et du dépôt, produisant un README qui reflète fidèlement le projet et qui fonctionne concrètement.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/omer-chandna/brag-more/tree/HEAD/skills/brag-more

Demander à votre IA préférée

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

Aperçu

Depuis le README du skill

brag-more preview

Documentation

Que fait brag-more ?

Tu l'as construit. Maintenant, fais en sorte que le dépôt en parle aussi. Le README est la première chose que quiconque voit sur GitHub ; transforme-le en une page d'accueil qui vend le projet en cinq secondes et emmène un inconnu de zéro à l'exécution en une minute.

Quel que soit le projet, le résultat doit ressembler au README d'un projet open-source bien aimé : confiant, scannable, visuel et vrai. Rien sur la page qui ne mérite pas sa place.

Usage : /brag-more [options]. Options (drapeaux ou langage naturel) :

OptionDéfaut
--style clean|bold|minimal|showcasedéduit du projet (voir Styles)
--previewdésactivé : écrit README.md sur place. Avec, écrit uniquement dans brag-output/repo/ et laisse README.md intact
--no-bannerbannière activée
--no-videodésactivé : si le projet n'a pas de vidéo, en créer une d'abord (voir La vidéo)
--no-demodémo activée quand il y a quelque chose à montrer

Les fichiers de travail vont dans brag-output/repo/ (horodaté brag-output-YYYY-MM-JJ-HHmmss/repo/ si brag-output/ existe déjà et ne vient pas de cette exécution). Les ressources référencées par le README vont dans le dépôt, dans .github/readme/, pour qu'elles voyagent avec lui.

1. Inspection

Lis le projet, pas seulement l'ancien README :

  • Le README existant, chaque ligne. C'est l'écriture de l'utilisateur. Garde tout ce qui est vrai et utile (étapes d'installation, tableaux de configuration, crédits, notes de licence, liens de sponsors, remerciements) ; restyle-le, ne le jette pas.
  • Identité : couleurs et polices exactes de la marque depuis les feuilles de style ou la configuration du thème, le logo ou favicon, toute image de héros existante ou image OG.
  • Ce que c'est : manifestes de paquets (package.json, pyproject.toml, Cargo.toml, go.mod, …) pour le nom, la description, la version, la licence, les binaires et scripts ; le point d'entrée et les routes ou commandes principales pour les vraies fonctionnalités.
  • Comment l'exécuter : les commandes réelles d'installation et de démarrage depuis les scripts de manifeste, Makefile, justfile, Dockerfile, ou workflow CI. Note les versions d'exécution que le projet impose.
  • Signaux pour les badges : LICENSE, .github/workflows/*, si le paquet est publié (npm, PyPI, crates.io — vérifie le nom et le flag private du manifest), le dépôt distant git (git remote get-url origin) pour propriétaire/dépôt.
  • Sortie existante de brag : si brag-output*/brag.mp4 et brag.jpg existent, ce sont les meilleurs matériaux de démo sur la machine. Utilise les plus récents. S'il n'y en a pas, tu les créeras à l'étape suivante.

Ignore la sortie de build, les fichiers de verrouillage, .git/, les fichiers de variables d'environnement et secrets (.env, .env.*), les clés et informations d'identification, et tout ce que .gitignore exclut pour ces raisons.

Avant d'écrire, réponds : Qu'est-ce que c'est (une phrase qu'un inconnu comprend) ? Pour qui est-ce ? Quelle est la seule chose qu'il fait mieux que l'alternative ? Quel est l'accroche visuelle — la capture d'écran, le GIF ou la bannière qui fait arrêter de défiler ? Quelles sont les 3 à 5 vraies fonctionnalités ? Quel est le chemin le plus court du clone à l'exécution ?

Le README est public. N'y emporte jamais de secrets, jetons, noms d'hôtes internes, vrais noms de clients ou d'utilisateurs, adresses e-mail ou autres données personnelles, ni dans ses images. Si une capture d'écran montre de telles données, remplace-les par des substituts fictifs plausibles.

La vidéo (avant le plan, quand il n'y en a pas encore)

La meilleure démo du README est la vidéo de lancement du projet, donc brag-more la crée quand elle manque. Saute cette étape quand --no-demo ou --no-video est défini, ou quand un brag-output*/brag.mp4 existe déjà.

  1. Si la compétence /brag est installée (vérifie la liste des compétences), exécute-la pour ce projet via l'outil Compétence, en transmettant toute demande de --tone ou de format. Dis à l'utilisateur en une ligne : « Pas encore de vidéo de lancement, donc j'en crée une avec /brag d'abord. »
  2. Sinon, lis <répertoire-compétence>/video.md (le workflow vidéo léger fourni ici, de brag-slim) et suis-le. Il ne nécessite que des outils déjà sur la machine.
  3. Quand il se termine, la vidéo, l'affiche et la copie de partage sont dans brag-output/. Continue avec le README en les utilisant comme démo.

Si la création de la vidéo échoue ou si l'utilisateur ne veut pas attendre, continue sans elle et utilise les solutions de repli sous Démo.

2. Plan

Écris brag-output/repo/readme-plan.md : l'accroche, le style choisi, l'ordre des sections, quels visuels tu vas créer et ce que chacun montre, quels badges sont justifiés (et la preuve pour chacun), et ce que tu conserves de l'ancien README.

Forme : une forme de départ, pas un modèle. Supprime toute section qui serait vide ou du remplissage.

  1. Héros — le héros SVG animé (voir Construction), puis centré : l'accroche, une courte rangée de badges, et une ligne de navigation de liens (Démo · Install · Docs · …).
  2. Démo — le produit en action, juste en dessous du héros, encadré : la boucle vidéo brag, un GIF de l'interface réelle, ou un enregistrement de terminal. Un visuel, grand.
  3. Pourquoi — 2 à 4 phrases : ce qu'il fait pour l'utilisateur et ce qui le distingue, dans les propres mots du projet. Pour un outil de développeur, un bloc de code de 3 à 5 lignes qui est l'accroche bat un paragraphe (bun run index.tsx # TS et JSX prêts à l'emploi).
  4. Vitrine de fonctionnalités — 3 à 6 vraies fonctionnalités, chacune avec son propre petit visuel : une capture d'écran recadrée de l'interface réelle, un GIF de terminal par commande, ou un extrait de code et sa sortie. Dispose les visuelles sous forme de cartes côte à côte (voir Construction). Les fonctionnalités purement textuelles obtiennent une introduction en gras et une ligne.
  5. Démarrage rapide — copiable-collable, dans l'ordre, chaque commande vérifiée par rapport au projet. Prérequis d'abord.
  6. Utilisation — un ou deux exemples réels : une commande et sa sortie, un extrait de code, ou un bloc de configuration.
  7. Comment ça marche — optionnel. Un court paragraphe ou un diagramme Mermaid quand l'architecture est la partie intéressante.
  8. Tout le reste de l'ancien README — configuration, FAQ, feuille de route, contribution, crédits — rangé, plié dans <details> quand c'est long.
  9. Pied de page — ligne de licence, plus la bande artistique de fermeture (voir Construction).

Lois du README

  • Vrai. Chaque affirmation, chiffre, fonctionnalité et badge doit être soutenu par le projet. Pas d'étoiles, téléchargements, benchmarks, témoignages ou logos « utilisé par » inventés. Un badge n'apparaît que si ce vers quoi il pointe existe (un paquet publié, un vrai workflow, un fichier de licence).
  • Fonctionne. Chaque commande dans Démarrage rapide et Utilisation existe dans le projet telle qu'écrite. Si tu peux l'exécuter en toute sécurité (installer, construire, --help, tests), fais-le. Si une étape nécessite des secrets ou un service payant, dis-le clairement au lieu de le cacher.
  • Test des cinq secondes. Quelqu'un qui atterrit sur le dépôt depuis un tweet sait ce que c'est, le voit fonctionner, et trouve la commande d'installation sans défiler au-delà du premier écran.
  • Montre la chose. La démo montre le vrai produit en action, pas une animation de logo ou un art abstrait. Réutilise l'interface réelle, le CSS réel, le texte réel.
  • Dis ce qu'est le dépôt. Si le dépôt est le site web, la page d'atterrissage ou la démo pour un produit, dis-le dans l'accroche ; n'implique pas que les gens peuvent télécharger une application ou installer un paquet que le dépôt ne fournit pas.
  • Spécifique. Il doit sembler écrit pour ce projet exact. « Ultra-rapide », « transparent », « nouvelle génération », « rationalisez votre flux de travail » sont interdits, sauf si le projet les mérite mesurablement.
  • Scannable. Paragraphes courts, titres qui disent quelque chose, une idée par puce. Émojis dans les titres seulement si la propre voix du projet les utilise, et alors avec parcimonie (le style showcase est l'exception : un émoji par titre de section, par conception).
  • Les deux thèmes. Les lecteurs GitHub utilisent le mode clair et le mode sombre. Chaque image a un bon rendu sur #ffffff et sur #0d1117 : PNG transparents avec une bordure visible, ou <picture> avec une source prefers-color-scheme par thème.
  • S'adapte à la colonne. La colonne README fait environ 830 px de large sur desktop et beaucoup moins sur téléphone. Le texte de la bannière reste lisible lorsqu'il est réduit à la largeur du téléphone ; les tableaux ont peu de colonnes ; pas de grandes mises en page HTML brutes qui cassent sur mobile.
  • Chaque lien résout. Les liens relatifs pointent vers des fichiers qui existent ; les ancres correspondent aux titres réels.

Styles

StyleSensationQuand l'utiliser
cleanHéros animé avec mouvement retenu, démo encadrée, cartes soignéesLa plupart des projets ; le défaut
boldHéros à fond perdu dans les couleurs de la marque avec un moment animé plus grand, accroche percutante, démo au premier planApplications grand public, projets ludiques, lancements
minimalPetit logo animé + nom + accroche, sections simplesBibliothèques, CLI, infrastructure, outils sérieux
showcaseLe README technique dense avec sections émojies (pense à un hackathon gagnant ou un projet de recherche) : une vraie capture d'écran du produit en haut, une ligne de prix ou de statut, puis une section menée par un émoji par sujetHackathon, recherche, ML, données, ou projets scientifiques ; tout ce qui a une vraie profondeur à montrer. Choisis-le quand l'utilisateur demande « quelque chose comme Find My Shark » ou un README détaillé de style documentation

La recette showcase

Modélisé sur le README Find-My-Shark du propriétaire. Garde ce qui le fait fonctionner, et corrige ce qui ne fonctionne pas :

  • Titre avec un émoji et la ligne de réussite en dessous (« NASA Space Apps 2025, Galactic Impact Winner »), seulement si le projet l'a vraiment mérité. Demande ou lis-le depuis l'ancien README ; n'en invente jamais un.
  • Une vraie capture d'écran ou le GIF démo directement sous le titre, encadré (voir Démo, encadré). Garde le héros animé seulement s'il ajoute quelque chose ; ici, le vrai produit est la star.
  • Un pitch de 2 à 3 lignes et la ligne « pourquoi c'est important », puis des sections chacune menée par un émoji : Fonctionnalités, Région/Portée ou Entrées, Sources de données (tableau), Comment ça marche ou Modèle mathématique, Démarrage rapide (installation, utilisation de base, utilisation de l'API), Structure du projet (arbre annoté), Configuration (la vraie config), Fichiers de sortie, Options de ligne de commande, Contexte, Extensions futures, Tests, Journalisation, tagline de clôture.
  • Inclus seulement les sections pour lesquelles le projet a un contenu réel. La profondeur de niveau hackathon est le but, donc garde les spécificités : paramètres, formules, seuils, noms d'ensembles de données et arbre du projet.
  • Corrige les erreurs habituelles : utilise l'URL de clone réelle (jamais votre-nom-utilisateur), remplace les entrées obsolètes du bloc de code de l'arbre du projet par ce qui existe, ajoute une table des matières ou une ligne de liens rapides quand il y a plus de six sections, enveloppe les longues sections de référence (options CLI, configuration complète, contexte scientifique) dans <details>, ajoute des badges pour la pile réelle (version Python, licence, bibliothèques clés) et une <picture> ou une capture d'écran encadrée pour les deux thèmes, et définis la description et les sujets du dépôt à la livraison.
  • Ancres avec émoji : GitHub supprime l'émoji du slug d'un titre mais garde le trait d'union, donc ## 🚀 Démarrage rapide devient #-démarrage-rapide, pas #démarrage-rapide. Écris chaque lien de navigation et lien de badge de cette façon et vérifie chacun par rapport à son titre. Le résumé <details> n'est pas un titre et n'a pas d'ancre.
  • Suis toujours chaque loi du README (Vrai, Fonctionne, Les deux thèmes) et l'étape Vérification.

3. Construction

Les meilleurs README sur GitHub (Excalidraw, Scalar, Supabase, Charm, Rich, Bun) partagent quelques astuces. Utilise-les toutes ; c'est ce qui fait que celui-ci arrête le défilement.

Le héros : un SVG animé

C'est la signature. Une bannière statique se lit comme un modèle ; un héros qui bouge — dans les propres couleurs, polices et interface du projet — se lit comme fait pour ce projet. GitHub rend un SVG dans une balise <img> avec son CSS @keyframes en cours d'exécution, donc le héros peut animer sans les bandes ou le poids d'un GIF.

Construis .github/readme/hero.svg (viewBox environ 1600×800, rendu à width="100%") :

  • La scène est le produit. Recrée le vrai héros du projet ou l'écran clé en formes SVG : son image de fond, son titre dans sa propre police, et un élément d'interface réel faisant son travail (une carte glissant, une commande tapant, un graphique se dessinant, un toast atterrissant). Une idée, une boucle.
  • Mouvement : CSS @keyframes dans un bloc <style> à l'intérieur du SVG, seulement sur transform et opacity, avec transform-box: fill-box; transform-origin: center sur tout ce qui se met à l'échelle ou tourne. Une boucle de 6 à 10 s qui revient à son image de départ de manière transparente, entrées décalées, chaque ligne de texte installée assez longtemps pour être lue. Ajoute une dérive lente sur le fond (une échelle de 1,0 à 1,05 sur la boucle) pour que l'image ne donne jamais l'impression d'être figée. Une transform CSS remplace l'attribut transform SVG d'un élément, donc positionne les choses avec un <g transform=…> extérieur et anime un élément intérieur.
  • Mouvement réduit : enveloppe les keyframes dans @media (prefers-reduced-motion: no-preference) pour que les lecteurs qui optent pour moins d'animation voient l'image terminée et stable. L'image stable doit pouvoir être publiée seule et montrer le produit, donc tout ce qui n'apparaît qu'au milieu de la boucle (une superposition de correspondance, un toast) commence caché avec un attribut opacity="0" et n'est révélé que par ses keyframes.
  • Autonome. Un SVG chargé via <img> ne peut rien récupérer : pas de polices web par URL, pas d'images externes, pas de scripts. Incorpore les polices en base64 @font-face (les fichiers latin de Google Fonts font déjà ~20 Ko et peuvent être incorporés en entier ; sous-ensemble d'autres polices avec pyftsubset … --text="…" --flavor=woff2, ce qui nécessite une version récente de fontTools), ou convertis le texte en chemins. Incorpore les photos en base64 JPEG, redimensionnées à ce dont le héros a besoin. Évite <foreignObject> (Safari ne le rendra pas à l'intérieur d'<img>). Garde le fichier sous ~1,5 Mo.
  • Les deux thèmes. Si le héros est à fond perdu et opaque, il fonctionne sur les deux ; sinon, crée aussi hero-dark.svg et échange avec <picture> ou les fragments d'URL #gh-dark-mode-only / #gh-light-mode-only.
  • Texte : le nom du projet et l'accroche, en grand (le héros rétrécit à ~40 % sur téléphone). Rien d'autre.
<p align="center">
  <a href="<lien site ou démo>"><img src=".github/readme/hero.svg" alt="<Projet> — <accroche>" width="100%"></a>
</p>

Capture aussi l'image stable à 1280×640 vers .github/readme/social-preview.png (opaque) pour la carte sociale du dépôt ; rends le SVG dans un navigateur sans tête avec mouvement réduit activé.

Si le projet n'a pas d'identité visuelle digne d'être animée (une bibliothèque sans interface), fais plutôt un mot-symbole animé : le nom dans une police appropriée, un mouvement qui dit ce qu'il fait (une valeur circulant dans un tuyau, du texte formaté, un test devenant vert).

Démo, encadrée

Par ordre de préférence :

  1. La vidéo brag. Celle trouvée lors de l'Inspection ou créée à l'étape La vidéo. Si un brag.mp4 existe, fais un GIF de prévisualisation en boucle ou un WebP animé à partir de ses 4 à 8 secondes les plus fortes, redimensionné à une largeur de 800 px, limité à 30 ips et à une palette de 256 couleurs. Pour la capture d'écran vidéo, utilise l'image brag.jpg la plus récente existante ou la dernière image de la vidéo, redimensionnée à 1280×720, opacifiée sur un fond de la couleur de fond du dépôt (#ffffff ou #0d1117) pour que la transition de thème soit propre en <picture>, et stockée dans .github/readme/demo-preview.png.
  2. Une vraie capture d'écran du produit. Ouvrir l'URL du projet ou le serveur de développement, capturer la fenêtre du navigateur à 1280×800 (image fixe, pas de GIF), recadrer pour supprimer les chrome du navigateur, superposer une légère bordure du trait de la couleur de la marque, et

… [tronqué pour la traduction]

README Lois (suite)

  • Fonctionne. Chaque commande dans Démarrage rapide et Utilisation existe dans le projet telle qu'écrite. Si tu peux l'exécuter en toute sécurité (installer, construire, --help, tests), fais-le. Si une étape nécessite des secrets ou un service payant, dis-le clairement au lieu de le cacher.
  • Test des cinq secondes. Quelqu'un qui atterrit sur le dépôt depuis un tweet sait ce que c'est, le voit fonctionner, et trouve la commande d'installation sans défiler au-delà du premier écran.
  • Montre la chose. La démo montre le vrai produit en action, pas une animation de logo ou un art abstrait. Réutilise l'interface réelle, le CSS réel, le texte réel.
  • Dis ce qu'est le dépôt. Si le dépôt est le site web, la page d'atterrissage ou la démo pour un produit, dis-le dans l'accroche ; n'implique pas que les gens peuvent télécharger une application ou installer un paquet que le dépôt ne fournit pas.
  • Spécifique. Il doit sembler écrit pour ce projet exact. « Ultra-rapide », « transparent », « nouvelle génération », « rationalisez votre flux de travail » sont interdits, sauf si le projet les mérite mesurablement.
  • Scannable. Paragraphes courts, titres qui disent quelque chose, une idée par puce. Émojis dans les titres seulement si la propre voix du projet les utilise, et alors avec parcimonie (le style showcase est l'exception : un émoji par titre de section, par conception).
  • Les deux thèmes. Les lecteurs GitHub utilisent le mode clair et le mode sombre. Chaque image a un bon rendu sur #ffffff et sur #0d1117 : PNG transparents avec une bordure visible, ou <picture> avec une source prefers-color-scheme par thème.
  • S'adapte à la colonne. La colonne README fait environ 830 px de large sur desktop et beaucoup moins sur téléphone. Le texte de la bannière reste lisible lorsqu'il est réduit à la largeur du téléphone ; les tableaux ont peu de colonnes ; pas de grandes mises en page HTML brutes qui cassent sur mobile.
  • Chaque lien résout. Les liens relatifs pointent vers des fichiers qui existent ; les ancres correspondent aux titres réels.

4. Vérification

Relis le README modifié avec un regard neuf. Résout-il chaque loi du README ? Es-tu prêt à le défendre face à l'utilisateur ?

  • Le README est vrai. Pas de distorsion. Pas de fonctionnalité manquante comme expédiée. Pas de badge de constructeur de communauté pour un projet solo. Vérifie chaque badge contre sa source : le paquet est-il sur PyPI (pip install nom-paquet fonctionne), npm (npm view nom-paquet retourne un JSON), crates.io, etc. ? Le workflow de test a-t-il une mauvaise note ?
  • Il tourne. Relis chaque commande que tu as écrite. Vérifie le message de validation le plus récent pour le répertoire de travail du projet : est-ce que l'installation réussit ? Les tests passent-ils ? Les chemins de fichiers sont-ils exacts ?
  • L'image de héros se charge dans un <img> SVG (pas d'images externes, pas de <foreignObject>, pas de polices à récupérer).
  • Les thèmes clair et sombre. Les images transparentes ont une légère bordure ou un arrière-plan pour être lisibles dans les deux thèmes, ou utilise <picture>.
  • Les ressources sont engagées. Les images et le SVG dans .github/readme/ sont engagés dans le dépôt avant de livrer le README.
  • Le plan est complet. brag-output/repo/ contient readme-plan.md, le README révisé (README.md), et chaque ressource visuelle (.github/readme/hero.svg, hero-dark.svg, social-preview.png, demo-preview.gif ou .webp, demo-preview.png, et toutes les images de vitrine de fonctionnalités).

Configuration du dépôt

Avant de finaliser, ajuste les métadonnées du dépôt pour qu'elles correspondent au nouveau README :

  • Description : l'accroche, en une phrase (max 350 caractères).
  • Sujets : 3–8 sujets pertinents (langage, framework, cas d'usage, nom de l'outil).
  • Site web : l'URL du site ou de la page de démo (pas le dépôt lui-même).
  • Image sociale : .github/readme/social-preview.png.

5. Livraison

Écris le README finalisé dans README.md (ou dans brag-output/repo/README.md si --preview).

Confirme dans la sortie :

  • Le nom du projet
  • Un résumé de la structure : « Héros animé · Démo · Fonctionnalités (N) · Démarrage rapide · Pied de page »
  • Les badges ajoutés et leur justification (par exemple « Badges : la licence MIT a un fichier → badge », « npm publié → badge de version et de téléchargements », « Workflow CI → badge de build passant »)
  • Les ressources créées : les chemins de fichiers vers le SVG du héros et l'image de démo (relatifs à la racine du dépôt)
  • Ce qui est conservé de l'ancien README : sections, notes de licence, crédits, etc.
  • Changer l'angle du concept si l'accroche originale était trompeuse
  • Toute vidéo ou démo créée, où elle a été placée, et comment l'utiliser ultérieurement

Pour que le dépôt soit aussi beau que le projet qu'il contient.

Skills associés