xingcanlee/wisp-writer

wisp-writer : écrire des articles cohérents avec le thème Wisp

L'orientation de Wisp est calme, précise, retenue. Les articles sont écrits dans src/content/posts/<slug>/index.mdx (ou index.md), et le frontmatter est défini par src/content.config.ts. Ce skill fournit :

SKILL.md
reference/   frontmatter.md  style-guide.md  elements.md  templates/
scripts/     new_post.py  check_post.py  tests/   (Python + uv, dépendances en ligne PEP 723, aucune installation nécessaire)

Conventions de commandes

Toutes les commandes s'exécutent à la racine du site, sous la forme uv run skills/wisp-writer/scripts/<script>.py .... Lorsque vous copiez ce skill vers un autre site Wisp :

• Placé dans <site>/skills/wisp-writer/ : les commandes restent inchangées.
• Placé dans <site>/.claude/skills/wisp-writer/ ou ~/.claude/skills/wisp-writer/ : remplacez le chemin par l'emplacement réel ; le script cherchera astro.config.* ou src/content en remontant depuis le répertoire courant, ou vous pouvez spécifier --root <racine_du_site>.
• Si le site n'est pas trouvé, le script le signale et se termine avec le code de sortie 2, sans écrire aucun fichier.
• Sans uv : python3 <chemin>/new_post.py ... fonctionne également (utilise uniquement la bibliothèque standard, nécessite Python 3.10+).

Workflow

1. Identifier le public et les points clés. Avant d'écrire, notez trois choses : qui est le public (ce qu'il sait et ne sait pas), ce qu'il retiendra (une conclusion en une phrase), et le type d'article. En cas de manque d'informations, interrogez d'abord l'utilisateur ; ne fabriquez pas de faits, de données ou de citations.
2. Créer l'article. Choisissez le modèle en fonction du type : tutorial (tutoriel), deep-dive (analyse approfondie), algorithm (explication d'algorithme avec composants interactifs), note (note courte), paper-reading (lecture d'article).

   uv run skills/wisp-writer/scripts/new_post.py attention-explained \
     --title "Explication de l'attention personnelle" --template deep-dive \
     --tags "LLM,Transformer" --category Apprentissage_automatique \
     --description "De l'intuition à la formule, expliquez clairement le processus de calcul de l'attention personnelle."
   

   Le slug utilise le kebab-case ; s'il existe déjà, une erreur est signalée. Le script liste les balises et catégories existantes, réutilisez-les de préférence. Paramètres : --draft, --md/--mdx, --date, --list-templates.
3. Écrire. Suivez le guide de style, la syntaxe des éléments dans elements, et les champs dans frontmatter. Remplacez tous les TODO dans le modèle.
4. Illustrations et interactivité. Pour les schémas, utilisez le skill wisp-diagram pour produire les fichiers source et les .wisp.svg, puis insérez-les dans l'article avec la syntaxe de référence aux diagrammes ; pour les flux simples, utilisez directement Mermaid. Pour les démonstrations interactives, utilisez le composant explainer existant (actuellement MatMul) ; pour d'autres algorithmes, ajoutez un nouveau composant, voir docs/guide/explainers.md, cela relève d'une modification de code, qui doit être expliquée séparément et approuvée ; ne modifiez pas en écrivant un article.
5. Vérifier et corriger.

   uv run skills/wisp-writer/scripts/check_post.py attention-explained --strict
   

   Format de sortie : fichier:ligne niveau règle explication. Les error doivent être corrigées ; les warning sont évaluées une par une : corrigez si possible ; les info sont simplement informatives. --json pour la lecture par programme, --all pour vérifier tous les articles.
6. Prévisualiser. pnpm build doit réussir (valide le frontmatter et Mermaid) ; pour voir le rendu, utilisez pnpm dev. Optionnel : avec Playwright, prenez une capture d'écran de la page de l'article en thème clair et foncé, vérifiez que les formules, diagrammes et blocs de code ne débordent pas et sont lisibles en mode sombre.

Règles strictes

1. Le texte commence par h2, pas de h1 ; ne sautez pas de niveaux ; les h2 sont des groupes nominaux.
2. title ≤ 80, description ≤ 200 caractères ; la description indique clairement ce que l'article résout.
3. Les balises et catégories réutilisent l'écriture existante, avec la même casse (pas à la fois llm et LLM).
4. Les paragraphes en chinois utilisent les signes de ponctuation pleine chasse ; pas d'espace manuel entre le chinois et l'anglais ; pour insister en chinois, utilisez gras, pas d'italique.
5. La première occurrence d'un terme est accompagnée de sa traduction anglaise, par exemple "auto-attention (self-attention)".
6. Chaque bloc de code a un identifiant de langage ; le repliement des longs blocs de code est optionnel, laissez par défaut.
7. Chaque image a un alt décrivant la conclusion de l'image ; les légendes utilisent "Figure N : explication".
8. Ne codez pas en dur les couleurs, n'écrivez pas style=, n'utilisez pas d'échelles de gris Tailwind ; les couleurs proviennent uniquement des variables du thème.
9. Les articles utilisant des composants doivent être en .mdx et inclure import ; les composants interactifs ajoutent client:visible.
10. Ne fabriquez pas de faits, de données, de citations ou de liens ; en cas de doute, signalez-le clairement ou supprimez.
11. Ne modifiez pas les articles existants sauf demande de l'utilisateur ; travaillez uniquement dans src/content/posts/<slug>/.

Exemple de fragment

Voici un fragment correspondant au ton (expliquer une chose, sans préambule, sans exagérer) :

## Pourquoi diviser par √d

Supposons que chaque composante de $q$ et $k$ soit une variable aléatoire indépendante de variance 1. Alors la variance du produit scalaire $q \cdot k$ est $d_k$. Plus la dimension est grande, plus le produit scalaire est grand, et plus softmax se rapproche de one-hot, rendant le gradient très petit.

En divisant par $\sqrt{d_k}$, la variance revient autour de 1, et la sortie de softmax reste dans une plage modérée. Sans cette étape, il est difficile d'entraîner des réseaux profonds.

À comparer avec : "Comme tout le monde le sait, cette astuce super simple mais très importante peut grandement améliorer les performances !" — vide, exagéré, sans information.

Erreurs courantes

• Commencer par "Cet article présentera..." ou "Avec le développement de...", donnez directement la conclusion ou le problème.
• Écrire # Titre dans le texte ; ou passer directement à h4 après h2.
• Titres sous forme de phrase ("Voyons comment implémenter cela"), ils doivent être des groupes nominaux ("Implémentation").
• Mélanger des virgules et parenthèses demi-chasse dans le chinois ; utiliser l'italique pour insister en chinois.
• Écrire des composants dans un fichier .md, ou oublier import dans un fichier .mdx ; oublier client:visible pour les composants interactifs.
• Images sans alt ; référencer un fichier .excalidraw non encore généré (d'abord dessiner, puis référencer) ; référencer .wisp.svg au lieu du fichier source.
• Utiliser une nouvelle balise pour un même concept (Llm, Grand modèle coexistant avec LLM existant).
• Texte de nœud Mermaid trop long, entraînant un chevauchement après rendu ; raccourcissez à environ 12 caractères chinois maximum.
• Laisser des TODO en place ; check_post.py --strict les détecte.
• Écrire du code sans l'expliquer : avant le code, expliquez l'objectif ; après le code, expliquez les points clés ou le résultat attendu.