analyze-reference
Extrae patrones, no clones. Esta habilidad lee UNA página pública (más hasta dos enlaces internos que nombre el usuario), describe cómo está construida y cómo se mueve en términos abstractos, y escribe patterns/<slug>.md. Nada del sitio se almacena: sin imágenes, video, 3D, logotipos, texto, código, nombres de fuentes de marca ni códigos de color. Las capturas de pantalla son material de trabajo temporal bajo .cache/analyze/ (ignorado por git) y siempre se eliminan al final.
Esto es una guía para el flujo de trabajo del propio repositorio, no un consejo legal. Consulta a un abogado de propiedad intelectual antes de productizarlo (ver docs/roadmap.md).
Entradas
url(obligatorio): una página pública http(s). Cualquier cosa detrás de un inicio de sesión, muro de pago o desafío de bot está fuera del alcance.--focus "..."(opcional): lo que le gusta al usuario del sitio, en sus palabras. Dirige qué secciones de la hoja reciben profundidad. Regístralo en el frontmatter (nonesi se omite).- Hasta 2 enlaces internos (opcional, mismo sitio): analiza cada uno con los mismos pasos y combínalos en una sola hoja. Nunca explores más allá.
Slug: derivado del host (se elimina www., los puntos se convierten en guiones, p.ej. example-com). Pasa --slug a recon.mjs si el usuario nombra uno. Si patterns/<slug>.md ya existe, pregunta antes de reemplazarlo.
Todos los comandos se ejecutan desde la raíz del repositorio. Los scripts están en .claude/skills/analyze-reference/scripts/; cada uno responde a --help.
Pasos
Ejecuta estos en orden. El paso 6 (limpieza) se ejecuta sin importar cómo terminen los pasos 1 a 5: éxito, aborto o error. Trátalo como un finally.
1. Verificar permisos (antes de tocar el sitio con un navegador)
node .claude/skills/analyze-reference/scripts/check-robots.mjs <url>
Evalúa robots.txt para *, ClaudeBot, anthropic-ai y GPTBot, el encabezado X-Robots-Tag, <meta name="robots">, y las reservas de text-and-data-mining (TDMRep: /.well-known/tdmrep.json, encabezado y meta tdm-reservation). Códigos de salida: 0 permitido, 1 bloqueado, 2 no se puede verificar.
- Salida
1o2: DETENTE. No produzcas ninguna hoja, no ejecutes reconocimiento. Dile al usuario las razones exactas que el script imprimió. La salida2(5xx, tiempo de espera, archivos ilegibles) es un aborto conservador: di que no se pudieron verificar los permisos; no reintentes en un bucle ni busques otra forma de entrar. - Ejecútalo también para cada enlace interno adicional.
- Un 404 para
robots.txtcuenta como permitido; un 401/403 cuenta como no permitido.
2. Reconocimiento
node .claude/skills/analyze-reference/scripts/recon.mjs <url> [--slug <slug>]
Playwright (Chromium sin cabeza; configura QA_CHROME_PATH o CHROME_PATH si el navegador propio de Playwright no está instalado) carga la página, la desplaza y escribe .cache/analyze/<slug>/recon.json y screens/{375,768,1440}-<n>.png. El JSON contiene solo estructura y estadísticas: secciones en orden con alturas y recuentos de encabezados/palabras (nunca texto), tamaños de tipo agregados, alturas de línea, espaciado, uso de grid/flex, fuentes clasificadas como serif/sans/mono/display (nunca nombradas), colores como descripciones de roles (nunca códigos), bibliotecas detectadas con evidencia y confianza, dominios de red, presencia de canvas/WebGL y observaciones de movimiento (revelar, pin, paralaje, scrub, encabezado pegajoso, desplazamiento suavizado).
Contenedores de desplazamiento. Algunas páginas mantienen el documento con una altura de un viewport y desplazan un contenedor interno. recon.mjs detecta esto (el elemento visible overflow-y: auto|scroll|overlay que cubre al menos el 60% del viewport con el mayor rango de desplazamiento) y lo usa para capturas de pantalla, muestreo de movimiento y la sonda de rueda. recon.json registra scroller: { kind: "document" | "container", scrollHeightPx, clientHeightPx }, y viewports[w].docHeightPx es la altura desplazable realmente utilizada. Verifica scroller.kind al leer la evidencia. La heurística está registrada, no garantizada: si las capturas de pantalla muestran un panel lateral o modal en lugar de la página, dilo en la hoja. No cubierto: desplazadores anidados u horizontales, y escenas impulsadas por eventos de rueda sin un elemento desplazable. Una página también puede dejar de desplazarse en un ancho (por ejemplo, un punto de interrupción de tableta); entonces una captura de pantalla en ese ancho es correcta.
Detrás de un proxy. Cuando HTTPS_PROXY o HTTP_PROXY está configurado (sesiones en la nube), check-robots.mjs y recon.mjs se re-ejecutan una vez con NODE_USE_ENV_PROXY=1 para que fetch de Node lo use, y recon.mjs pasa el proxy a Chromium (el bucle local permanece directo). No se necesitan banderas; la línea de advertencia experimental de Node está oculta. Los certificados provienen de NODE_EXTRA_CA_CERTS como de costumbre; los scripts nunca los leen ni incrustan. Sin proxy, nada cambia.
La salida 3 significa que la página no es analizable (formulario de inicio de sesión, desafío de bot, HTTP 401/403/429, inalcanzable). DETENTE: no hay hoja, dile al usuario por qué (para una página de inicio de sesión: "la página no es pública"). Nunca intentes evadir un bloqueo, resolver un desafío, iniciar sesión o cambiar el agente de usuario.
3. Leer la evidencia
- Lee
.cache/analyze/<slug>/recon.jsonpor completo. - Ve las capturas de pantalla con la herramienta Read, al menos unas pocas por ancho, para juzgar lo que los números no pueden: composición del héroe, ritmo, densidad, dónde un diseño rompe la cuadrícula, qué se mueve. Son solo para tus ojos; nunca las copies, incrustes o hagas referencia a ellas.
- Confianza: un global o una clase DOM más un nombre de script coincidente es
alta; solo uno de ellos esmedia; solo un dominio de red esbaja. Las bibliotecas incluidas en el código de la aplicación aparecen solo como coincidencias de nombres de script, así que di "probablemente" y mantén la confianza que informó el reconocimiento.
4. Escribir la hoja
Copia la estructura de patterns/_template.md en patterns/<slug>.md. Completa el frontmatter (url, slug, la fecha de hoy como YYYY-MM-DD, focus, libraries como una lista de nombres) y cada sección, con tus propias palabras:
| Sección | Contenido |
|---|---|
| Resumen | Qué tipo de página es y por qué vale la pena aprender de ella |
| Mapa de secciones | Secciones ordenadas: rol, altura aproximada en viewports, idea de diseño |
| Héroe | Tipo de héroe, composición de la primera pantalla, qué se mueve al cargar |
| Cuadrícula y espaciado | Sistema de columnas, clase de ancho de contenido, escala de espaciado (unidad base), ritmo vertical |
| Tipografía | Clases genéricas ("display grotesco grande + cuerpo serif"), proporción de escala, pesos, altura de línea y hábitos de tracking, mayúsculas/minúsculas |
| Paleta | Roles y tonos ("fondo casi negro, acento cálido saturado"), carácter de contraste, tema |
| Densidad | Contenido por pantalla, espacio en blanco, ideas por sección, equilibrio texto-medio |
| Movimiento | Tabla: momento, disparador (carga, desplazamiento, hover), tipo (revelar, pin, paralaje, scrub, transición de página, shader/3D), técnica y biblioteca, confianza |
| Bibliotecas | Bibliotecas detectadas con la clase de evidencia y confianza |
| Qué tomar / qué evitar | Qué reutilizar como patrón en una landing original, y qué es demasiado específico o arriesgado de imitar |
Entradas de movimiento: una fila por efecto relevante. Una sección que se fija mientras su contenido se anima con el desplazamiento es disparador scroll, tipo pin+scrub, con la biblioteca y su confianza. El comportamiento de hover no es medido por el reconocimiento; mira las capturas de pantalla o el recuento de hoverTransitionElements y expresa tu confianza como baja cuando lo infieras.
5. Validar
npm run validate:patterns
Debe pasar. Si reporta violaciones archivo:línea, reescribe esas líneas de forma más abstracta y ejecútalo de nuevo. Nunca debilites el validador, y nunca uses una línea > note: para colar copia: ese prefijo solo exime tus breves comentarios de la regla de cita larga.
Opcional, solo si un efecto marcado como interesante permanece sin explicación después del paso 3: npx rea-agents analyze-javascript-application <url> (pesado, nunca obligatorio). Registra solo una conclusión escrita ("ruta de cámara vinculada al desplazamiento impulsada por una biblioteca de línea de tiempo, confianza media"), nunca su salida, código o volcados. Omítelo si necesita acceso a la red que no tienes.
6. Limpieza (siempre)
node .claude/skills/analyze-reference/scripts/recon.mjs --cleanup <slug>
Ejecútalo después de un éxito, después de un aborto en cualquier paso, y después de un error. Luego confirma que .cache/analyze/<slug> ha desaparecido y que git status no muestra nada del sitio (solo patterns/<slug>.md en caso de éxito). recon.mjs también elimina su propia carpeta cuando falla, pero aún así ejecutas la limpieza.
7. Informar al usuario
Di qué se analizó, la ruta de la hoja, las bibliotecas con confianza, cualquier cosa que no pudiste determinar, y que un humano debe revisar la hoja en el PR. En caso de aborto: la razón, y que no se escribió ninguna hoja.
Reglas de abstracción (estrictas)
Nunca pongas esto en la hoja, el resumen de chat de la hoja, un commit o cualquier archivo versionado:
- Texto del sitio: titulares, cuerpo del texto, microcopia, texto alternativo, meta descripciones (solo se permiten el título de la página y la URL).
- URL de imágenes, videos, fuentes, modelos 3D o iconos, y cualquier archivo de activo.
- Código fuente, marcado, CSS, JS o fragmentos de shader, incluso cortos, minificados o editados.
- Códigos de color Hex,
rgb(),hsl()u otros. Describe por rol y tono. - Nombres de fuentes de marca o propietarias. Usa clases genéricas.
- Logotipos, marcas comerciales, ilustraciones.
Escribe sobre patrones como un diseñador informaría a un colega: "sección de declaración fijada, contenido desplazado a través de aproximadamente un viewport extra", no una transcripción del marcado. Si no estás seguro de si un detalle es contenido o patrón, déjalo fuera.
Casos de aborto
| Situación | Acción |
|---|---|
robots.txt no permite la ruta para *, ClaudeBot, anthropic-ai o GPTBot | Detente en el paso 1, reporta la regla coincidente, sin hoja |
Reserva TDM (archivo TDMRep, encabezado o meta, o directiva de robots.txt) | Detente en el paso 1, repórtalo, sin hoja |
noai, noindex o none en X-Robots-Tag o meta robots | Detente en el paso 1, repórtalo, sin hoja |
| No se pueden verificar los permisos (5xx, tiempo de espera, archivo ilegible) | Detente en el paso 1, di "no se pueden verificar los permisos", sin hoja |
| Formulario de inicio de sesión, muro de pago, HTTP 401/403/429, desafío de bot | Detente en el paso 2, di que la página no es pública o bloquea navegadores automatizados, sin hoja; no evadas |
| URL inalcanzable o respuesta no 2xx | Detente en el paso 2, reporta el error, sin hoja |
| La validación sigue fallando | Arregla abstrayendo más; si no puede pasar sin perder el punto, dilo y no escribas ninguna hoja |
En cada caso de aborto ejecuta el paso 6.
Atribución
El enfoque de reconocimiento (capturas de pantalla en varios anchos, estructura DOM, estilos calculados, observación de interacción y desplazamiento) está adaptado de las fases de reconocimiento de la habilidad clone-website en JCodesMore/ai-website-cloner-template, Licencia MIT. Solo la idea de las fases de reconocimiento fue reutilizada y reescrita para una descripción abstracta; no se incluye código, ni ninguna de sus fases de descarga de activos o reconstrucción.