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/に置く：コマンドはそのままでOK。<サイト>/.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>/内だけで作業する。
サンプル（適切なトーン）
以下は適切なトーンの例です（一つのことを説明し、前置きや誇張はありません）：
## なぜ √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で発見できる。- コードだけ書いて説明がない。コードの前に目的を、コードの後に重要なポイントや期待される出力を説明する。