mveplus/claude-skills

Site explicativo do projeto

Produz uma apresentação de slides sem dependências externas na pasta site/ que explica um código-fonte desde o porquê até o código, com demonstrações interativas que espelham a lógica real do projeto, além de um job de CI que a publica. Implementação de referência: https://mveplus.github.io/onair-led-sign-firmware/ (19 slides, 4 simulações; fonte em https://github.com/mveplus/onair-led-sign-firmware/tree/main/site).

Modelos no diretório templates/ desta skill:

Arquivo	Copiar para	Propósito
index.html	site/index.html	Estrutura da página + padrões de slide para clonar
deck.css	site/deck.css	Tokens de tema, layout, componentes
deck.js	site/deck.js	Navegação, visão geral, roteamento por hash, loop de frame, auxiliar de etapas
app.js	site/app.js	Ponto de partida para as demonstrações do projeto (conexão de etapas, hook de frame)
github-pages.yml	.github/workflows/pages.yml	Deploy no GitHub Pages
gitlab-ci.yml	mesclar em .gitlab-ci.yml	Deploy no GitLab Pages

O código de demonstração específico do projeto vai em site/app.js (e estilos em um opcional site/app.css); mantenha deck.js e deck.css genéricos.

Processo

1. Perguntar antes de construir (uma chamada AskUserQuestion)

Primeiro, verifique git remote -v para que a pergunta sobre hospedagem reflita a realidade. Se o repositório remoto for GitHub e o usuário disser GitLab (ou o contrário), pergunte sobre isso. Faça no máximo quatro perguntas:

• Hospedagem: GitHub Pages, GitLab Pages ou ambos.
• Público/profundidade: misto (primeiro a ideia, depois um mergulho profundo; padrão), desenvolvedores ou não desenvolvedores.
• Demonstrações interativas: ofereça de 3 a 4 candidatos específicos para este projeto, encontrados em uma análise rápida (máquinas de estado, lógica de temporização/limiar, fluxos de requisição, matemática ou fórmulas, construtores de configuração). multiSelect.
• Opcionalmente: uma restrição de idioma ou marca, se o repositório sugerir uma.

2. Ler o código corretamente

Leia os pontos de entrada, os módulos principais, o README/docs e os arquivos de CI. Para cada afirmação que os slides farão (timeouts, thresholds, defaults, tópicos, endpoints, o que um reset limpa), obtenha do código, não do README. Mantenha uma lista de discrepâncias doc-vs-código e becos sem saída (por exemplo, um job de CI cujo consumidor não existe). Mostre o comportamento real do código nos slides e reporte a lista ao usuário no final. Nunca "corrija" silenciosamente os slides para corresponder aos documentos.

3. Esboço (~12–20 slides), agrupados em capítulos

Arco típico: título (com um elemento interativo divertido) → a ideia / problema → visão geral (arquitetura clicável) → fluxo de requisição/dados (animação passo a passo) → um slide por componente principal → resiliência / tratamento de falhas → segurança / segredos → build, CI, entrega → resumo dos princípios de design com links. Cada slide precisa de um data-chapter e um data-title.

4. Construir

• Copie os modelos e clone os padrões de slide em index.html (hero, duas colunas com um card, etapas, grade de informações).
• As simulações reutilizam o algoritmo real do projeto: portar a função (matemática de inteiros, limites, ordenação) e citar seu nome no slide. Uma simulação que apenas parece correta é um bug.
• Use Deck.onFrame(slideId, fn) para animação, de forma que apenas o slide visível anime. Use Deck.stepper(...) para sequências de cliques.
• Diagramas: SVG inline usando os tokens CSS; nada externo. Sem CDNs e sem fontes para buscar, para que o site funcione offline e em Pages restritos.
• Imagens: copie para site/img/, redimensionadas com metadados removidos (com ImageMagick: magick in -auto-orient -strip -resize 1200x -quality 80 out.jpg). Verifique as imagens originais do repositório em busca de EXIF de GPS (por exemplo, identify -format '%[EXIF:GPSLatitude]' ou exiftool -gps:all) e avise o usuário se alguma for encontrada. Fotos de celular geralmente carregam a localização de onde foram tiradas. Depois de enviadas, estão no histórico do git, então removê-las exige uma reescrita do histórico, o que é uma decisão do usuário.

5. Configuração de publicação

• GitHub: copie github-pages.yml. O Pages deve ser ativado uma vez com source = Actions (Settings → Pages), ou com o comando abaixo. Forneça comandos que o usuário copiará em um bloco de código cercado por crases, sem nada depois deles. Um ponto final de frase copiado junto com o comando acaba no argumento (build_type=workflow.), e a API o rejeita:

  gh api -X POST repos/OWNER/REPO/pages -f build_type=workflow
  

  Ele só faz deploy a partir do branch padrão.
• GitLab: mescle o job pages em qualquer .gitlab-ci.yml existente; não o sobrescreva. O Pages é ativado automaticamente; a URL é mostrada em Deploy → Pages.
• Adicione um breve parágrafo com link na seção de visão geral / "Como funciona" do README.

6. Verificar antes de relatar

• node --check site/*.js
• Sirva com python3 -m http.server 8765 --bind 127.0.0.1 --directory site (em segundo plano). Se uma ferramenta de automação de navegador estiver disponível (por exemplo, Claude no Chrome), abra o site, tire screenshots de cada capítulo e execute cada demonstração executando JavaScript na página (.click(), PointerEvents disparados) em vez de clicar em coordenadas: screenshots geralmente são dimensionadas em relação aos pixels CSS, então cliques em coordenadas erram. Se a janela não puder ser redimensionada, verifique a largura de telefone carregando o site em um iframe de 380 px e procurando elementos com getBoundingClientRect().right > 381.
• Sem uma ferramenta de navegador, diga ao usuário quais páginas e demonstrações verificar manualmente. Não relate o site como testado.
• Feche quaisquer abas que você abriu e pare o servidor depois.

7. Entregar

Pergunte antes de commitar ou fazer push. Então, em um branch: um commit para o site, commits separados para quaisquer correções de código que o usuário solicitar. Relate: o que foi construído, como habilitar o Pages, a lista de discrepâncias e qualquer coisa não testada (por exemplo, hardware).

Regras de estilo

• Tema escuro por padrão (tokens em deck.css), com um acento vermelho que pode ser retocado por projeto via --accent.
• Texto simples e concreto. Explique por que uma escolha de design existe, não apenas o que ela faz.
• Trechos de código são curtos e reais (extraídos da fonte, com um comentário nomeando o arquivo).
• Teclado: ←/→/Espaço/PageUp/PageDown/Home/End, O para a visão geral, Esc para fechar. Deslizar no toque. Cada slide tem sua própria URL (#/id-do-slide).