handley-lab/handley-lab.github.io

Habilidade do site

Use esta habilidade ao trabalhar dentro de handley-lab.github.io. Ela codifica as convenções do site de CLAUDE.md e o fluxo de trabalho para adicionar receitas do cookbook e outros conteúdos.

Quando usar

• O usuário deseja adicionar ou editar conteúdo no site.
• O usuário deseja pré-visualizar suas alterações localmente.
• O usuário deseja publicar uma receita (cartão e página complementar opcional de formato longo).
• Uma habilidade recipe (ou outra habilidade de conteúdo) entrega um rascunho para pré-visualização.

Inicialização

Uma vez por máquina:

script/bootstrap            # gem install bundler && bundle install

Pré-visualização local

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

A recarga automática captura edições em *.md, _data/*.yml, _layouts/*.html, _includes/*.html e arquivos de coleção em _recipes/.

Verificação de compilação

Antes de commitar:

script/build                # bundle exec jekyll build → _site/

Se você tiver tocado em algo que possa expor skills/, execute também as verificações de vazamento. O repositório intencionalmente tem tanto uma página pública skills.md (que publica em /skills/) quanto um diretório de origem skills/ privado (excluído da compilação). A combinação é sutil — essas verificações tornam a distinção explícita:

# A página pública do marketplace deve existir.
test -f _site/skills/index.html
# Os arquivos de habilidade brutos NÃO devem vazar.
test ! -e _site/skills/website
test ! -e _site/skills/recipe
test ! -e _site/skills/README.md
# Qualquer outra coisa em _site/skills/ além de index.html e assets compilados é um vazamento.
find _site/skills -mindepth 1 ! -name index.html ! -name '*.css' ! -name '*.js' -print

O find final não deve imprimir nada.

script/cibuild              # compila, verifica se _site/index.html existe, depois exclui _site

Se script/cibuild sair com código 0 (imprimindo "Compila!"), o site compila.

O modelo de conteúdo do AI Cookbook

Duas superfícies:

• _data/recipes.yml — a lista de cartões de receita exibidos em /cookbook/. Toda receita tem um cartão aqui.
• _recipes/<id>.md — página complementar opcional renderizada em /cookbook/<id>/. Adiciona um link "Ler receita completa" ao cartão.

Entradas apenas com cartão são válidas. O tamanho é uma propriedade da receita; algumas receitas são leituras de 3 a 4 minutos sem página complementar, outras têm um texto mais longo que vale a pena vincular.

Adicionando ou editando um cartão de receita

Os cartões de receita residem apenas em _data/recipes.yml. Eles não exigem um arquivo em _recipes/.

- id: <id>
  title: "..."                           # descrição simples — diga o que é, não quão inteligente é
  category: "..."                        # ex.: Engenharia de Contexto, Comunicação de Pesquisa
  timebox: "..."                         # ex.: 10 minutos, uma tarde, várias sessões
  status: "Rascunho"                      # Esboço | Rascunho | Em andamento | Completo
  proposer: "..."                        # opcional; útil para atribuição em workshop
  summary: "..."                         # 1–2 frases. Comece pelo que se tornou possível, não pelo que foi eficiente.
  outcome: "..."                         # obrigatório, não pode estar vazio (Esboço: ... é aceitável)
  evidence: "..."                        # obrigatório, não pode estar vazio (Esboço: ... é aceitável)
  demo_url:
  repo_url: "..."

Durante o workshop de 5 de maio de 2026 e qualquer workshop subsequente, prefira postar o YAML do cartão de receita no issue de coordenação para merge em lote pelo orquestrador, em vez de abrir muitos PRs concorrentes contra _data/recipes.yml — o arquivo é um ímã de conflitos de merge sob edições paralelas.

Adicionando uma página complementar de formato longo para uma receita

Uma receita de formato longo tem duas metades que devem permanecer sincronizadas:

1. Cartão — uma entrada em _data/recipes.yml. Renderizado em /cookbook/ e no bloco de pré-visualização da página inicial.
2. Página complementar — um arquivo em _recipes/<id>.md. Renderizado em /cookbook/<id>/.

O include do cartão (_includes/recipe_card.html) descobre uma página complementar correspondente pelo slug da coleção — o Jekyll deriva automaticamente o slug do nome do arquivo. Portanto, <id> (o campo do cartão, o id do frontmatter da página complementar e o nome do arquivo) devem todos concordar. Caso contrário, o link "Ler receita completa" não aparecerá.

Etapa 1 — Escolha <id> e verifique se não está em uso

• kebab-case (ex.: jaxwavelets, gw-emulator, cosmosis-cobaya-port).
• Único em todos os três lugares onde deve concordar (nome do arquivo, id do cartão, id do frontmatter da página complementar).

Verificação via script (execute com o <id> escolhido):

id="<id>"
fail=0

# 1. O id do cartão não deve existir em _data/recipes.yml
if grep -nE "^- id: ${id}\" _data/recipes.yml; then
  echo "ERRO: _data/recipes.yml já tem id: ${id}"; fail=1
fi

# 2. O nome do arquivo complementar não deve existir
if test -e "_recipes/${id}.md"; then
  echo "ERRO: _recipes/${id}.md já existe"; fail=1
fi

# 3. O id do frontmatter complementar não deve existir sob outro nome de arquivo
if grep -RsnE "^id: ${id}\" _recipes; then
  echo "ERRO: outro _recipes/*.md já tem id: ${id}"; fail=1
fi

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

Se alguma verificação falhar, escolha um id diferente. Não sobrescreva.

Etapa 2 — Crie o branch de funcionalidade

git checkout -b recipe/<id>

Crie o branch primeiro, depois escreva — as alterações não commitadas são transportadas, mas é mais limpo limitar suas edições ao branch desde o início. Nunca empurre diretamente para main.

Etapa 3 — Escreva _recipes/<id>.md

O frontmatter deve incluir o esquema completo do cartão (para que a página seja autodocumentada e o layout tenha os dados necessários):

---
id: <id>
title: "..."
category: "..."
timebox: "..."
status: "Rascunho"            # Esboço | Rascunho | Em andamento | Completo
summary: "..."
outcome: "..."
evidence: "..."
demo_url:                  # opcional; deixe o campo sem valor ou omita completamente
repo_url: "..."            # opcional
author: "..."
date: YYYY-MM-DD
---

status aceita "Esboço", "Rascunho", "Em andamento" ou "Completo". outcome e evidence devem ser não vazios (para esboços, comece com Esboço: ... em vez de deixar em branco).

Em seguida, o corpo de formato longo. Não escreva um H1 inicial no corpo — _layouts/recipe.html renderiza {{ page.title }} como o H1. Comece o corpo com ## Seção.

Use _recipes/jaxwavelets.md como modelo de referência (com a ressalva de que sua execução foi criticada no workshop de 5 de maio de 2026 por ser muito longa e densa — prefira leituras de 3 a 4 minutos com uma nota de Métodos para detalhes forenses).

Etapa 4 — Acrescente um cartão correspondente a _data/recipes.yml

- id: <id>                              # DEVE corresponder a _recipes/<id>.md
  title: "..."
  category: "..."
  timebox: "..."
  status: "..."
  summary: "..."
  outcome: "..."                        # obrigatório, não pode estar vazio
  evidence: "..."                       # obrigatório, não pode estar vazio
  demo_url:
  repo_url: "..."

Não envie outcome ou evidence vazios. Se você não pode escrevê-los, a receita não está pronta para publicar.

Etapa 5 — Pré-visualização

script/server (ou atualize o servidor em execução). Visite:

• /cookbook/<id>/ — a página complementar renderiza com o título do frontmatter como H1, MathJax carregado se necessário.
• /cookbook/ — o novo cartão aparece com um link "Ler receita completa" funcional.
• / — o bloco de pré-visualização da página inicial reflete a alteração se <id> estiver entre os três primeiros cartões.

Etapa 6 — Verificação de compilação + commit

script/cibuild                          # sai com código 0 se tudo estiver bem
git add _recipes/<id>.md _data/recipes.yml
git commit -m "Adiciona receita <id>"
git push -u origin recipe/<id>
gh pr create                            # ou abra o PR na interface web do GitHub se gh não estiver autenticado

Arquivos que esta habilidade NÃO DEVE modificar sem OK explícito do usuário

• _posts/ — atualmente em auditoria; novas postagens passam por revisão de PR (veja Papers abaixo).
• assets/group/group.yaml — gerenciado via script/calculate.
• _config.yml — configuração global do site; precisa de OK explícito do usuário.
• script/* — scripts de compilação; precisa de OK explícito do usuário.

Papers (_posts/)

O diretório _posts/ historicamente continha resumos de arXiv gerados automaticamente por script/posts/arxiv.py. A partir de 5 de maio de 2026, estes estão sendo auditados: nada em _posts/ deve ser considerado revisado por humanos, e a página /papers/ está sendo reconstruída para exibir apenas entradas revisadas por PR. Em caso de dúvida, não adicione diretamente a _posts/ — abra um PR e solicite revisão humana.

Modos de falha comuns

• Link "Ler receita completa" ausente: o slug do nome do arquivo não corresponde ao id do cartão. Verifique se _recipes/<id>.md existe e se o cartão tem id: <id>.
• H1 duplicado na página: o corpo começa com # .... Remova-o; o layout adiciona o H1 de {{ page.title }}.
• Rótulos "Resultado:" / "Evidência:" vazios: os campos do cartão são "". Preencha-os; a receita não está pronta para publicar sem eles.
• A compilação falha após editar _config.yml: erro de sintaxe na coleção ou nos escopos padrão. A coleção atual é recipes (minúsculas) com permalink: /cookbook/:path/.