wisp-writer: Wisp 主题で一貫性のある記事を書く
Wisp の指向は「静か、正確、抑制的」です。記事は src/content/posts/<slug>/index.mdx（または index.md）に書き、frontmatter は src/content.config.ts に従います。本スキルは以下を提供します：
SKILL.md
reference/ frontmatter.md style-guide.md elements.md templates/
scripts/ new_post.py check_post.py tests/ （Python + uv、PEP 723 インラインディペンデンシー、インストール不要）
コマンド規約
すべてのコマンドはサイトのルートディレクトリで実行し、uv run skills/wisp-writer/scripts/<スクリプト>.py ... と記述します。本スキルを他の Wisp サイトにコピーする場合：
<サイト>/skills/wisp-writer/に配置：コマンドはそのまま。<サイト>/.claude/skills/wisp-writer/または~/.claude/skills/wisp-writer/に配置：パスを実際の場所に変更。スクリプトはカレントディレクトリから上位に向けてastro.config.*またはsrc/contentを探します。--root <サイトのルート>で指定することも可能。- サイトが見つからない場合、スクリプトはエラーを表示し、終了コード 2 で終了します。ファイルは書き込みません。
- uv がない場合：
python3 <パス>/new_post.py ...でも実行可能です（標準ライブラリのみ使用、Python 3.10+ が必要）。
ワークフロー
- 読者と要点を明確にする。 書き始める前に以下の 3 つを書き留めます：読者は誰か（何ができて、何ができないか）、読後に持ち帰ってほしいこと（一文の結論）、記事のタイプ。情報が不足している場合はまずユーザーに質問し、事実、データ、引用を捏造してはいけません。
- 記事を作成する。 タイプに応じてテンプレートを選択：
tutorialチュートリアル、deep-dive原理深掘り、algorithmアルゴリズム解説（インタラクティブコンポーネント付き）、note短いメモ、paper-reading論文解説。uv run skills/wisp-writer/scripts/new_post.py attention-explained \ --title "自己注意機構の解説" --template deep-dive \ --tags "LLM,Transformer" --category 機械学習 \ --description "直感から数式まで、自己注意の計算過程を明確に説明します。"--draft、--md/--mdx、--date、--list-templates。 - 執筆。 style-guide に従い、要素の書き方は elements、フィールドは frontmatter を参照。テンプレート内の
TODOをすべて置き換えます。 - 図とインタラクション。 図が必要な場合は、wisp-diagram スキルを使用してソースファイルと
.wisp.svgを生成し、図表参照構文で記事に挿入。簡単なフローは Mermaid を直接使用。インタラクティブなデモが必要な場合は、既存の explainer コンポーネント（現在はMatMul）を使用。他のアルゴリズムには新しいコンポーネントが必要で、その方法はdocs/guide/explainers.mdにあります。これはコード変更に該当するため、個別に説明し同意を得た上で行い、記事作成中に一緒に変更してはいけません。 - チェックと修正。
出力形式：uv run skills/wisp-writer/scripts/check_post.py attention-explained --strictファイル:行番号 レベル ルール 説明。error は必ず修正。warning は一つずつ判断し、修正可能なら修正。info は単なるヒント。--jsonでプログラム読み取り可能、--allですべての記事をチェック。 - プレビュー。
pnpm buildが必ず通ること（frontmatter と Mermaid を検証）。見た目を確認するにはpnpm dev。オプション：Playwright を使って記事ページをライトテーマとダークテーマでそれぞれ 1 枚ずつスクリーンショットを撮り、数式、図表、コードブロックがはみ出していないか、ダークモードでも見やすいか確認。
ハードルール
- 本文は h2 から始め、h1 は書かない。見出しレベルを飛ばさない。h2 は名詞句にする。
titleは 80 文字以内、descriptionは 200 文字以内。descriptionにはその記事が何を解決するかを明確に書く。- タグとカテゴリは既存の表記を再利用し、大文字小文字を統一する（
llmとLLMが混在しないように）。 - 日本語段落では全角句読点を使用。日本語と英単語の間には手動でスペースを入れない。強調は
**太字**を使用し、斜体は使わない。 - 専門用語が初出のときは英語表記を併記する（例：「自己注意（self-attention）」）。
- すべてのコードブロックに言語識別子を付ける。長いコードブロックの折りたたみはオプション。デフォルトでは気にしない。
- すべての画像に alt 属性を付け、図が伝えたい結論を説明する。図のキャプションは
"図 N：説明"の形式。 - 色をハードコードしない、
style=を書かない、Tailwind の色階調を使わない。色はテーマ変数のみから使用。 - コンポーネントを使用する記事は必ず
.mdxファイルとし、importを記述。インタラクティブコンポーネントにはclient:visibleを付ける。 - 事実、データ、引用、リンクを捏造しない。確信がない内容は明示的にその旨を記載するか削除する。
- 既存の記事は、ユーザーが要求した場合を除き変更しない。作業は
src/content/posts/<slug>/内のみ。
サンプル（文体に合った例）
以下は、Wisp のトーンに合った例です（一つのことを明確に説明し、前置きや誇張なし）：
## なぜ √d で割るのか
$q$ と $k$ の各成分が分散 1 の独立な確率変数だとすると、ドット積 $q \cdot k$ の分散は $d_k$ になります。次元が大きくなるほどドット積は大きくなり、softmax は one-hot に近づいて勾配が非常に小さくなります。
$\sqrt{d_k}$ で割ることで、分散が約 1 に戻り、softmax の出力は穏やかな範囲に保たれます。このステップがないと、深いネットワークは訓練が困難になります。
比較：「ご存知の通り、この超シンプルでありながら非常に重要な小ワザは効果を劇的に向上させます！」——空虚で、過度な強調、情報がありません。
よくある間違い
- 冒頭を「本稿では〜を紹介します」「〜の発展に伴い」で始める。結論や問題を直接書くべき。
- 本文中に
# タイトルと書く。または h2 の直後に h4 を書く。 - 見出しを文で書く（「実装方法を見てみよう」）— 名詞句（「実装方法」）にするべき。
- 日本語の中で半角カンマや括弧を混在させる。日本語の強調に斜体を使う。
.mdファイルにコンポーネントを書く、または.mdxでimportを忘れる。インタラクティブコンポーネントでclient:visibleを忘れる。- 画像に alt がない。まだ生成されていない
.excalidrawを参照する（先に図を描き、その後参照）。ソースファイルではなく.wisp.svgを参照する。 - 同じ概念に新しいタグを使う（既存の
LLMがあるのにLlmや大規模言語モデルを追加する）。 - Mermaid のノードテキストが長すぎてレンダリング後に重なる。約 12 文字以内に短縮する。
TODOプレースホルダーを残したまま納品する。check_post.py --strictで発見可能。- コードだけ書いて説明がない：コードの前に目的を説明し、コードの後に重要なポイントや期待される出力を説明する。