Theycallmeholla/skills – Gravação de Passo a Passo no Navegador

Skill de Gravação de Passo a Passo (GIF)

Gera um projeto Node.js autossuficiente que grava um passo a passo no navegador e exporta MP4 + GIF.

Quando usar esta skill vs. claude-in-chrome gif_creator

Para uma captura rápida e única dentro da sessão ativa do navegador do usuário (seu perfil, abas abertas, já logado), a ferramenta claude-in-chrome gif_creator é muito mais simples — sem estrutura de projeto, sem chaves de API. Recorra a esta skill quando o usuário precisar de algo que o gif_creator não pode oferecer: um script reexecutável/versionável (regravar após cada alteração na UI), saída MP4, um GIF gifski de alta qualidade, uma gravação com perfil limpo (sem favoritos/extensões pessoais no quadro) ou repetibilidade em CI.

Arquitetura

Descrição em linguagem natural
        ↓
Claude gera script TypeScript
        ↓
Stagehand v3 (controle de navegador com IA) — Playwright conectado via CDP
        ↓
Contexto de gravação do Playwright captura vídeo (.webm)
        ↓
ffmpeg converte → .mp4
gifski converte quadros → .gif
        ↓
Saída: walkthrough.mp4 + walkthrough.gif + walkthrough.md

Fluxo de Trabalho

Etapa 1: Levantar Requisitos

Pré-requisito — Chave de API LLM: O Stagehand chama um LLM para cada ação de IA. O usuário precisa de ANTHROPIC_API_KEY (ou a chave do provedor correspondente ao modelo configurado, por exemplo, OPENAI_API_KEY) disponível para .env. Confirme isso antecipadamente — sem ela, o script gerado não pode ser executado.

Antes de gerar qualquer código, confirme:

1. URL alvo — Onde o passo a passo começa? (por exemplo, https://app.example.com/login)
2. Descrição do fluxo — Quais etapas devem ser demonstradas? (linguagem natural é suficiente)
3. Situação de autenticação — A página é pública ou precisa de login? Se precisar de login: eles vão colocar credenciais fixas no .env, usar uma sessão/exportação de cookies pré-autenticada ou começar de um estado já logado?
4. Formato de saída — Apenas GIF, apenas MP4 ou ambos? (padrão: ambos)
5. Duração / ritmo — Demonstração rápida ou passo a passo deliberado? (~1-2s de pausa entre etapas é o padrão)
6. Viewport — O padrão é 1280×800. Mais estreito para demonstrações no estilo mobile.

Se o usuário fornecer uma descrição rica antecipadamente, infira o que puder e pergunte apenas sobre lacunas.

Etapa 2: Gerar o Projeto

Gere um projeto completo e executável em ./walkthrough-[nome]/:

walkthrough-[nome]/
├── package.json
├── tsconfig.json
├── .env.example
├── src/
│   └── walkthrough.ts      ← script principal
└── scripts/
    └── convert.sh          ← conversão com ffmpeg + gifski

Leia references/stagehand-patterns.md para a API do Stagehand e padrões de tradução de etapas. Leia references/output-pipeline.md para comandos de conversão com ffmpeg/gifski e ajustes de GIF.

Etapa 3: Traduzir Etapas

Converta a linguagem natural do usuário em chamadas stagehand.act() (v3: act() reside na instância do stagehand e recebe uma string simples, com opções como variables e page). Consulte references/stagehand-patterns.md para padrões e armadilhas.

Regras-chave de tradução:

• Cada ação lógica na UI = uma chamada stagehand.act("...", { page }) com uma instrução clara em inglês
• Entrada digitada passa por variables (placeholders %name%) — nunca coloque segredos inline na string de instrução
• Adicione page.waitForTimeout(1500) entre etapas principais para ritmo (visível para o espectador)
• Adicione page.waitForLoadState('networkidle') após navegações
• Nunca codifique seletores — o Stagehand os descobre a partir de instruções em linguagem natural
• Para fluxos com autenticação: use .env para credenciais, nunca codifique

Etapa 4: Estratégia de Gravação

Sempre use gravação de vídeo do Playwright como método de captura principal:

• O Stagehand v3 não tem gravação embutida — conecte o Playwright ao navegador do Stagehand via chromium.connectOverCDP({ wsEndpoint: stagehand.connectURL() }), crie um contexto com a opção recordVideo e controle a página desse contexto (consulte references/stagehand-patterns.md)
• Grave a sessão completa como .webm através desse contexto de gravação
• NÃO tente unir capturas de tela individuais diretamente em GIF — vídeo → quadros → GIF tem qualidade superior
• Após a conclusão do script, execute convert.sh para produzir MP4 e GIF

Nunca faça do GIF o artefato principal. O MP4 é sempre produzido primeiro. O GIF é derivado dele. GIFs são grandes e de baixa qualidade para qualquer coisa com mais de 15 segundos — avise o usuário e sugira manter os passos a passos abaixo de 60s.

Etapa 5: Sobreposições de Clique/Cursor (Opcional, mas recomendado)

Injete uma sobreposição de destaque de clique via page.addInitScript() antes do passo a passo começar. Consulte references/stagehand-patterns.md → seção "Click Overlay" para o trecho de código.

Isso adiciona uma animação sutil de ondulação em cada ponto de clique — tornando os passos a passos dramaticamente mais legíveis sem pós-processamento.

Etapa 6: Saída

Após a geração, produza:

1. O diretório do projeto (todos os arquivos)
2. Uma breve lista de verificação de configuração na conversa:

## Configuração
npm install
npx playwright install chromium
cp .env.example .env  # preencha ANTHROPIC_API_KEY + quaisquer credenciais

## Execução
npx tsx src/walkthrough.ts

## Converter para GIF + MP4
bash scripts/convert.sh

Informe também ao usuário o que esperar: duração aproximada, tamanho do viewport, nomes dos arquivos de saída.

Ofereça-se para executar: O Claude Code pode executar todo o pipeline sozinho — npm install, npx playwright install chromium, executar o script de passo a passo e depois bash scripts/convert.sh — se o usuário concordar (eles ainda precisam fornecer os valores do .env). Ao executá-lo você mesmo, verifique a saída antes de declarar sucesso: use ffprobe no MP4 para uma duração razoável e verifique se os tamanhos dos arquivos GIF/MP4 são não triviais (convert.sh os imprime em sua cauda de verificação).

---

Avisos / Condições de Abandono

Informe o usuário antecipadamente se algum destes se aplicar:

Condição	Orientação
Página requer login com MFA/SSO	O script não pode lidar com isso automaticamente — o usuário deve exportar cookies de uma sessão de navegador logada
CAPTCHA na página alvo	O Playwright irá travar — use um ambiente de demonstração/sandbox
Animações pesadas / rolagem infinita	A gravação os capturará, mas a conversão para GIF será grande — sugira cortar
Fluxo com >90 segundos	Recomende apenas MP4; o GIF será inutilizavelmente grande
Conteúdo da página é aleatório/dinâmico	O Stagehand lida com alvo visual, mas avise que reexecuções podem parecer diferentes

---

Convenção de Nomenclatura de Saída

walkthrough-[slug]/
  output/
    walkthrough.webm     ← gravação bruta do Playwright
    walkthrough.mp4      ← convertido (H.264, seguro para web)
    walkthrough.gif      ← saída do gifski, máximo 800px de largura
    walkthrough.md       ← anotação passo a passo (gerada automaticamente)

O arquivo .md lista cada chamada act() como uma etapa numerada com timestamps — útil para incorporar como legenda junto ao GIF.

---

Arquivos de Referência

• references/stagehand-patterns.md — API do Stagehand, tradução de etapas, trecho de sobreposição de clique, padrões de autenticação
• references/output-pipeline.md — comandos ffmpeg, flags do gifski, otimização de GIF, solução de problemas