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일 워크숍 및 이후 워크숍에서는 _data/recipes.yml에 대한 여러 경쟁 PR을 여는 대신 레시피 카드 YAML을 오케스트레이터 일괄 병합을 위한 조정 이슈에 게시하는 것을 선호합니다. 해당 파일은 병렬 편집 시 병합 충돌의 온상입니다.

레시피에 긴 형식 동반 페이지 추가하기

긴 형식 레시피는 동기화 상태를 유지해야 하는 두 개의 절반으로 구성됩니다:

1. 카드 — _data/recipes.yml의 항목. /cookbook/ 및 홈페이지 미리보기 블록에 렌더링됩니다.
2. 동반 페이지 — _recipes/<id>.md 파일. /cookbook/<id>/에 렌더링됩니다.

카드 포함(_includes/recipe_card.html)은 컬렉션 slug로 일치하는 동반 페이지를 찾습니다. Jekyll은 파일 이름에서 slug를 자동으로 파생합니다. 따라서 <id>(카드 필드, 동반 페이지의 frontmatter id, 파일 이름)가 모두 일치해야 합니다. 그렇지 않으면 "전체 레시피 읽기" 링크가 나타나지 않습니다.

1단계 — <id> 선택 및 사용되지 않음 확인

• 케밥-케이스(예: 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: ...로 시작하세요).

그런 다음 긴 형식 본문을 작성합니다. 선행 본문 H1을 작성하지 마세요. _layouts/recipe.html은 {{ page.title }}을 H1으로 렌더링합니다. 본문을 ## Section으로 시작하세요.

참조 템플릿으로 _recipes/jaxwavelets.md를 사용하세요(단, 2026년 5월 5일 워크숍에서 해당 실행이 너무 길고 밀도가 높았다는 비판을 받았다는 점을 유의하세요. 법의학적 세부 사항을 위한 Methods 노트와 함께 3~4분 분량의 읽기를 선호하세요).

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>/ — 필요 시 MathJax가 로드된 상태로 frontmatter 제목이 H1로 동반 페이지가 렌더링됩니다.
• /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/* — 빌드 스크립트이며, 사용자의 명시적 승인이 필요합니다.

Papers (_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/입니다.