handley-lab/handley-lab.github.io

網站技能

在 handley-lab.github.io 目錄內工作時使用此技能。它將 CLAUDE.md 中的網站慣例以及新增食譜和其他內容的工作流程編碼於此。

使用時機

• 使用者想要在網站上新增或編輯內容。
• 使用者想要在本地預覽其變更。
• 使用者想要發布食譜（卡片與選用的詳細詳細頁面）。
• 某個 recipe 技能（或其他內容技能）將草稿移交以供預覽。

引導環境

每台機器執行一次：

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 Cookbook 內容模型

兩個層面：

• _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 日的工作坊及任何後續工作坊期間，建議將食譜卡片的 YAML 發佈到協調 issue 中，供協調員批量合併，而不是針對 _data/recipes.yml 開啟多個競爭的 PR——在平行編輯下，該檔案是合併衝突的磁鐵。

為食譜新增詳細詳細頁面

一個詳細食譜有兩個部分必須保持同步：

1. 卡片 — _data/recipes.yml 中的條目。在 /cookbook/ 和首頁預覽區塊中呈現。
2. 詳細頁面 — _recipes/<id>.md 中的檔案。在 /cookbook/<id>/ 中呈現。

卡片包含（_includes/recipe_card.html）透過集合 slug 發現相符的詳細頁面——Jekyll 從檔名自動衍生 slug。**因此 <id>（卡片欄位、詳細頁面的 frontmatter id 以及檔名）必須全部一致。**否則「閱讀完整食譜」連結將不會出現。

步驟 1 — 選擇 <id> 並檢查是否未使用

• 以連字號分隔的小寫單字（kebab-case）（例如 jaxwavelets、gw-emulator、cosmosis-cobaya-port）。
• 在所有三個必須一致的位置（檔名、卡片 id、詳細頁面 frontmatter 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. 詳細頁面 frontmatter 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

Frontmatter 必須包含完整的卡片結構（這樣頁面才能自我說明，且佈局擁有所需的資料）：

---
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，請以 Stub: ... 為開頭，而不是留空）。

然後是詳細頁面的主體。不要撰寫以 H1 開頭的主體——_layouts/recipe.html 會將 {{ page.title }} 呈現為 H1。請以 ## Section 開頭。

使用 _recipes/jaxwavelets.md 作為參考模板（但需注意，在 2026 年 5 月 5 日的工作坊中，其執行被批評為太長且太密集——請偏好 3–4 分鐘的閱讀，並附上 Methods 註記以提供鑑識細節）。

步驟 4 — 將相符的卡片附加到 _data/recipes.yml

- id: <id>                              # 必須與 _recipes/<id>.md 相符
  title: "..."
  category: "..."
  timebox: "..."
  status: "..."
  summary: "..."
  outcome: "..."                        # 必填，不可為空
  evidence: "..."                       # 必填，不可為空
  demo_url:
  repo_url: "..."

不要交付空的 outcome 或 evidence。如果你無法撰寫它們，表示食譜尚未準備好發布。

步驟 5 — 預覽

script/server（或重新整理正在執行的伺服器）。前往：

• /cookbook/<id>/ — 詳細頁面呈現，frontmatter 標題作為 H1，如果需要則載入 MathJax。
• /cookbook/ — 新卡片出現，並帶有可運作的「閱讀完整食譜」連結。
• / — 如果 <id> 位於前三張卡片中，首頁預覽區塊會反映變更。

步驟 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 網頁 UI 中開啟 PR

未經使用者明確許可，此技能不得修改的檔案

• _posts/ — 目前正在稽核；新文章需經過 PR 審查（請參閱下方的 Papers）。
• assets/group/group.yaml — 透過 script/calculate 管理。
• _config.yml — 全站設定；需要使用者明確許可。
• script/* — 建置腳本；需要使用者明確許可。

論文（_posts/）

_posts/ 目錄歷史上存放著來自 script/posts/arxiv.py 的自動產生的 arXiv 摘要。截至 2026 年 5 月 5 日，這些摘要正在接受稽核：不應假設 _posts/ 中的任何內容都經過人工審查，且 /papers/ 頁面正在重建，僅顯示經過 PR 審查的條目。如有疑問，請不要直接新增到 _posts/——請開啟 PR 並請求人工審查。

常見失敗模式

• 「閱讀完整食譜」連結遺失：檔案名稱 slug 與卡片的 id 不符。請確認 _recipes/<id>.md 存在且卡片具有 id: <id>。
• 頁面上重複的 H1：主體以 # ... 開頭。請移除它；佈局會從 {{ page.title }} 新增 H1。
• 空的「Outcome:」/「Evidence:」標籤：卡片欄位為 ""。請填入它們；沒有這些，食譜就還沒準備好發布。
• 編輯 _config.yml 後建置失敗：集合或預設範圍語法錯誤。目前的集合是 recipes（小寫）且具有 permalink: /cookbook/:path/。