Communitygithub.com

Claude Eye

Analisa uma gravação de tela de uma animação web/UI quadro a quadro para encontrar bugs de temporização, como elementos que aparecem/desaparecem fora de sincronia, transições escalonadas que chegam no momento errado, cintilação ou travamentos.

O que é Claude Eye?

A habilidade **Claude Eye** transforma gravações de tela de animações web/UI em uma análise quadro a quadro para detectar bugs de temporização que são muito rápidos para serem percebidos a olho nu (tipicamente 100-300 ms). Ela funciona extraindo quadros do vídeo usando ffmpeg, e então utiliza a própria capacidade de visão do Claude (sem necessidade de chave de API externa) para examinar cada quadro e registrar o estado dos elementos animados. A partir dessas observações, a habilidade gera uma linha do tempo detalhada e um relatório de dessincronização, mostrando exatamente quando e onde as animações saem do ritmo. É útil para desenvolvedores que enfrentam problemas com animações CSS/JS, transições, carregamentos de página ou qualquer tipo de movimento na interface, mesmo que eles não peçam explicitamente uma análise 'quadro a quadro'. A habilidade suporta os formatos de vídeo .mp4, .mov, .webm e .gif, e requer apenas Node.js 18+ e ffmpeg/ffprobe instalados no sistema, sem a necessidade de instalar pacotes npm adicionais.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/AbbasMalikzada/claude-eye-skill/tree/HEAD/claude-eye

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Claude Eye: análise de animação quadro a quadro

Você não pode assistir a um vídeo, mas pode ler imagens. Esta habilidade transforma um vídeo em um conjunto de quadros com timestamp, faz com que você observe cada quadro e registre o que cada elemento animado está fazendo, e então transforma essas observações em uma linha do tempo que mostra exatamente quando as coisas saem de sincronia. Bugs de temporização em animações CSS/JS geralmente são da ordem de 100-300 ms, muito rápidos para serem percebidos a olho nu, mas fáceis de ver em uma tabela de quadros.

Os scripts ficam ao lado deste arquivo em scripts/. Eles precisam apenas de Node 18+ e ffmpeg/ffprobe, sem necessidade de npm install. Abaixo, <skill> significa o diretório desta habilidade.

1. Verificar pré-requisitos

Execute ffmpeg -version. Se estiver faltando, informe ao usuário e forneça o comando de instalação para o sistema operacional dele (Windows: winget install Gyan.FFmpeg ou choco install ffmpeg; macOS: brew install ffmpeg; Linux: sudo apt install ffmpeg). Eles precisarão de um novo terminal após a instalação. Não instale você mesmo sem perguntar.

2. Extrair quadros

node <skill>/scripts/extract_frames.mjs <video> --fps 5 --out ./claude-eye-output [--start S] [--end S] [--width 960]

Isso escreve frames/frame_NNNN.png mais um manifest.json que mapeia cada número de quadro para seu timestamp. Sempre use os timestamps do manifesto, nunca os calcule de cabeça.

Controle sua leitura de imagens. Cada quadro lido consome contexto, então mire em cerca de 40 quadros ou menos por passada:

  • Clipe curto (menos de ~8 s): 5 fps em todo o clipe é suficiente.
  • Clipe mais longo, ou você não sabe onde está o problema: faça uma passada grossa primeiro (--fps 1 ou 2 em todo o vídeo) para encontrar onde as coisas se movem. Em seguida, reextraia apenas essa janela em fps mais alto (--start/--end, --fps 10-15) em um diretório --out separado. Relate a passada fina.
  • Se o usuário nomear um momento ("por volta de 3 segundos", "quando o título aparece"), vá direto para essa janela.

A largura padrão de 960 px é suficiente para julgar opacidade e posição. Use uma --width maior apenas se os elementos forem minúsculos.

3. Observar os quadros e registrar observações

Leia os quadros em ordem com a ferramenta Read. Para cada quadro, observe todo elemento visível de texto/UI que está animando ou poderia estar: títulos, subtítulos, botões, imagens, spans de destaque, sobreposições e assim por diante.

Mantenha nomes de seletores estáveis entre quadros: escolha um nome descritivo em kebab-case na primeira vez que vir um elemento (hero-title, subtitle, cta-button) e reutilize exatamente esse nome em todos os quadros seguintes. A linha do tempo junta quadros pelo nome, então hero-title em um quadro e title no próximo se tornam dois elementos diferentes e a análise falha. Inclua um elemento com 0% assim que ele aparecer ou for conhecido como existente. Isso torna os pontos "oculto → entrando em transição" visíveis.

Para cada elemento, estime:

  • opacity_percent (0-100). Julgue em relação ao fundo e à aparência totalmente visível do elemento em quadros posteriores. Revele também revelações parciais: um clip-path ou máscara que está 40% revelada conta como 40.
  • state: um de hidden (≤10%), transitioning-in (subindo), visible (≥90%), transitioning-out (descendo). Compare com quadros vizinhos para distinguir "entrando" de "saindo".
  • Opcional: has_gradient, has_blur e notes para coisas como movimento ("translateY ~20px acima da posição final"), escala, quantidade de desfoque ou mudança de cor. Movimento e escala são tão importantes quanto opacidade, então registre-os em notes quando os vir.

Escreva tudo em <out>/frames.json:

[
  {
    "frame": 1,
    "elements": [
      { "selector": "hero-title", "opacity_percent": 0, "state": "hidden" },
      { "selector": "subtitle", "opacity_percent": 0, "state": "hidden" }
    ],
    "overall_state": "pre-animation",
    "observation": "Área do herói em branco; nada renderizado ainda."
  }
]

frame deve corresponder aos números de quadro do manifesto. Os timestamps são preenchidos a partir do manifesto. Para execuções longas, escreva o arquivo em partes conforme avança, em vez de manter 40 quadros na memória.

A opacidade de um vídeo comprimido é aproximada. Uma diferença de ±10% entre quadros é ruído; padrões ao longo de vários quadros são o sinal.

4. Construir o relatório

node <skill>/scripts/build_report.mjs ./claude-eye-output --context "o que a animação deveria fazer"

Isso produz report.md (resumo, tabela de linha do tempo de opacidade, temporização por elemento, pontos de transição, eventos de dessincronização, observações) e analysis.json. Uma dessincronização é um quadro onde alguns elementos estão totalmente visíveis enquanto outros ainda estão em transição, com mais de 40 pontos de diferença de opacidade entre eles. Use --spread N para tornar isso mais ou menos rigoroso.

5. Interpretar: é aqui que você agrega valor

O script encontra quando as coisas acontecem. Seu trabalho é dizer por que e o que mudar:

  1. Substitua a seção <!-- RECOMENDATIONS --> de report.md por descobertas específicas. Leia a tabela de temporização dos elementos: por exemplo, "subtitle começa 200 ms depois de hero-title e atinge a opacidade total 400 ms depois, o que aponta para uma duração maior combinada com um atraso." Converta diferenças de quadros em milissegundos usando o espaçamento entre quadros (1/fps).
  2. Se o código-fonte do usuário estiver disponível, encontre o CSS/JS para esses elementos (transition, animation, @keyframes, transition-delay, configurações do framer-motion/GSAP) e aponte para as linhas exatas que explicam a temporização observada. Proponha a correção concreta.
  3. Mencione sua precisão de temporização (±1 quadro = ±1/fps s). Se uma conclusão depender de uma diferença menor que um quadro, reextraia essa janela em um fps mais alto antes de afirmá-la.

Em seguida, forneça ao usuário um breve resumo no chat: o que anima, as principais temporizações, cada dessincronização com seu timestamp e causa provável, e a correção. Inclua o caminho para report.md.

Não apenas opacidade

O pipeline de relatório é construído em torno de opacidade/visibilidade, mas a mesma abordagem de leitura de quadros funciona para outras questões, como mudança de layout, um elemento pulando, cintilação (um quadro com estado errado), um carregador girando quando não deveria, ou easing que parece linear. Para esses casos, ainda extraia quadros e leia-os. Você pode pular build_report.mjs e responder diretamente com timestamps referenciados por quadro do manifesto.

Habilidades Relacionadas