handley-lab/handley-lab.github.io

Website Skill

Verwende diesen Skill bei der Arbeit im Repository handley-lab.github.io. Er kodiert die Site-Konventionen aus CLAUDE.md und den Workflow zum Hinzufügen von Kochbuch-Rezepten und anderen Inhalten.

Wann verwenden

• Der Benutzer möchte Inhalte auf der Website hinzufügen oder bearbeiten.
• Der Benutzer möchte seine Änderungen lokal in der Vorschau anzeigen.
• Der Benutzer möchte ein Rezept veröffentlichen (Karte und optional eine ausführliche Begleitseite).
• Ein recipe Skill (oder ein anderer Content Skill) übergibt einen Entwurf zur Vorschau.

Bootstrap

Einmal pro Maschine:

script/bootstrap            # gem install bundler && bundle install

Lokale Vorschau

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

Live-Reload erkennt Änderungen an *.md, _data/*.yml, _layouts/*.html, _includes/*.html und Sammlungsdateien in _recipes/.

Build-Prüfung

Vor dem Commit:

script/build                # bundle exec jekyll build → _site/

Wenn du etwas bearbeitet hast, das skills/ betreffen könnte, führe auch die Leck-Prüfungen aus. Das Repository enthält absichtlich sowohl eine öffentliche skills.md-Seite (die unter /skills/ veröffentlicht wird) als auch ein privates skills/ Quellverzeichnis (vom Build ausgeschlossen). Die Kombination ist subtil – diese Prüfungen machen den Unterschied explizit:

# Die öffentliche Marktplatz-Seite muss existieren.
test -f _site/skills/index.html
# Rohe Skill-Dateien dürfen NICHT durchsickern.
test ! -e _site/skills/website
test ! -e _site/skills/recipe
test ! -e _site/skills/README.md
# Alles andere unter _site/skills/ außer index.html und gebauten Assets ist ein Leck.
find _site/skills -mindepth 1 ! -name index.html ! -name '*.css' ! -name '*.js' -print

Das letzte find sollte nichts ausgeben.

script/cibuild              # baut, prüft, ob _site/index.html existiert, löscht dann _site

Wenn script/cibuild mit 0 beendet wird (Ausgabe "It builds!") baut die Site.

Das KI-Kochbuch Content-Modell

Zwei Oberflächen:

• _data/recipes.yml — die Liste der Rezeptkarten, die unter /cookbook/ angezeigt werden. Jedes Rezept hat hier eine Karte.
• _recipes/<id>.md — optionale Begleitseite, die unter /cookbook/<id>/ gerendert wird. Fügt einen "Read full recipe"-Link zur Karte hinzu.

Reine Karteneinträge sind gültig. Die Länge ist eine Eigenschaft des Rezepts; manche Rezepte sind 3–4-minütige Lesevorträge ohne Begleitseite, andere haben eine längere Ausarbeitung, die es wert ist, verlinkt zu werden.

Hinzufügen oder Bearbeiten einer Rezeptkarte

Rezeptkarten leben ausschließlich in _data/recipes.yml. Sie benötigen keine Datei in _recipes/.

- id: <id>
  title: "..."                           # klar beschreibend – sage, was es ist, nicht wie clever es ist
  category: "..."                        # z. B. Context Engineering, Research Communication
  timebox: "..."                         # z. B. 10 Minuten, ein Nachmittag, mehrere Sitzungen
  status: "Draft"                        # Stub | Draft | In progress | Complete
  proposer: "..."                        # optional; nützlich für Workshop-Zuschreibungen
  summary: "..."                         # 1–2 Sätze. Beginne mit dem, was möglich wurde, nicht mit dem, was effizient war.
  outcome: "..."                         # erforderlich, darf nicht leer sein (Stub: ... ist akzeptabel)
  evidence: "..."                        # erforderlich, darf nicht leer sein (Stub: ... ist akzeptabel)
  demo_url:
  repo_url: "..."

Während des Workshops am 5. Mai 2026 und aller Folgeworshops ist es vorzuziehen, Rezeptkarten-YAML im Koordinations-Issue für den Orchestrator-Batch-Merge zu posten, anstatt viele konkurrierende PRs gegen _data/recipes.yml zu eröffnen – die Datei ist bei parallelen Bearbeitungen ein Magnet für Merge-Konflikte.

Hinzufügen einer ausführlichen Begleitseite für ein Rezept

Ein ausführliches Rezept hat zwei Hälften, die synchron bleiben müssen:

1. Karte — ein Eintrag in _data/recipes.yml. Wird auf /cookbook/ und im Startseiten-Vorschaublock gerendert.
2. Begleitseite — eine Datei unter _recipes/<id>.md. Wird unter /cookbook/<id>/ gerendert.

Das Karten-Include (_includes/recipe_card.html) findet eine passende Begleitseite über den Collection-slug – Jekyll leitet slug automatisch aus dem Dateinamen ab. Also müssen <id> (das Kartenfeld, die id im Frontmatter der Begleitseite und der Dateiname) alle übereinstimmen. Sonst erscheint der "Read full recipe"-Link nicht.

Schritt 1 – Wähle <id> und prüfe, ob es nicht vergeben ist

• Kebab-Case (z. B. jaxwavelets, gw-emulator, cosmosis-cobaya-port).
• Einzigartig an allen drei Stellen, an denen es übereinstimmen muss (Dateiname, Karten-id, Begleitseiten-Frontmatter-id).

Skript-Prüfung (führe sie mit deiner gewählten <id> aus):

id="<id>"
fail=0

# 1. Karten-id darf nicht in _data/recipes.yml existieren
if grep -nE "^- id: ${id}$" _data/recipes.yml; then
  echo "FEHLER: _data/recipes.yml hat bereits id: ${id}"; fail=1
fi

# 2. Begleitseiten-Dateiname darf nicht existieren
if test -e "_recipes/${id}.md"; then
  echo "FEHLER: _recipes/${id}.md existiert bereits"; fail=1
fi

# 3. Begleitseiten-Frontmatter-id darf nicht unter einem anderen Dateinamen existieren
if grep -RsnE "^id: ${id}$" _recipes; then
  echo "FEHLER: Eine andere _recipes/*.md hat bereits id: ${id}"; fail=1
fi

[ "$fail" = 0 ] && echo "OK: ${id} ist frei"

Wenn eine Prüfung fehlschlägt, wähle eine andere ID. Überschreibe nicht.

Schritt 2 – Erstelle den Feature-Branch

git checkout -b recipe/<id>

Zuerst Branch, dann schreiben – nicht committete Änderungen werden übernommen, aber es ist sauberer, deine Bearbeitungen von Anfang an auf den Branch zu beschränken. Niemals direkt nach main pushen.

Schritt 3 – Schreibe _recipes/<id>.md

Das Frontmatter muss das vollständige Kartenschema enthalten (damit die Seite selbstdokumentierend ist und das Layout die benötigten Daten hat):

---
id: <id>
title: "..."
category: "..."
timebox: "..."
status: "Draft"            # Stub | Draft | In progress | Complete
summary: "..."
outcome: "..."
evidence: "..."
demo_url:                  # optional; lasse das Feld ohne Wert oder lasse es ganz weg
repo_url: "..."            # optional
author: "..."
date: YYYY-MM-DD
---

status akzeptiert "Stub", "Draft", "In progress" oder "Complete". outcome und evidence müssen nicht leer sein (für Stubs beginne mit Stub: ... anstatt es leer zu lassen).

Dann der ausführliche Textkörper. Schreibe keine führende H1 im Textkörper – _layouts/recipe.html rendert {{ page.title }} als H1. Beginne den Textkörper mit ## Abschnitt.

Verwende _recipes/jaxwavelets.md als Referenzvorlage (mit dem Hinweis, dass seine Ausführung im Workshop vom 5. Mai 2026 als zu lang und zu dicht kritisiert wurde – bevorzuge 3–4-minütige Lesevorträge mit einer Methodennotiz für forensische Details).

Schritt 4 – Füge eine passende Karte an _data/recipes.yml an

- id: <id>                              # MUSS mit _recipes/<id>.md übereinstimmen
  title: "..."
  category: "..."
  timebox: "..."
  status: "..."
  summary: "..."
  outcome: "..."                        # erforderlich, darf nicht leer sein
  evidence: "..."                       # erforderlich, darf nicht leer sein
  demo_url:
  repo_url: "..."

Versende keine leeren outcome oder evidence. Wenn du sie nicht schreiben kannst, ist das Rezept nicht bereit zur Veröffentlichung.

Schritt 5 – Vorschau

script/server (oder aktualisiere den laufenden Server). Besuche:

• /cookbook/<id>/ — die Begleitseite wird mit dem Frontmatter-Titel als H1 gerendert, MathJax geladen falls nötig.
• /cookbook/ — die neue Karte erscheint mit einem funktionierenden "Read full recipe"-Link.
• / — der Startseiten-Vorschaublock spiegelt die Änderung wider, wenn <id> unter den ersten drei Karten ist.

Schritt 6 – Build-Prüfung + Commit

script/cibuild                          # beendet mit 0, wenn alles gut ist
git add _recipes/<id>.md _data/recipes.yml
git commit -m "Rezept <id> hinzufügen"
git push -u origin recipe/<id>
gh pr create                            # oder öffne den PR in der GitHub-Web-Oberfläche, wenn gh nicht authentifiziert ist

Dateien, die dieser Skill NICHT ohne explizite Zustimmung des Benutzers ändern darf

• _posts/ — wird derzeit geprüft; neue Beiträge durchlaufen PR-Review (siehe Papers unten).
• assets/group/group.yaml — wird über script/calculate verwaltet.
• _config.yml — Site-weite Konfiguration; benötigt explizite Zustimmung des Benutzers.
• script/* — Build-Skripte; benötigt explizite Zustimmung des Benutzers.

Papers (_posts/)

Das Verzeichnis _posts/ enthielt historisch automatisch generierte arXiv-Zusammenfassungen von script/posts/arxiv.py. Stand 5. Mai 2026 werden diese geprüft: Es sollte davon ausgegangen werden, dass nichts in _posts/ von Menschen überprüft wurde, und die /papers/-Seite wird neu aufgebaut, um nur PR-geprüfte Einträge anzuzeigen. Füge im Zweifelsfall nicht direkt zu _posts/ hinzu – öffne einen PR und bitte um menschliche Überprüfung.

Häufige Fehlermodi

• "Read full recipe"-Link fehlt: Der Dateiname-Slug stimmt nicht mit der id der Karte überein. Überprüfe, ob _recipes/<id>.md existiert und die Karte id: <id> hat.
• Doppelte H1 auf der Seite: Der Textkörper beginnt mit # .... Entferne sie; das Layout fügt die H1 aus {{ page.title }} hinzu.
• Leere "Outcome:" / "Evidence:" Labels: Die Kartenfelder sind "". Fülle sie aus; das Rezept ist ohne sie nicht bereit zur Veröffentlichung.
• Build schlägt nach Bearbeitung von _config.yml fehl: Syntaxfehler im Collection- oder Standard-Scope. Die aktuelle Collection ist recipes (Kleinbuchstaben) mit permalink: /cookbook/:path/.