wlsdnen/explainer-page

Creación de página explicativa

Cuándo usar

• Al crear una página explicativa nueva (HTML único o carpeta).
• Al cambiar sustancialmente la estructura, figuras o explicación de una página existente.

Si la carpeta o proyecto de la página contiene un CLAUDE.md, sus reglas tienen prioridad sobre este skill.

Idioma de salida

El idioma de salida predeterminado es coreano (합쇼체, lang="ko"). Si el usuario solicita otro idioma o el CLAUDE.md del proyecto lo define, se escribe en ese idioma, y se cambia el atributo lang, la pila de fuentes tipográficas y las reglas de estilo de escritura (references/writing.md) según corresponda. El resto de reglas se aplican independientemente del idioma.

Resultado

• Un único index.html autocontenido, sin paso de compilación (CSS/JS inline). Si hay videoclips o imágenes, se colocan en la misma carpeta.
• Las bibliotecas externas se cargan desde CDN con una versión exacta fijada, o, si se necesita funcionamiento sin conexión, se colocan (vendoring) archivos en la carpeta y se cargan con rutas relativas. Se pregunta al usuario qué opción prefiere o se indica en el CLAUDE.md de la carpeta de la página.

Flujo de trabajo

1. Recopilación de datos y verificación de hechos

• Abrir y leer directamente el artículo, video, repositorio de código o blog/página web. Verificar todas las afirmaciones y cifras que se usarán en la página contra el original (números de tabla/figura, marcas de tiempo del video, ubicación en el código, secciones del blog). Si el blog cita un artículo, verificar preferiblemente en el artículo original.
• Crear una lista de conceptos previos necesarios para entender el texto. Son el material para la entrevista del siguiente paso.

2. Entrevista de nivel del lector (obligatoria antes de la estructuración)

• Preguntar mediante AskUserQuestion (opción múltiple) por cada concepto previo si el lector 'lo conoce', 'lo domina a medias' o 'no lo conoce'. Si no está disponible AskUserQuestion, formular la misma pregunta en texto.
• Profundizar según las respuestas. Continuar hasta que se determine el nivel necesario para la comprensión del texto.
• Registrar el resultado en la sección ## Nivel del lector del CLAUDE.md de la carpeta de la página, por concepto. En modificaciones posteriores, leer este registro y mantener el mismo nivel. Al desplegar la página, no incluir CLAUDE.md.
• Aplicación en el texto:
  • No conoce: explicar en el texto principal.
  • Domina a medias: poner en un cuadro de repaso breve (<details>).
  • Conoce: omitir la explicación.

3. Estructuración

• Determinar primero el flujo de la página y los títulos de las secciones (como oraciones de afirmación). Para cada sección, decidir la figura (animación, imagen estática, deslizador) y los videoclips que mostrarán la afirmación.
• Si el tema incluye datos, modelo y evaluación, incluir en la estructura de secciones el flujo desde los datos hasta las métricas de evaluación.
• Detalles: references/writing.md, references/visuals.md.

4. Redacción

• Un único index.html con CSS/JS inline. Separar la lógica de cálculo en scripts sin DOM.
• Si hay fuente de video, recortar clips para cada sección explicativa.
• Detalles: references/writing.md, references/visuals.md, references/style.md.

5. Verificación

• Ejecutar scripts/check_page.py para comprobar desbordamiento horizontal en 375, 768 y 1280 píxeles, errores de consola y tamaño táctil del primer [data-widget].
• Verificar también el funcionamiento de todos los controles y animaciones, así como la lógica de cálculo (check.mjs).
• Comando: references/verify.md.

Reglas clave

• Hechos: solo escribir afirmaciones y cifras del artículo verificadas en el original. Todas las cifras llevan una etiqueta de artículo/blog/video/cálculo/ejemplo.
• Estructura: título + resumen de una línea → secciones → trampas/malentendidos → fuentes. Los h2 son oraciones de afirmación.
• Dentro de una sección: 1-2 frases sobre qué observar → figura → breve explicación de por qué. Deducciones y excepciones en <details>.
• Ecuaciones: no la deducción completa, sino el rol de cada término y el concepto clave.
• Figuras: solo aquellas con las que el lector pueda comprobar la afirmación directamente. Por defecto, animación de reproducción automática (con botones de reproducir/pausar e ir al inicio).
• Estilo de escritura: 합쇼체 (según el idioma base), máximo 3 oraciones por párrafo, máximo una analogía por sección.
• Diseño: definir uno nuevo para cada página según el tema (prohibido copiar el diseño de páginas existentes). Requisitos fijos: solo modo claro (color-scheme: light), colores gestionados con variables CSS.

Lista de verificación de finalización

• La sección ## Nivel del lector existe en el CLAUDE.md de la carpeta de la página.
• Todos los conceptos marcados como 'No conoce' están explicados en el texto principal.
• Los conceptos marcados como 'Domina a medias' tienen un cuadro de repaso <details>.
• Cada h2 es una oración de afirmación.
• Todas las cifras tienen etiqueta, y las cifras de artículo y blog se verificaron contra el original.
• Cada ecuación explica el rol de cada término.
• Si hay datos, modelo y evaluación, el flujo de limpieza de datos → formato de entrada/salida → procesamiento interno del modelo → salida → pérdida/aprendizaje → métricas de evaluación está acompañado de figuras.
• No hay figuras decorativas; el fenómeno se ve inmediatamente con los valores predeterminados de los controles; hay una guía de una línea debajo de cada figura.
• Si hay fuente de video, existen clips por sección y subtítulos en el idioma de salida (ej.: .ko.vtt).
• Al final, hay lista de fuentes (enlaces al artículo, video, repositorio de código, blog/página web).
• El atributo lang, viewport, <title>, color-scheme: light y los colores se gestionan con variables CSS.
• El diseño y los colores se ajustan a la naturaleza del tema, y no se copió el diseño de páginas existentes.
• check_page.py pasa, todos los controles y animaciones funcionan.
• Si hay lógica de cálculo, node check.mjs pasa.