Aperçu : page HTML avec sélection pour commentaires
Transforme n'importe quel plan, proposition, brouillon ou texte finalisé en une page HTML où l'on peut « sélectionner du texte → ajouter un commentaire », ouverte sur l'ordinateur de l'utilisateur pour qu'il (ou son client) puisse réviser. Après lecture, cliquez sur « Tout copier » : les commentaires et les cases cochées deviennent un markdown à coller dans la conversation pour appliquer les modifications.
Où se trouve ce fichier
Le dossier contenant ce fichier est le dossier de la compétence (noté $SKILL_DIR ci-dessous). Définissez-le avant chaque exécution :
SKILL_DIR="${CLAUDE_SKILL_DIR:-$HOME/.claude/skills/preview}"
[ -f "$SKILL_DIR/scripts/md-to-preview.py" ] || SKILL_DIR="$(cd "$(dirname "$(find "$HOME/.claude/skills" .claude/skills -path '*/preview/scripts/md-to-preview.py' 2>/dev/null | head -1)")/.." && pwd)"
echo "$SKILL_DIR"
- Nécessite Python 3.9 ou supérieur, utilise uniquement la bibliothèque standard, pas de pip.
- Sur macOS :
python3; sur Windows sipython3n'est pas disponible, utilisezpythonoupy. - Si le dossier de la compétence est introuvable, arrêtez-vous et demandez à l'utilisateur de vérifier que le dossier
previewse trouve dans~/.claude/skills/, sans créer vous-même une autre fonctionnalité de commentaires.
| Fichier | Usage |
|---|---|
scripts/md-to-preview.py | Générateur principal : conversion md en page d'aperçu |
scripts/convert/inject.py | HTML déjà mis en page, ajoute uniquement les fonctions de commentaire |
scripts/convert/visuals.py, flow.py, tables.py | Composants visuels, organigrammes, conversion de tableaux (appelés automatiquement par le générateur) |
assets/preview-comment-overlay.html | Interface de commentaire par sélection |
assets/preview-tokens.css | Couleurs, polices, espacements ; modifiez l'apparence ici |
assets/fonts/ | Polices intégrées Noto Sans TC, Geist, Geist Mono (licence SIL OFL) |
assets/example.md | Exemple complet : une fausse proposition de projet, tous les composants utilisés |
Règle 1 : Les commentaires sont toujours « par sélection »
Lorsque l'utilisateur dit « ajouter des commentaires » ou « une version commentable », il s'agit toujours de sélectionner du texte puis d'ajouter un commentaire, comme dans Google Docs, et non d'une zone de saisie à côté de chaque paragraphe. L'interface de commentaire de cette compétence est celle par sélection ; utilisez-la directement, sans en créer une autre.
Règle 2 : Réécrire d'abord, générer ensuite
D'abord déterminer le type de page
| Type | Exemple | Traitement |
|---|---|---|
| Explicatif | Plan, proposition, rapport, comparaison, page à valider | Réécrire selon les règles ci-dessous pour une version facile à lire, puis générer la page. Ne pas envoyer le brouillon directement dans le générateur. |
| Révision de texte original | Contrat, texte finalisé, transcription, texte client | Ne pas modifier un seul mot du contenu, générer la page avec --no-lint ; éventuellement ajouter un > [!Conclusion] au début pour indiquer ce que la page doit montrer. |
Règles d'écriture pour les pages explicatives
- Tout dire dans le premier écran : Commencez par
> [!Conclusion]pour résumer en une phrase, puis> [!À vous de décider]pour lister ce que le lecteur doit faire. Le contexte vient après, le lecteur peut décider sans faire défiler. - Ne dire qu'une fois : Ce qui est dit dans le cadre de conclusion n'est pas répété dans le texte. Ce qui est montré par un graphique ou un tableau n'est pas redit en paragraphe. Pas de section « Résumé ».
- Langage simple : Utilisez les mots courants du lecteur. La première occurrence d'un terme technique doit être accompagnée d'une métaphore ou d'un
> [!En clair]pour l'expliquer. - Montrer plutôt qu'écrire : Demandez-vous « quelle relation décrit ce passage » et choisissez le composant correspondant dans le tableau ci-dessous. Un paragraphe purement textuel ne doit pas dépasser trois lignes ; chaque section
##doit contenir au moins un composant visuel ou un tableau. - Court : Une idée par phrase. Supprimez les formules d'introduction comme « autrement dit », « c'est-à-dire », « il est à noter que ».
- Supprimez les répétitions, pas l'information : Chiffres, dates, noms, conséquences : rien ne doit être supprimé ou modifié.
Guide rapide des composants visuels
Écrivez quelques lignes de syntaxe, le générateur dessine le graphique. Utilisez le séparateur ｜ (pleine largeur) et la flèche →. Consultez assets/example.md pour la syntaxe complète.
| Ce que décrit le passage | Composant | Syntaxe |
|---|---|---|
| Ancien vs nouveau, maintenant vs après modification | Comparaison | ```comparaison : première ligne Maintenant → Après modif, puis chaque ligne élément｜ancien → nouveau |
| Composition du système, flux de données | Architecture | ```architecture : chaque ligne un niveau niveau｜boîte, boîte ; si ordre à l'intérieur : A → B ; possibilité d'insérer une ligne ↓ description entre deux niveaux |
| Quand se produit quoi | Chronologie | ```chronologie : chaque ligne moment｜titre｜description ; ✅ pour terminé, 👉 pour maintenant |
| Ordre, étapes, chaîne de cause à effet | Étapes | ```étapes : chaque ligne titre｜description, numérotation automatique ; jusqu'à 4 étapes en ligne, 5+ en colonne |
| Quelques chiffres clés | Chiffres | ```chiffres : chaque ligne nombre unité｜étiquette｜note ; espace entre le nombre et l'unité pour réduire la police |
| Plusieurs options, qui fait quoi, éléments en parallèle | Cartes | ```cartes (ou options, répartition) : chaque ligne titre｜une ligne｜une ligne ; ★ en début de ligne marque l'option recommandée |
| Comparaison multi-colonnes | Tableau | Tableau md standard. Si l'en-tête contient à la fois « maintenant/ancien » et « après modif/nouveau/suggestion », la colonne ancienne devient grise, la nouvelle vert pâle |
| Processus avec branchements | Cartes de processus | Diagramme ASCII ou mermaid (graph/flowchart en TD, LR) ; si la conversion échoue, le contenu original est conservé |
| Conclusion, décision, attention, risque | Cadre important | > [!Conclusion] titre, puis > contenu. Utilisez : Conclusion, À vous de décider, Attention, Risque, Terminé, En clair, Explication |
| Statut | Étiquette couleur | En ligne : {vert:Terminé} {jaune:En attente} {rouge:Bloqué} {bleu:En cours} {gris:Abandonné} |
| Mot-clé dans une phrase | Soulignement | ==mot-clé==, un seul par paragraphe maximum |
- Les couleurs ont une signification fixe : bleu pour conclusion et information, vert pour terminé et après modification, jaune pour attention et attente, rouge pour risque et bloqué. « À vous de décider » apparaît une seule fois par page.
- Une erreur de syntaxe ne casse pas la page ; elle se transforme en bloc de code gris. Vérifiez après génération qu'aucun élément n'est resté en gris.
- Utilisez les étapes ou la chronologie pour les relations de cause à effet ou d'ordre ; les cartes pour les éléments indépendants.
- Le texte dans les graphiques est du vrai texte, sélectionnable pour commentaire.
Inspection de mise en page
Lors de la génération, une « inspection de mise en page » est automatiquement affichée : pas de cadre de conclusion au début, un paragraphe trop long, trop peu de composants visuels, répétitions, tirets, etc. Si des alertes apparaissent, modifiez le md et relancez jusqu'à obtenir « Inspection de mise en page : réussie ». Pour les révisions de texte original, ajoutez --no-lint.
Économie de ressources
- Les graphiques utilisent toujours la syntaxe courte, pas de HTML ou SVG fait à la main, pas d'images supplémentaires.
- Pour modifier le contenu, modifiez le md et relancez, ne modifiez pas directement le HTML de sortie.
- Pour les longues listes, utilisez
--fold "3"pour les masquer.
Règle 3 : Toujours utiliser le générateur
- La page d'aperçu est toujours générée avec
scripts/md-to-preview.py(source md) ouscripts/convert/inject.py(HTML déjà mis en page). N'écrivez pas de CSS à la main, ne créez pas vous-même une fonctionnalité de commentaire. - Pour modifier l'apparence, modifiez
assets/preview-tokens.csset relancez le générateur.
Processus d'exécution
Étape 1 : Déterminer la source et l'identité
Déduisez de la conversation ; si impossible, demandez :
- Quel contenu prévisualiser ? (contenu juste écrit dans la conversation, fichier fourni par l'utilisateur)
- Qui commentera ? Identité par défaut
moi,visiteur. Pour un client, utilisez par exempleclient,mol(le premier est l'identité par défaut).
Si la source est du contenu de la conversation, sauvegardez-le d'abord en fichier md dans le répertoire de travail actuel de l'utilisateur (ou dans un dossier Aperçu sur le bureau si aucun), avec un nom de fichier en chinois décrivant le contenu, par exemple Proposition-ClientExemple.md.
Étape 2 : Générer la page
Source en md (cas le plus courant) :
python3 "$SKILL_DIR/scripts/md-to-preview.py" "<source>.md" "<sortie>.html" \
--identities "moi,visiteur" --badges "brouillon,2026-10-19"
| Paramètre | Rôle |
|---|---|
--identities | Liste des identités, séparées par des virgules ; la première est l'identité par défaut |
--badges | Petites étiquettes grises sous le titre, séparées par des virgules ; omis si non fourni |
--key | Nom utilisé pour stocker les commentaires dans le navigateur, unique par page ; sinon, utilise le nom du fichier de sortie |
--title | Titre du document ; sinon, utilise le premier titre # du md |
--fold "3,4" | Plie les titres des niveaux spécifiés en sections dépliables, pour les longues pages |
--no-lint | Pas d'inspection de mise en page (pour les textes originaux comme les contrats) |
--no-overlay | Version propre sans fonctionnalité de commentaire |
--icon | Caractère ou emoji pour l'icône de l'onglet ; sinon, utilise le premier caractère du titre |
--fonts copy／link／none | Traitement des polices, par défaut copy |
Polices : Par défaut, un dossier preview-fonts/ est créé à côté du HTML de sortie. 🚨 Pour envoyer à quelqu'un, le HTML et le dossier preview-fonts/ doivent être envoyés ensemble. Un simple HTML utilisera les polices système (fonctionnel, mais moins esthétique).
Images : Dans le md, une balise  sur une ligne seule devient une image avec légende, le chemin étant relatif au HTML de sortie.
Source déjà en HTML mis en page (par exemple une proposition faite à la main) : ne modifiez pas la mise en page, ajoutez uniquement la fonction de commentaire.
python3 "$SKILL_DIR/scripts/convert/inject.py" "<page>.html" -o "<page>-commentaire.html" --identities "moi,client"
-odoit être un nouveau fichier, l'outil n'écrase pas la source.- Si la page a déjà des commentaires et que vous voulez une nouvelle version, ajoutez
--replace.
Étape 3 : Ouvrir pour l'utilisateur
Ouvrez avec le navigateur par défaut :
# macOS
open "<sortie>.html"
# Windows (le terminal de Claude est Git Bash, utilisez start ; PowerShell utilisez Start-Process "<sortie>.html")
start "" "<sortie>.html"
# Linux
xdg-open "<sortie>.html"
Dites trois choses à l'utilisateur :
- Sélectionnez n'importe quel texte pour faire apparaître « Ajouter un commentaire ».
- Les cases à cocher peuvent être cochées directement.
- Après lecture, cliquez sur « Tout copier » en haut à droite et collez le contenu dans la conversation.
Étape 4 (optionnelle) : Commentaires du client
- Compressez le HTML et le dossier
preview-fonts/en un zip, envoyez-le au client, demandez-lui de décompresser et double-cliquer sur le HTML. - Définissez l'identité pour correspondre au rôle du client, par exemple
--identities "client,moi". - Les commentaires sont stockés dans le navigateur du client et ne sont pas synchronisés automatiquement. Demandez au client d'appuyer sur « Tout copier » et de vous renvoyer le texte par email ou message.
Cases à cocher
Lorsque l'utilisateur doit décider élément par élément d'une liste, et que les options sont fixes, créez des cases à cocher plutôt que de lui demander de répondre par écrit. Par exemple : une liste de fonctionnalités à implémenter ou non, une sélection de ressources, une liste de contrôle avant mise en ligne. Pour une ou deux options seulement, ou si une justification est nécessaire, posez directement la question ou utilisez le commentaire par sélection.
Comment écrire
Dans le md, écrivez sous forme de liste de tâches ; le générateur les transformera en cases cliquables :
### À faire absolument
- [x] Formulaire de commande (après remplissage, insertion automatique en base de données)
- [ ] Calendrier des plannings (chaque employé voit uniquement ses propres plages)
- [ ]non coché,- [x]pré-coché.- Chaque groupe est placé sous son propre titre (
##ou###) : à l'exportation, le groupe est déterminé par le titre le plus proche. - Chaque élément doit avoir un nom et une explication, compréhensible indépendamment ; n'écrivez pas simplement « oui » ou « non ».
- Sous le même titre, pas deux options identiques.
Ce qui se passe côté utilisateur
- L'état des cases est sauvegardé dans son navigateur ; un rafraîchissement ne le perd pas. « Effacer » ne supprime que les commentaires, pas les cases.
- Lorsque l'utilisateur clique sur « Tout copier », un bloc supplémentaire est ajouté au début :
## Résultat des cases (cochées 2/5)
### Confirmation du périmètre › À faire absolument
- [x] Formulaire de commande (après remplissage, insertion automatique en base de données)
- [ ] Calendrier des plannings (chaque employé voit uniquement ses propres plages)
Lors de la réception du résultat des cases
- Sauvegardez le résultat des cases tel quel dans un fichier ; suivez-le scrupuleusement, ne le retapez pas de mémoire.
- Les éléments non cochés sont à ne pas faire ou à laisser en l'état ; n'ajoutez pas votre propre jugement.
- Si des éléments contradictoires sont cochés dans le même groupe, demandez à l'utilisateur.
- Pour les actions ayant un impact externe (envoi d'email, suppression de fichier, mise en ligne), listez d'abord la liste finale et n'agissez que lorsque l'utilisateur dit « Fais-le ».
Comment appliquer le « Résumé des commentaires » reçu
Lorsque l'utilisateur clique sur « Tout copier » et colle le contenu, il se présente ainsi : chaque commentaire contient le texte original sélectionné (citation), la position (titre de paragraphe), le contexte et le contenu du commentaire.
Interprétation un par un
| Aspect du commentaire | Interprétation |
|---|---|
| Seulement un nouveau texte, sans verbe | Remplacer : remplacer la citation par le texte du commentaire |
| « Supprimer », « Enlever » | Supprimer le passage de la citation (uniquement la portée de la citation) |
| « Ajouter », « Compléter », « Encore un ci-dessous » | Ajouter : ajouter du contenu près de la citation |
| Descriptif (« pourrait-on… », « j'aimerais… ») | Modifier selon la demande |
| Flou, interprétation ambiguë | Choisir la modification la plus minimale, et signaler clairement votre choix |
- Utilisez d'abord la « position » et le « contexte » pour trouver le bon endroit avant de modifier. Si le même texte apparaît plusieurs fois sur la page, utilisez le contexte pour ne cibler qu'un seul endroit.
- Les commentaires d'une même série peuvent être redondants avec ceux de la série précédente ; comparez d'abord ceux déjà modifiés.
Appliquer, relancer, rouvrir
- Modifiez le md original, puis relancez le générateur avec la même commande et le même
--key; ne modifiez pas directement le HTML de sortie (il serait écrasé lors de la prochaine exécution). Le même--keypermet de conserver les anciens commentaires. - Rouvrez la page pour l'utilisateur.
- Rapportez : pour chaque commentaire, dites « commentaire X → modification effectuée ». Pour les cas flous, indiquez votre choix.
Mémorandum technique (pour Claude, pas à communiquer à l'utilisateur)
- L'ancrage des commentaires utilise le « texte sélectionné + contexte » ; de petites modifications du contenu permettent toujours de retrouver la position ; si introuvable, marquez « Texte original modifié ».
- La surbrillance utilise l'API CSS Custom Highlight du navigateur, ne modifie pas la structure de la page. Chrome, Edge, Safari récents la prennent en charge ; les navigateurs incompatibles perdront uniquement la surbrillance jaune, les commentaires dans la barre latérale fonctionnent toujours.
- Les commentaires et les cases sont stockés dans le
localStoragedu navigateur, chaque page avec un--keydifférent, sinon les commentaires de pages différentes se mélangent. - L'interface de commentaire expose
window.PreviewCommentsaprès chargement :.refresh()pour repositionner les surbrillances,.data()pour récupérer tous les commentaires,.exportMd()pour retourner le markdown exporté. - Les popups de la page doivent avoir un z-index inférieur à 10400, sinon les boutons de commentaire seront masqués.