handley-lab/handley-lab.github.io

Website スキル

このスキルは handley-lab.github.io 内で作業する際に使用します。これは CLAUDE.md のサイト規約と、クックブックのレシピやその他のコンテンツを追加するためのワークフローをエンコードしたものです。

使用するタイミング

• ユーザーがサイトにコンテンツを追加または編集したい場合。
• ユーザーがローカルで変更をプレビューしたい場合。
• ユーザーがレシピ（カードとオプションの長文解説ページ）を公開したい場合。
• recipe スキル（またはその他のコンテンツスキル）がプレビュー用のドラフトを引き渡した場合。

ブートストラップ

マシンごとに1回のみ実行:

script/bootstrap            # gem install bundler && bundle install

ローカルプレビュー

script/server               # bundle exec jekyll serve, http://127.0.0.1:4000

ライブリロードは *.md、_data/*.yml、_layouts/*.html、_includes/*.html、および _recipes/ 内のコレクションファイルへの編集を検出します。

ビルドチェック

コミットする前に:

script/build                # bundle exec jekyll build → _site/

skills/ に関連するものを触った場合は、リークチェックも実行してください。このリポジトリには、パブリックな skills.md ページ（/skills/ に公開）と、プライベートな skills/ ソースディレクトリ（ビルドから除外）が意図的に存在します。この組み合わせは微妙なため、以下のチェックでその区別を明確にします:

# パブリックなマーケットプレイスページが存在すること。
test -f _site/skills/index.html
# 生のスキルファイルが漏れてはならない。
test ! -e _site/skills/website
test ! -e _site/skills/recipe
test ! -e _site/skills/README.md
# _site/skills/ 内で index.html とビルド済みアセット以外はリーク。
find _site/skills -mindepth 1 ! -name index.html ! -name '*.css' ! -name '*.js' -print

最後の find は何も出力してはいけません。

script/cibuild              # ビルド、_site/index.html の存在を確認、その後 _site を削除

script/cibuild が終了コード0で終了し（「It builds!」と表示される）、サイトがビルドされます。

AIクックブックのコンテンツモデル

2つのサーフェス:

• _data/recipes.yml — /cookbook/ に表示されるレシピカードのリスト。すべてのレシピにはここにカードがあります。
• _recipes/<id>.md — /cookbook/<id>/ にレンダリングされるオプションの解説ページ。カードに「レシピ全文を読む」リンクを追加します。

カードのみのエントリも有効です。長さはレシピの特性であり、解説ページのない3〜4分で読めるレシピもあれば、リンクを張る価値のある長めの記事を持つものもあります。

レシピカードの追加または編集

レシピカードは _data/recipes.yml にのみ存在します。_recipes/ にファイルは必要ありません。

- id: <id>
  title: "..."                           # 簡潔で説明的に — それが何であるかを伝え、どれほど賢いかは伝えない
  category: "..."                        # 例: Context Engineering, Research Communication
  timebox: "..."                         # 例: 10 minutes, one afternoon, multi-session
  status: "Draft"                        # Stub | Draft | In progress | Complete
  proposer: "..."                        # オプション; ワークショップの帰属に便利
  summary: "..."                         # 1〜2文。何が効率的だったかではなく、何が可能になったかを先に述べる。
  outcome: "..."                         # 必須、空であってはならない（Stub: ...  は許容）
  evidence: "..."                        # 必須、空であってはならない（Stub: ...  は許容）
  demo_url:
  repo_url: "..."

2026年5月5日のワークショップおよび後続のワークショップでは、_data/recipes.yml に対する多数の競合するPRを開くのではなく、レシピカードのYAMLを調整イシューに投稿してオーケストレーターによる一括マージを依頼することを推奨します。このファイルはパラレル編集下でマージコンフリクトの温床となります。

レシピの長文解説ページの追加

長文レシピには、同期を保つ必要がある 2つのパート があります:

1. カード — _data/recipes.yml のエントリ。/cookbook/ とホームページのプレビューブロックにレンダリングされます。
2. 解説ページ — _recipes/<id>.md のファイル。/cookbook/<id>/ にレンダリングされます。

カードインクルード（_includes/recipe_card.html）は、コレクションの slug によって一致する解説ページを発見します。Jekyllはファイル名から自動的に slug を導出します。したがって、<id>（カードのフィールド、解説ページのフロントマター id、ファイル名）はすべて一致している必要があります。 そうでないと「レシピ全文を読む」リンクは表示されません。

ステップ 1 — <id> を選択し、未使用であることを確認する

• ケバブケース（例: jaxwavelets、gw-emulator、cosmosis-cobaya-port）。
• 一致する必要がある3つの場所（ファイル名、カード id、解説ページのフロントマター id）全体で一意であること。

スクリプトによる確認（選択した <id> で実行）:

id="<id>"
fail=0

# 1. カード id が _data/recipes.yml に存在してはならない
if grep -nE "^- id: ${id}$" _data/recipes.yml; then
  echo "ERROR: _data/recipes.yml already has id: ${id}"; fail=1
fi

# 2. 解説ページのファイル名が存在してはならない
if test -e "_recipes/${id}.md"; then
  echo "ERROR: _recipes/${id}.md already exists"; fail=1
fi

# 3. 解説ページのフロントマター id が別のファイル名で存在してはならない
if grep -RsnE "^id: ${id}$" _recipes; then
  echo "ERROR: another _recipes/*.md already has id: ${id}"; fail=1
fi

[ "$fail" = 0 ] && echo "OK: ${id} is free"

いずれかのチェックが失敗した場合は、別のIDを選択してください。上書きしないでください。

ステップ 2 — フィーチャーブランチを作成する

git checkout -b recipe/<id>

先にブランチを作成し、それから書き込みます。未コミットの変更は引き継がれますが、最初からブランチに編集を閉じ込める方がクリーンです。main に直接プッシュしないでください。

ステップ 3 — _recipes/<id>.md を書く

フロントマターには完全なカードスキーマを含める必要があります（ページが自己文書化され、レイアウトが必要なデータを持てるようにするため）:

---
id: <id>
title: "..."
category: "..."
timebox: "..."
status: "Draft"            # Stub | Draft | In progress | Complete
summary: "..."
outcome: "..."
evidence: "..."
demo_url:                  # オプション; フィールドを値なしにするか、完全に省略する
repo_url: "..."            # オプション
author: "..."
date: YYYY-MM-DD
---

status は "Stub"、"Draft"、"In progress"、または "Complete" を受け入れます。outcome と evidence は空であってはなりません（スタブの場合は、空白のままにするのではなく Stub: ... で始めてください）。

次に長文の本文です。先頭の本文H1は書かないでください。 _layouts/recipe.html が {{ page.title }} をH1としてレンダリングします。本文は ## Section で開始してください。

参考テンプレートとして _recipes/jaxwavelets.md を使用してください（ただし、その実装は2026年5月5日のワークショップで長すぎて密度が高すぎると批評された点に注意してください — 詳細なフォレンジックについてはMethodsノートを付け、3〜4分で読めるものを推奨します）。

ステップ 4 — _data/recipes.yml に一致するカードを追加する

- id: <id>                              # MUST match _recipes/<id>.md
  title: "..."
  category: "..."
  timebox: "..."
  status: "..."
  summary: "..."
  outcome: "..."                        # required, must be non-empty
  evidence: "..."                       # required, must be non-empty
  demo_url:
  repo_url: "..."

空の outcome や evidence を出荷しないでください。それらが書けないのであれば、レシピは公開準備ができていません。

ステップ 5 — プレビュー

script/server（または実行中のサーバーをリフレッシュ）。以下のURLにアクセス:

• /cookbook/<id>/ — 解説ページがフロントマターのタイトルをH1としてレンダリングされ、必要に応じてMathJaxが読み込まれます。
• /cookbook/ — 新しいカードが「レシピ全文を読む」リンクとともに表示されます。
• / — <id> が最初の3つのカードにある場合、ホームページのプレビューブロックに変更が反映されます。

ステップ 6 — ビルドチェック + コミット

script/cibuild                          # すべて問題なければ 0 で終了
git add _recipes/<id>.md _data/recipes.yml
git commit -m "Add <id> recipe"
git push -u origin recipe/<id>
gh pr create                            # または、gh が認証されていない場合はGitHub Web UIでPRを開く

明示的なユーザーのOKなしにこのスキルが変更してはならないファイル

• _posts/ — 現在監査中。新しい投稿はPRレビューを通過します（下記のPapers参照）。
• assets/group/group.yaml — script/calculate で管理。
• _config.yml — サイト全体の設定。明示的なユーザーのOKが必要。
• script/* — ビルドスクリプト。明示的なユーザーのOKが必要。

Papers（_posts/）

_posts/ ディレクトリは、これまで script/posts/arxiv.py からの自動生成arXivサマリーを保持していました。2026年5月5日時点でこれらは監査中です。_posts/ 内のものはすべて人間によるレビューを経たと想定すべきではなく、/papers/ ページはPRレビュー済みのエントリのみを表示するように再構築されています。疑わしい場合は、_posts/ に直接追加せず、PRを開いて人間によるレビューをリクエストしてください。

一般的な障害モード

• 「レシピ全文を読む」リンクがない: ファイル名のスラッグがカードの id と一致していません。_recipes/<id>.md が存在し、カードに id: <id> があることを確認してください。
• ページに重複するH1がある: 本文が # ... で始まっています。それを削除してください。レイアウトが {{ page.title }} からH1を追加します。
• 空の「Outcome:」/「Evidence:」ラベル: カードフィールドが "" です。値を入力してください。それらがないとレシピは公開準備ができていません。
• _config.yml の編集後にビルドが失敗する: コレクションまたはデフォルトスコープの構文エラー。現在のコレクションは recipes（小文字）で、permalink: /cookbook/:path/ が設定されています。