analyze-reference
Extraia padrões, não clone. Esta skill lê UMA página pública (mais no máximo dois links internos nomeados pelo usuário), descreve como ela é construída e como se move em termos abstratos e escreve patterns/<slug>.md. Nada do site é armazenado: nenhuma imagem, vídeo, 3D, logotipo, texto, código, nomes de fontes de marca ou códigos de cores. Capturas de tela são material de trabalho temporário em .cache/analyze/ (git-ignorado) e são sempre excluídas no final.
Isso é uma orientação para o fluxo de trabalho do próprio repositório, não um aconselhamento jurídico. Consulte um advogado de PI antes de industrializar (veja docs/roadmap.md).
Entradas
url(obrigatório): uma página pública http(s). Qualquer coisa atrás de login, paywall ou desafio de bot está fora de escopo.--focus "..."(opcional): o que o usuário gosta no site, em suas próprias palavras. Direciona quais seções da folha recebem profundidade. Registre no frontmatter (nonese omitido).- Até 2 links internos (opcional, mesmo site): analise cada um com os mesmos passos e mescle em uma única folha. Nunca rastreie além.
Slug: derivado do host (www. removido, pontos para traços, ex.: example-com). Passe --slug para recon.mjs se o usuário nomear um. Se patterns/<slug>.md já existir, pergunte antes de substituir.
Todos os comandos são executados a partir da raiz do repositório. Os scripts ficam em .claude/skills/analyze-reference/scripts/; cada um responde a --help.
Passos
Execute em ordem. O passo 6 (limpeza) é executado independentemente de como os passos 1 a 5 terminam: sucesso, abortamento ou erro. Trate-o como um finally.
1. Verificar permissões (antes de tocar no site com um navegador)
node .claude/skills/analyze-reference/scripts/check-robots.mjs <url>
Ele avalia robots.txt para *, ClaudeBot, anthropic-ai e GPTBot, o cabeçalho X-Robots-Tag, <meta name="robots"> e reservas de mineração de dados (TDMRep: /.well-known/tdmrep.json, cabeçalho e meta tdm-reservation). Códigos de saída: 0 permitido, 1 bloqueado, 2 não é possível verificar.
- Saída
1ou2: PARE. Não produza folha, não execute recon. Informe ao usuário os motivos exatos que o script imprimiu. Saída2(5xx, timeout, arquivos ilegíveis) é um abortamento conservador: diga que as permissões não puderam ser verificadas; não tente novamente em loop e não procure outra forma de entrada. - Execute também para cada link interno extra.
- Um 404 para
robots.txtconta como permitido; um 401/403 conta como negado.
2. Reconhecimento
node .claude/skills/analyze-reference/scripts/recon.mjs <url> [--slug <slug>]
Playwright (Chromium headless; defina QA_CHROME_PATH ou CHROME_PATH se o próprio navegador do Playwright não estiver instalado) carrega a página, a percorre e escreve .cache/analyze/<slug>/recon.json e screens/{375,768,1440}-<n>.png. O JSON contém apenas estrutura e estatísticas: seções em ordem com alturas e contagens de cabeçalhos/palavras (nunca texto), tamanhos de tipo agregados, alturas de linha, espaçamento, uso de grid/flex, fontes classificadas como serif/sans/mono/display (nunca nomeadas), cores como descrições de função (nunca códigos), bibliotecas detectadas com evidência e confiança, domínios de rede, presença de canvas/WebGL e observações de movimento (reveal, pin, parallax, scrub, cabeçalho fixo, rolagem suave).
Contêineres de rolagem. Algumas páginas mantêm o documento com uma única altura de viewport e rolam um wrapper interno. recon.mjs detecta isso (o elemento visível overflow-y: auto|scroll|overlay cobrindo pelo menos 60% da viewport com o maior intervalo de rolagem) e o usa para capturas de tela, amostragem de movimento e a sonda de roda. recon.json registra scroller: { kind: "document" | "container", scrollHeightPx, clientHeightPx }, e viewports[w].docHeightPx é a altura rolável realmente usada. Verifique scroller.kind ao ler a evidência. A heurística é registrada, não garantida: se as capturas de tela mostrarem um painel lateral ou modal em vez da página, diga isso na folha. Não coberto: rolagens aninhadas ou horizontais e cenas acionadas por eventos de roda sem elemento rolável. Uma página também pode parar de rolar em uma largura (por exemplo, um breakpoint de tablet); então uma captura de tela nessa largura está correta.
Por trás de um proxy. Quando HTTPS_PROXY ou HTTP_PROXY está definido (sessões em nuvem), check-robots.mjs e recon.mjs se reexecutam uma vez com NODE_USE_ENV_PROXY=1 para que o fetch do Node o use, e recon.mjs passa o proxy para o Chromium (loopback permanece direto). Nenhuma flag necessária; a linha de aviso experimental do Node é ocultada. Os certificados vêm de NODE_EXTRA_CA_CERTS como de costume; os scripts nunca os leem ou incorporam. Sem proxy, nada muda.
Saída 3 significa que a página não é analisável (formulário de login, desafio de bot, HTTP 401/403/429, inacessível). PARE: nenhuma folha, informe ao usuário o motivo (para uma página de login: "a página não é pública"). Nunca tente evitar um bloqueio, resolver um desafio, fazer login ou alterar o user agent.
3. Ler as evidências
- Leia
.cache/analyze/<slug>/recon.jsoncompletamente. - Veja as capturas de tela com a ferramenta Read, pelo menos algumas por largura, para julgar o que os números não podem: composição do hero, ritmo, densidade, onde um layout quebra a grade, o que se move. Elas são apenas para seus olhos; nunca copie, incorpore ou faça referência a elas.
- Confiança: um global ou uma classe DOM mais um nome de script correspondente é
alta; um deles sozinho émédia; um domínio de rede sozinho ébaixa. Bibliotecas agrupadas no código do aplicativo aparecem apenas como correspondências de nome de script, então diga "provavelmente" e mantenha a confiança relatada pelo recon.
4. Escrever a folha
Copie a estrutura de patterns/_template.md para patterns/<slug>.md. Preencha o frontmatter (url, slug, data de hoje como YYYY-MM-DD, focus, libraries como uma lista de nomes) e cada seção, com suas próprias palavras:
| Seção | Conteúdo |
|---|---|
| Resumo | Que tipo de página é esta e por que vale a pena aprender com ela |
| Mapa de seções | Seções ordenadas: função, altura aproximada em viewports, ideia de layout |
| Hero | Tipo de hero, composição da primeira tela, o que se move ao carregar |
| Grade e espaçamento | Sistema de colunas, classe de largura de conteúdo, escala de espaçamento (unidade base), ritmo vertical |
| Tipografia | Classes genéricas ("grotesco grande de display + corpo serifado"), proporção de escala, pesos, hábitos de altura de linha e espaçamento entre caracteres, capitalização |
| Paleta | Funções e tons ("fundo quase preto, acento quente saturado"), caráter de contraste, tema |
| Densidade | Conteúdo por tela, espaços em branco, ideias por seção, equilíbrio texto-mídia |
| Movimento | Tabela: momento, gatilho (carregar, rolar, passar o mouse), tipo (reveal, pin, parallax, scrub, transição de página, shader/3D), técnica e biblioteca, confiança |
| Bibliotecas | Bibliotecas detectadas com a classe de evidência e confiança |
| O que pegar / o que evitar | O que reutilizar como padrão em uma landing original e o que é muito específico ou arriscado de imitar |
Entradas de movimento: uma linha por efeito relevante. Uma seção que fixa enquanto seu conteúdo anima com rolagem é gatilho rolar, tipo pin+scrub, com a biblioteca e sua confiança. O comportamento de passar o mouse não é medido pelo recon; observe as capturas de tela ou a contagem hoverTransitionElements e declare sua confiança como baixa quando inferir.
5. Validar
npm run validate:patterns
Deve passar. Se reportar violações file:line, reescreva essas linhas de forma mais abstrata e execute novamente. Nunca enfraqueça o validador e nunca use uma linha > note: para contrabandear cópia: esse prefixo só isenta seus próprios comentários curtos da regra de citação longa.
Opcional, apenas se um efeito marcado como interessante permanecer inexplicado após o passo 3: npx rea-agents analyze-javascript-application <url> (pesado, nunca obrigatório). Registre apenas uma conclusão escrita ("caminho de câmera vinculado à rolagem acionado por uma biblioteca de timeline, confiança média"), nunca sua saída, código ou dumps. Pule se precisar de acesso de rede que você não tem.
6. Limpeza (sempre)
node .claude/skills/analyze-reference/scripts/recon.mjs --cleanup <slug>
Execute após um sucesso, após um abortamento em qualquer etapa e após um erro. Em seguida, confirme que .cache/analyze/<slug> sumiu e que git status não mostra nada do site (apenas patterns/<slug>.md em caso de sucesso). recon.mjs também remove sua própria pasta quando falha, mas você ainda executa a limpeza.
7. Relatar ao usuário
Diga o que foi analisado, o caminho da folha, as bibliotecas com confiança, qualquer coisa que você não pôde determinar e que um humano deve revisar a folha no PR. Em caso de abortamento: o motivo e que nenhuma folha foi escrita.
Regras de abstração (rigorosas)
Nunca coloque o seguinte na folha, no resumo da folha no chat, em um commit ou em qualquer arquivo versionado:
- Texto do site: manchetes, corpo do texto, microcópia, texto alternativo, meta descrições (apenas o título da página e a URL são permitidos).
- URLs de imagem, vídeo, fonte, modelo 3D ou ícone e qualquer arquivo de ativo.
- Código fonte, marcação, CSS, JS ou fragmentos de shader, mesmo que curtos, minificados ou editados.
- Códigos de cor hex,
rgb(),hsl()ou outros. Descreva por função e tom. - Nomes de fontes de marca ou proprietárias. Use classes genéricas.
- Logotipos, marcas, ilustrações.
Escreva sobre padrões da maneira que um designer faria um briefing para um colega: "seção de declaração fixa, conteúdo varrido em cerca de uma viewport extra", não uma transcrição da marcação. Se você não tiver certeza se um detalhe é conteúdo ou padrão, deixe-o de fora.
Casos de abortamento
| Situação | Ação |
|---|---|
robots.txt nega o caminho para *, ClaudeBot, anthropic-ai ou GPTBot | Pare no passo 1, relate a regra correspondente, nenhuma folha |
Reserva TDM (arquivo TDMRep, cabeçalho ou meta, ou diretiva robots.txt) | Pare no passo 1, relate, nenhuma folha |
noai, noindex ou none em X-Robots-Tag ou meta robots | Pare no passo 1, relate, nenhuma folha |
| Permissões não podem ser verificadas (5xx, timeout, arquivo ilegível) | Pare no passo 1, diga "não é possível verificar permissões", nenhuma folha |
| Formulário de login, paywall, HTTP 401/403/429, desafio de bot | Pare no passo 2, diga que a página não é pública ou bloqueia navegadores automatizados, nenhuma folha; não evite |
| URL inacessível ou resposta não 2xx | Pare no passo 2, relate o erro, nenhuma folha |
| Validação continua falhando | Corrija abstraindo mais; se não puder passar sem perder o ponto, diga e não escreva nenhuma folha |
Em todos os casos de abortamento, execute o passo 6.
Atribuição
A abordagem de reconhecimento (capturas de tela em várias larguras, estrutura DOM, estilos computados, interação e observação de rolagem) é adaptada das fases de recon da skill clone-website em JCodesMore/ai-website-cloner-template, Licença MIT. Apenas a ideia das fases de recon foi reutilizada e reescrita para descrição abstrata; nenhum código e nenhuma de suas fases de download de ativos ou reconstrução está incluída.