Sitio web handley-lab.github.io

Habilidad del sitio web

Usa esta habilidad cuando trabajes dentro de handley-lab.github.io. Codifica las convenciones del sitio de CLAUDE.md y el flujo de trabajo para agregar recetas del cookbook y otro contenido.

Cuándo usarla

• El usuario quiere añadir o editar contenido en el sitio.
• El usuario quiere previsualizar sus cambios localmente.
• El usuario quiere publicar una receta (tarjeta y página complementaria opcional de formato largo).
• Una habilidad de receta (u otra habilidad de contenido) entrega un borrador para previsualización.

Inicialización

Una vez por máquina:

script/bootstrap            # gem install bundler && bundle install

Previsualización local

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

La recarga en vivo detecta ediciones en *.md, _data/*.yml, _layouts/*.html, _includes/*.html y archivos de colecciones en _recipes/.

Verificación de compilación

Antes de hacer commit:

script/build                # bundle exec jekyll build → _site/

Si has tocado algo que pueda exponer skills/, ejecuta también las comprobaciones de filtraciones. El repositorio intencionadamente tiene tanto una página pública skills.md (que publica en /skills/) como un directorio privado skills/ (excluido de la compilación). La combinación es sutil: estas comprobaciones hacen explícita la distinción:

# La página pública del marketplace debe existir.
test -f _site/skills/index.html
# Los archivos de habilidad en bruto NO deben filtrarse.
test ! -e _site/skills/website
test ! -e _site/skills/recipe
test ! -e _site/skills/README.md
# Cualquier otra cosa bajo _site/skills/ que no sea index.html y los assets compilados es una filtración.
find _site/skills -mindepth 1 ! -name index.html ! -name '*.css' ! -name '*.js' -print

El find final no debería imprimir nada.

script/cibuild              # compila, verifica que _site/index.html existe, luego elimina _site

Si script/cibuild sale con 0 (imprimiendo "¡Compila!"), el sitio se compila.

El modelo de contenido del AI Cookbook

Dos superficies:

• _data/recipes.yml — la lista de tarjetas de recetas que se muestra en /cookbook/. Cada receta tiene una tarjeta aquí.
• _recipes/<id>.md — página complementaria opcional renderizada en /cookbook/<id>/. Añade un enlace "Leer receta completa" a la tarjeta.

Las entradas solo con tarjeta son válidas. La longitud es una propiedad de la receta; algunas recetas se leen en 3–4 minutos sin página complementaria, otras tienen un artículo más extenso que merece un enlace.

Añadir o editar una tarjeta de receta

Las tarjetas de receta viven solo en _data/recipes.yml. No requieren un archivo en _recipes/.

- id: <id>
  title: "..."                           # descriptivo claro — di qué es, no lo ingenioso que es
  category: "..."                        # p. ej. Ingeniería de Contexto, Comunicación de Investigación
  timebox: "..."                         # p. ej. 10 minutos, una tarde, varias sesiones
  status: "Draft"                        # Borrador | En progreso | Completo
  proposer: "..."                        # opcional; útil para atribución en talleres
  summary: "..."                         # 1–2 frases. Empieza con lo que fue posible, no con lo eficiente.
  outcome: "..."                         # requerido, debe ser no vacío (Borrador: ... es aceptable)
  evidence: "..."                        # requerido, debe ser no vacío (Borrador: ... es aceptable)
  demo_url:
  repo_url: "..."

Durante el taller del 5 de mayo de 2026 y cualquier taller posterior, prefiere publicar el YAML de la tarjeta de receta en el issue de coordinación para que el orquestador lo fusione por lote en lugar de abrir muchos PRs en competencia contra _data/recipes.yml — el archivo es un imán de conflictos de fusión bajo ediciones paralelas.

Añadir una página complementaria de formato largo para una receta

Una receta de formato largo tiene dos mitades que deben mantenerse sincronizadas:

1. Tarjeta — una entrada en _data/recipes.yml. Se renderiza en /cookbook/ y en el bloque de previsualización de la página de inicio.
2. Página complementaria — un archivo en _recipes/<id>.md. Se renderiza en /cookbook/<id>/.

La tarjeta include (_includes/recipe_card.html) descubre una página complementaria coincidente por el slug de la colección — Jekyll deriva automáticamente el slug del nombre del archivo. Por lo tanto <id> (el campo de la tarjeta, el id del frontmatter de la página complementaria y el nombre del archivo) deben coincidir todos. De lo contrario, el enlace "Leer receta completa" no aparecerá.

Paso 1 — Elige <id> y verifica que no esté en uso

• kebab-case (p. ej. jaxwavelets, gw-emulator, cosmosis-cobaya-port).
• Único en los tres lugares donde debe coincidir (nombre de archivo, id de la tarjeta, id del frontmatter de la complementaria).

Comprobación con script (ejecuta con tu <id> elegido):

id="<id>"
fail=0

# 1. El id de la tarjeta no debe existir en _data/recipes.yml
if grep -nE "^- id: ${id}\" _data/recipes.yml; then
  echo "ERROR: _data/recipes.yml ya tiene id: ${id}"; fail=1
fi

# 2. El nombre de archivo de la complementaria no debe existir
if test -e "_recipes/${id}.md"; then
  echo "ERROR: _recipes/${id}.md ya existe"; fail=1
fi

# 3. El id del frontmatter de la complementaria no debe existir bajo otro nombre de archivo
if grep -RsnE "^id: ${id}\" _recipes; then
  echo "ERROR: otro archivo _recipes/*.md ya tiene id: ${id}"; fail=1
fi

[ "$fail" = 0 ] && echo "OK: ${id} está libre"

Si alguna comprobación falla, elige un id diferente. No sobrescribas.

Paso 2 — Crea la rama de funcionalidad

git checkout -b recipe/<id>

Primero la rama, luego escribe — los cambios sin commit se trasladan, pero es más limpio delimitar tus ediciones a la rama desde el principio. Nunca hagas push directamente a main.

Paso 3 — Escribe _recipes/<id>.md

El frontmatter debe incluir el esquema completo de la tarjeta (para que la página sea autodocumentada y el diseño tenga los datos que necesita):

---
id: <id>
title: "..."
category: "..."
timebox: "..."
status: "Draft"            # Borrador | En progreso | Completo
summary: "..."
outcome: "..."
evidence: "..."
demo_url:                  # opcional; deja el campo sin valor u omítelo por completo
repo_url: "..."            # opcional
author: "..."
date: YYYY-MM-DD
---

status acepta "Borrador", "En progreso" o "Completo". outcome y evidence deben ser no vacíos (para borradores, comienza con "Borrador: ..." en lugar de dejarlo en blanco).

Luego el cuerpo de formato largo. No escribas un H1 inicial en el cuerpo — _layouts/recipe.html renderiza {{ page.title }} como el H1. Empieza el cuerpo con ## Sección.

Usa _recipes/jaxwavelets.md como plantilla de referencia (con la advertencia de que su ejecución fue criticada en el taller del 5 de mayo de 2026 por ser demasiado larga y densa — prefiere lecturas de 3–4 minutos con una nota de Métodos para detalles forenses).

Paso 4 — Añade una tarjeta coincidente a _data/recipes.yml

- id: <id>                              # DEBE coincidir con _recipes/<id>.md
  title: "..."
  category: "..."
  timebox: "..."
  status: "..."
  summary: "..."
  outcome: "..."                        # requerido, debe ser no vacío
  evidence: "..."                       # requerido, debe ser no vacío
  demo_url:
  repo_url: "..."

No envíes outcome o evidence vacíos. Si no puedes escribirlos, la receta no está lista para publicar.

Paso 5 — Previsualización

script/server (o actualiza el servidor en ejecución). Visita:

• /cookbook/<id>/ — la página complementaria se renderiza con el título del frontmatter como H1, MathJax cargado si es necesario.
• /cookbook/ — la nueva tarjeta aparece con un enlace funcional "Leer receta completa".
• / — el bloque de previsualización de la página de inicio refleja el cambio si <id> está entre las primeras tres tarjetas.

Paso 6 — Verificación de compilación + commit

script/cibuild                          # sale con 0 si todo está bien
git add _recipes/<id>.md _data/recipes.yml
git commit -m "Añadir receta <id>"
git push -u origin recipe/<id>
gh pr create                            # o abre el PR en la interfaz web de GitHub si gh no está autenticado

Archivos que esta habilidad NO DEBE modificar sin la aprobación explícita del usuario

• _posts/ — actualmente en auditoría; las nuevas publicaciones pasan por revisión de PR (ver Artículos más abajo).
• assets/group/group.yaml — gestionado mediante script/calculate.
• _config.yml — configuración de todo el sitio; necesita aprobación explícita del usuario.
• script/* — scripts de compilación; necesita aprobación explícita del usuario.

Artículos (_posts/)

El directorio _posts/ históricamente contenía resúmenes de arXiv generados automáticamente desde script/posts/arxiv.py. A partir del 5 de mayo de 2026, estos están siendo auditados: nada en _posts/ debe asumirse como revisado por humanos, y la página /papers/ se está reconstruyendo para mostrar solo entradas revisadas por PR. En caso de duda, no añadas directamente a _posts/ — abre un PR y solicita revisión humana.

Modos de fallo comunes

• Falta el enlace "Leer receta completa": el slug del nombre de archivo no coincide con el id de la tarjeta. Verifica que _recipes/<id>.md existe y que la tarjeta tiene id: <id>.
• H1 duplicado en la página: el cuerpo comienza con # .... Elimínalo; el diseño añade el H1 desde {{ page.title }}.
• Etiquetas "Resultado:" / "Evidencia:" vacías: los campos de la tarjeta son "". Complétalos; la receta no está lista para publicar sin ellos.
• La compilación falla después de editar _config.yml: error de sintaxis en la colección o en el ámbito de valores predeterminados. La colección actual es recipes (minúsculas) con permalink: /cookbook/:path/.