Communitygithub.com

expliquer-html

Montre à un agent comment planifier, construire ou découper une page « html explainer » pour que le résultat concret soit un texte ou un script utilisable. La procédure suit les pages HTML explainer, les fichiers de cette compétence, l'apparence. À utiliser lorsqu'une nouvelle tâche nécessite cette technique.

Qu'est-ce que expliquer-html ?

Cette compétence est conçue pour les agents IA (comme Claude Code, Cursor, etc.) qui doivent créer ou modifier des pages HTML d'explication technique — appelées « HTML explainer pages ». Elle fournit un processus structuré pour produire des pages minimales, ciblées, avec uniquement le contenu demandé par l'utilisateur, et en suivant un design sombre cohérent avec des liens en « pilules bleues ». La compétence s'appuie sur des fichiers de référence (modèle HTML, design, écriture, diagrammes) et impose l'utilisation exclusive de diagrammes de type « swimlane » (normaux ou jouables). Elle explique comment décider des sections d'une page en fonction de la question posée (problème, tâche, exploration), comment lier les pages entre elles, et décrit un workflow en 6 étapes allant de la recherche du ticket à la vérification finale. Les contrôles de qualité incluent la vérification que chaque diagramme est un swimlane, que les liens sont corrects, qu'aucune section superflue n'est ajoutée, et que le rendu Mermaid est sans erreur.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/frhn-xo/html-explainer/tree/HEAD/skills/html-explainer

Demander à votre IA préférée

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

Documentation

Pages HTML explainer

L'utilisateur lit ces pages dans un navigateur et Cmd+clique depuis elles directement dans VS Code. Il comprend un flux depuis une swimlane beaucoup plus rapidement qu'à partir de paragraphes, et il veut que chaque page réponde à ce qu'il a demandé et rien de plus.

Fichiers de cette compétence

  • assets/template.html : le point de départ de chaque page. Copiez-le, ne créez jamais une page à partir de zéro.
  • references/DESIGN.md : le design que chaque page suit, toujours dans sa forme sombre, avec chaque lien une pilule bleue (references/page.md, « L'apparence »). Lisez-le quand une page nécessite une couleur ou un élément que le modèle ne possède pas.
  • references/page.md : nom du fichier et emplacement, la barre latérale, les liens vers les fichiers, la section des tâches, la section Pages liées, les pages maîtres et explainer. Lisez-le lors de la création d'une page ou de la modification de sa structure.
  • references/writing.md : la section problème et tout texte en prose. Lisez-le avant d'écrire du texte.
  • references/diagrams.md : à quoi ressemble une swimlane et comment la vérifier. Lisez-le avant de dessiner ou de modifier un diagramme.
  • references/playable.md, assets/player.js, assets/player.css : swimlanes jouables. Lisez-les quand l'utilisateur dit « jouable », ou lors de la modification d'une page qui contient un div.player.

L'apparence

Chaque page suit references/DESIGN.md, toujours en sombre, avec chaque lien une pilule bleue pour qu'il se démarque comme cliquable : souligné pour un fichier, ↗ pour une autre page, ni l'un ni l'autre pour une section de la même page (references/page.md, « L'apparence : DESIGN.md, toujours sombre » et « Trois types de liens »). Le modèle fait déjà cela. Chaque diagramme se trouve dans un panneau que le lecteur peut redimensionner, zoomer et faire glisser (references/diagrams.md, « Le bloc diagramme »).

Gardez la page minimale

Une page ne contient que ce que l'utilisateur a demandé. Toute section, tableau ou note supplémentaire est quelque chose qu'il doit parcourir pour trouver la réponse.

  • Sections : uniquement celles dont la demande a besoin. Une swimlane avec un court paragraphe autour constitue une section. N'ajoutez jamais une section que l'utilisateur n'a pas demandée : pas de résumés, pas d'inventaires, pas de section « raisons », pas de registre des décisions passées.
  • Tableaux : seulement lorsque l'utilisateur en demande un. Écrivez plutôt des paragraphes et des swimlanes.
  • Sous un diagramme : rien. Pas de liste de fichiers, pas de notes, pas de ligne « non dessiné ». Si une phrase est nécessaire pour lire le diagramme, elle se trouve dans le paragraphe qui le précède.

Quelles sections une demande reçoit

Adaptez la page à la question :

  • « Quel est le problème », débogage, correction d'un bug : d'abord la section problème (references/writing.md), contenant une swimlane du bug (sur une page maître, une page jouable, references/playable.md). Ensuite, toutes les swimlanes supplémentaires nécessaires à l'explication.

  • Implémentation d'une fonctionnalité ou correction d'un bug, une fois les tâches discutées : une section tâche juste en dessous de la section problème (references/page.md, « La section tâche »). Tant que l'utilisateur est encore en train de cerner le problème, il n'y a pas encore de tâches, donc il n'y a pas de section tâche.

  • « Comment cela fonctionne-t-il », « De quoi parle ce projet » : pas de section problème, pas de section tâche. Une swimlane du flux, avec de courts paragraphes là où ils aident.

  • « Comment construire quelque chose comme ça » : une seule section : la swimlane habituelle pour cela, les fonctionnalités supplémentaires qui pourraient être ajoutées et comment procéder.

  • Toute page liée à d'autres pages (une page maître et ses explainers, ou des pages que l'utilisateur demande de lier) : une section Pages liées tout en bas (references/page.md, « La section Pages liées »).

Tout le reste : répondez à la question avec le moins de sections qui y répondent.

Diagrammes : uniquement des swimlanes

Il existe deux types de diagrammes, et seulement deux :

  1. Swimlane : un organigramme avec une boîte par acteur ou système, des étapes à l'intérieur de la boîte qui les exécute, des flèches traversant les boîtes lorsque le travail se déplace (references/diagrams.md).
  2. Swimlane jouable : la même swimlane avec des boutons Réinitialiser / Précédent / Suivant / Lire, une flèche par pression, et une légende en dessous (references/playable.md). « Jouable », « swimlane jouable », « diagramme jouable » et « avant/après jouable » signifient tous cela. « Swimlane » seul signifie une swimlane simple.

Toute autre demande de diagramme (« un diagramme Mermaid », « dessinez le flux », « un diagramme de cela ») reçoit une swimlane.

Workflow

  1. S'agit-il d'un explainer d'une page maître ? Greppez le dossier du ticket pour une phrase distinctive de la demande, même lorsque l'utilisateur ne colle que le texte d'un élément et ne nomme jamais la page maître. Si cela correspond, la nouvelle page est l'explainer de cette page maître : utilisez le préfixe du nom de fichier de la page maître et liez dans les deux sens dans la même modification (references/page.md).
  2. Créez le fichier (references/page.md, « Le fichier »), copié à partir de assets/template.html. Remplissez les espaces réservés {{…}}, et changez la clé localStorage toc-open-CHANGE-ME en une clé unique pour la page.
  3. Décidez des sections à partir de « Quelles sections une demande reçoit », et écrivez uniquement celles-ci.
  4. Dessinez les swimlanes (references/diagrams.md). Avant de rendre, listez chaque boucle, branche, chemin d'échec et retour anticipé dans le code couvert, et vérifiez que chacun est dessiné.
  5. Lie chaque référence de fichier avec #L<ligne>. Vérifiez que chaque chemin existe et que chaque ligne cible dit réellement ce que le texte prétend.
  6. Exécutez les vérifications ci-dessous, puis rapportez dans le chat avec le lien de la page (ci-dessous). Si quoi que ce soit que le code fait est omis d'un diagramme, dites-le dans cette réponse.

Vérifications avant de dire que c'est terminé

  • La page n'a que les sections nécessaires à la demande : pas de section problème sauf si elle explique un problème, pas de section tâche sauf si des tâches ont été discutées, pas de tableau sauf s'il a été demandé, rien sous un diagramme.
  • Lorsque la page explique ce qu'une personne a dit ou veut, sa première phrase dit ce qu'elle veut, en propres termes que l'utilisateur utiliserait (references/writing.md, « Expliquer ce que quelqu'un voulait dire »).
  • La page conserve l'apparence du modèle : toujours sombre, chaque couleur provenant de references/DESIGN.md, chaque lien une pilule bleue avec sa marque unique, aucun thème clair prefers-color-scheme ajouté (references/page.md, « L'apparence »).
  • Les légendes nomment les significations, pas les couleurs (« là où ça tourne mal », jamais « ocre = … ») ; la page n'a pas de liste de ses propres couleurs (references/page.md).
  • Chaque diagramme est une swimlane : la page n'a pas de sequenceDiagram, stateDiagram, classDiagram ou autre type de diagramme.
  • Rendu de chaque diagramme avec mermaid-cli et vérification du PNG (references/diagrams.md, « Rendre pour vérifier »). La page doit se charger sans erreurs de syntaxe Mermaid.
  • Chaque boîte qui envoie, écrit, appelle ou lit indique à ou depuis où dans son texte, et sa flèche se termine sur la boîte de ce système. Chaque appel à un autre système est une flèche sortante, plus une flèche de retour lorsque l'étape suivante utilise la réponse.
  • Voies de swimlane : greppez la source pour [" "] et ghost ; il ne doit y en avoir aucun. Dans le PNG, aucune boîte de voie n'est plus large ou plus haute que le nécessaire pour ses propres étapes.
  • Une swimlane jouable : parcourez-la du début à la fin et en arrière dans un navigateur.
  • Chaque href et data-href de la barre latérale correspond à un id sur la page, et chaque chemin de lien de fichier existe par rapport à la page.
  • Une page explainer : la page maître y fait référence partout où elle aborde le sujet, et le lead de l'explainer renvoie à la page maître.
  • Pages liées : chaque page liste l'autre dans sa section Pages liées, la section est la dernière de la page, et chaque lien qu'elle contient ouvre un fichier existant.
  • Après avoir changé le statut d'une tâche : un grep liste la classe de case à cocher et le libellé de chaque tâche côte à côte, et toutes les tâches terminées se ressemblent (references/page.md).
  • Un onglet de navigateur ouvert par automatisation est généralement en arrière-plan (document.visibilityState === "hidden"), donc les événements de défilement ne se déclenchent pas là. Testez le scroll-spy en appelant markActive() après chaque scrollIntoView(), et ne concluez pas qu'il est cassé.

Mentionner une page dans le chat

Chaque fois qu'une réponse de chat mentionne une page HTML, donnez deux lignes que l'utilisateur peut coller directement dans la barre d'adresse du navigateur, chacune seule sur sa propre ligne :

file:///Users//<dépôt>/_/.html

/Users//<dépôt>/_/.html

La première ligne est l'URL complète file:///, la seconde est le chemin absolu sur le disque. Rien d'autre ne va sur l'une ou l'autre ligne : pas de prose, pas d'accents graves, pas de lien markdown, pas de puce, pas de > blockquote. Mettez une courte étiquette sur la ligne ci-dessus si nécessaire (« Collez ceci dans votre navigateur : »). Ajoutez un #id de section à l'URL lorsque vous faites référence à une section, après avoir vérifié que l'id existe. Les fichiers de code dans le chat conservent les liens relatifs habituels.

Pourquoi : un lien relatif ouvre la source HTML dans VS Code, et un lien file:/// ouvre la page rendue dans le navigateur. Une URL enfouie dans une phrase ou enveloppée dans du markdown doit être extraite à la main.

Skills associés