xingcanlee/wisp-writer

wisp-writer: Mit dem Wisp-Theme konsistente Artikel schreiben

Wisp steht für Ruhe, Präzision und Zurückhaltung. Artikel werden unter src/content/posts/<slug>/index.mdx (oder index.md) abgelegt, das Frontmatter folgt src/content.config.ts. Dieses Skill bietet:

SKILL.md
reference/   frontmatter.md  style-guide.md  elements.md  templates/
scripts/     new_post.py  check_post.py  tests/   (Python + uv, PEP 723 Inline-Abhängigkeiten, keine Installation nötig)

Befehls-Konventionen

Alle Befehle werden im Stammverzeichnis der Website ausgeführt, geschrieben als uv run skills/wisp-writer/scripts/<skript>.py .... Wenn du dieses Skill in eine andere Wisp-Website kopierst:

• Platziere es unter <website>/skills/wisp-writer/: Die Befehle bleiben unverändert.
• Platziere es unter <website>/.claude/skills/wisp-writer/ oder ~/.claude/skills/wisp-writer/: Ersetze den Pfad durch den tatsächlichen Speicherort; das Skript sucht von dem aktuellen Verzeichnis aus nach oben nach astro.config.* oder src/content, oder du kannst --root <stammverzeichnis> verwenden.
• Wenn die Website nicht gefunden wird, gibt das Skript einen Hinweis aus und beendet sich mit Exit-Code 2, ohne Dateien zu schreiben.
• Ohne uv: python3 <pfad>/new_post.py ... funktioniert ebenfalls (nur Standardbibliothek, benötigt Python 3.10+).

Arbeitsablauf

1. Lege Leser und Kernpunkte fest. Schreibe vor dem Schreiben drei Dinge auf: Wer sind die Leser (was können sie, was nicht), was sollen sie mitnehmen (ein Satz Fazit) und der Artikeltyp. Frage den Benutzer, wenn Informationen fehlen; erfinde keine Fakten, Daten oder Zitate.
2. Artikel erstellen. Wähle die Vorlage nach Typ: tutorial Anleitung, deep-dive Tiefgang, algorithm Algorithmuserklärung (mit interaktiven Komponenten), note kurze Notiz, paper-reading Paper-Interpretation.

   uv run skills/wisp-writer/scripts/new_post.py attention-explained \
     --title "Erklärung des Selbstaufmerksamkeitsmechanismus" --template deep-dive \
     --tags "LLM,Transformer" --category Maschinelles Lernen \
     --description "Vom Verständnis zur Formel: Erkläre den Berechnungsprozess der Selbstaufmerksamkeit."
   

   Der Slug wird in kebab-case geschrieben; wenn er bereits existiert, wird ein Fehler gemeldet. Das Skript listet vorhandene Tags und Kategorien auf, bevorzugt diese wiederzuverwenden. Parameter: --draft, --md/--mdx, --date, --list-templates.
3. Schreiben. Folge dem style-guide, die Element-Schreibweise findest du in elements, die Felder in frontmatter. Ersetze alle TODO in der Vorlage.
4. Bilder und Interaktion. Wenn Bilder benötigt werden, verwende das wisp-diagram-Skill, um Quelldateien und .wisp.svg zu erstellen und verweise mit der Diagramm-Referenzsyntax auf das Bild; für einfache Abläufe verwende direkt Mermaid. Wenn interaktive Demonstrationen benötigt werden, verwende vorhandene Explainer-Komponenten (derzeit MatMul); für andere Algorithmen müssen neue Komponenten hinzugefügt werden (siehe docs/guide/explainers.md), dies ist eine Codeänderung und sollte separat erklärt und genehmigt werden – nicht während des Schreibens eines Artikels ändern.
5. Prüfen und reparieren.

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

   Ausgabeformat Datei:Zeile Ebene Regel Erklärung. Fehler müssen behoben werden; Warnungen werden einzeln bewertet, wenn möglich reparieren; Infos sind nur Hinweise. --json für die maschinelle Verarbeitung, --all prüft alle Artikel.
6. Vorschau. pnpm build muss erfolgreich sein (prüft Frontmatter und Mermaid); für eine Vorschau verwende pnpm dev. Optional: Verwende Playwright, um jeweils einen Screenshot des Artikels im hellen und dunklen Modus zu machen und zu prüfen, ob Formeln, Diagramme und Codeblöcke überlaufen und im Dunkeln lesbar sind.

Harte Regeln

1. Der Text beginnt mit h2, nicht h1; die Ebenen überspringen keine Stufen; h2 verwendet Nominalphrasen.
2. title ≤ 80, description ≤ 200 Zeichen; description beschreibt klar, welches Problem der Artikel löst.
3. Tags und Kategorien verwenden vorhandene Schreibweisen wieder, Groß-/Kleinschreibung einheitlich (nicht gleichzeitig llm und LLM).
4. In chinesischen Absätzen werden chinesische Satzzeichen verwendet; zwischen Chinesisch und Englisch werden keine manuellen Leerzeichen eingefügt; chinesische Betonungen erfolgen mit Fettschrift, nicht kursiv.
5. Beim ersten Auftreten eines Fachbegriffs wird die englische Bezeichnung angegeben, z.B. „Selbstaufmerksamkeit (self-attention)“.
6. Jeder Codeblock hat eine Sprachkennzeichnung; das Einklappen langer Codeblöcke ist optional, standardmäßig nicht erforderlich.
7. Jedes Bild hat einen Alt-Text, der die aus dem Bild zu ziehende Schlussfolgerung beschreibt; Bildunterschriften verwenden "Abbildung N: Erklärung".
8. Keine hartcodierten Farben, keine style=-Attribute, keine Tailwind-Farbabstufungen; Farben dürfen nur aus Theme-Variablen stammen.
9. Artikel, die Komponenten verwenden, müssen .mdx sein und import verwenden; interaktive Komponenten erhalten client:visible.
10. Keine Fakten, Daten, Zitate oder Links erfinden; unsichere Inhalte deutlich kennzeichnen oder löschen.
11. Vorhandene Artikel nicht ändern, außer der Benutzer verlangt es; nur innerhalb von src/content/posts/<slug>/ arbeiten.

Beispiel-Auszug

Nachfolgend ein Beispiel für den passenden Ton (erklärt eine Sache klar, ohne Vorrede oder Übertreibung):

## Warum durch √d teilen

Angenommen, jede Komponente von $q$ und $k$ sei eine unabhängige Zufallsvariable mit Varianz 1, dann ist die Varianz des Skalarprodukts $q \cdot k$ gleich $d_k$. Je größer die Dimension, desto größer das Skalarprodukt, desto näher kommt Softmax an ein One-Hot-Encoding heran, und der Gradient wird sehr klein.

Nach Division durch $\sqrt{d_k}$ liegt die Varianz wieder um 1, der Output von Softmax bleibt in einem milden Bereich. Ohne diesen Schritt sind tiefe Netzwerke nur schwer trainierbar.

Vergleiche: „Wie jeder weiß, ist dieser super einfache, aber sehr wichtige kleine Trick extrem effektiv!“ – hohl, überbetont, ohne Information.

Häufige Fehler

• Mit „Dieser Artikel stellt vor...“ oder „Mit der Entwicklung von...“ beginnen; stattdessen direkt die Schlussfolgerung oder das Problem nennen.
• Im Text # Überschrift schreiben; oder nach h2 direkt h4 schreiben.
• Überschriften als Sätze formulieren („Lass uns sehen, wie das umgesetzt wird“), sollten Nominalphrasen sein („Umsetzung“).
• In chinesischem Text halbbreite Kommas oder Klammern mischen; chinesische Betonungen kursiv schreiben.
• In .md-Dateien Komponenten schreiben oder in .mdx import vergessen; interaktive Komponenten client:visible vergessen.
• Bilder ohne Alt-Text; auf noch nicht generierte .excalidraw-Dateien verweisen (zuerst zeichnen, dann referenzieren); auf .wisp.svg statt auf die Quelldatei verweisen.
• Für dasselbe Konzept neue Tags verwenden (gleichzeitig Llm, Großmodell und bereits vorhandenes LLM).
• Zu lange Texte in Mermaid-Knoten, die nach dem Rendern überlappen; auf etwa 12 chinesische Zeichen oder weniger kürzen.
• TODO-Platzhalter hinterlassen und ausliefern; check_post.py --strict findet sie.
• Nur Code schreiben ohne Erklärung: Vor dem Code den Zweck erklären, nach dem Code die Kernpunkte oder erwarteten Ergebnisse nennen.