Communitygithub.com

explicador-html

Muestra a un agente cómo planificar, construir o recortar una 'página explicativa HTML' para que el resultado concreto sea texto o un script utilizable. El procedimiento recorre las páginas explicativas HTML, los archivos de esta habilidad, la apariencia. Úsalo cuando un nuevo encargo requiera este oficio.

¿Qué es explicador-html?

Esta habilidad está diseñada para agentes de IA que trabajan con documentación técnica en HTML, especialmente páginas explicativas que los desarrolladores leen en un navegador y desde las que pueden navegar directamente a VS Code. Su propósito es guiar al agente en la creación, modificación o recorte de dichas páginas, siguiendo un conjunto de reglas visuales y estructurales muy precisas (como el uso de temas oscuros, enlaces tipo 'píldora azul', y diagramas de carril). La habilidad incluye una plantilla HTML (`assets/template.html`), referencias sobre diseño, escritura, diagramas, y diagramas reproducibles. El agente debe decidir qué secciones incluir según el tipo de solicitud (problema, tarea, explicación general, etc.), dibujar únicamente diagramas de carril (normales o reproducibles), enlazar correctamente archivos y secciones, y ejecutar varias comprobaciones antes de dar por terminada la página. Al final, debe proporcionar al usuario dos líneas para pegar en el navegador: la URL `file:///` y la ruta absoluta en disco.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/frhn-xo/html-explainer/tree/HEAD/skills/html-explainer

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Páginas explicativas HTML

El usuario lee estas páginas en un navegador y, con Cmd+clic, navega directamente a VS Code desde ellas. Entienden un flujo a partir de un diagrama de carril mucho más rápido que a partir de párrafos, y quieren que cada página responda a lo que preguntaron y nada más.

Archivos de esta habilidad

  • assets/template.html: el punto de partida de cada página. Cópialo, nunca escribas una página desde cero.
  • references/DESIGN.md: el diseño que sigue cada página, siempre en su forma oscura, con cada enlace como una píldora azul (references/page.md, "La apariencia"). Léelo cuando una página necesite un color o una pieza que la plantilla no tenga.
  • references/page.md: nombre y ubicación del archivo, la barra lateral, enlaces a archivos, la sección de tareas, la sección de páginas enlazadas, páginas maestras y explicativas. Léelo al crear una página o cambiar su estructura.
  • references/writing.md: la sección de problema y cualquier texto. Léelo antes de escribir texto.
  • references/diagrams.md: cómo se ve un diagrama de carril y cómo verificarlo. Léelo antes de dibujar o editar cualquier diagrama.
  • references/playable.md, assets/player.js, assets/player.css: diagramas de carril reproducibles. Léelos cuando el usuario diga "reproducible", o al editar una página que tenga un div.player.

La apariencia

Cada página sigue references/DESIGN.md, siempre en modo oscuro, con cada enlace como una píldora azul para que se destaque como cliqueable: subrayado para un archivo, ↗ para otra página, ninguno para una sección de la misma página (references/page.md, "La apariencia: DESIGN.md, siempre oscuro" y "Tres tipos de enlace"). La plantilla ya hace esto. Cada diagrama se encuentra en un panel que el lector puede redimensionar, hacer zoom y arrastrar (references/diagrams.md, "El bloque de diagrama").

Mantén la página mínima

Una página contiene solo lo que el usuario pidió. Cada sección, tabla o nota extra es algo que necesitan leer para encontrar la respuesta.

  • Secciones: solo las que la solicitud necesita. Un diagrama de carril con un breve párrafo a su alrededor es una sección. Nunca agregues una sección que el usuario no pidió: sin resúmenes, sin inventarios, sin sección de "razones", sin registros de decisiones pasadas.
  • Tablas: solo cuando el usuario pida una. Escribe párrafos y diagramas de carril en su lugar.
  • Debajo de un diagrama: nada. Sin lista de archivos, sin notas, sin línea de "no dibujado". Si se necesita una frase para leer el diagrama, va en el párrafo anterior.

Qué secciones recibe una solicitud

Ajusta la página a la pregunta:

  • "¿Cuál es el problema?", depuración, corrección de un error: la sección de problema primero (references/writing.md), con un diagrama de carril del error (en una página maestra, una reproducible, references/playable.md). Luego cualquier otro diagrama de carril que la explicación necesite.

  • Implementar una funcionalidad o corregir un error, una vez discutidas las tareas: una sección de tarea justo debajo de la sección de problema (references/page.md, "La sección de tarea"). Mientras el usuario todavía está trabajando en el problema, no hay tareas aún, por lo tanto no hay sección de tarea.

  • "¿Cómo funciona esto?", "¿De qué trata este proyecto?": sin sección de problema, sin sección de tarea. Un diagrama de carril del flujo, con párrafos cortos donde ayuden.

  • "¿Cómo construiría algo como esto?": una sección: el diagrama de carril habitual para ello, qué funcionalidades extra podrían añadirse y cómo proceder.

  • Cualquier página enlazada con otras páginas (una maestra y sus explicativas, o páginas que el usuario pida enlazar): una sección Páginas enlazadas al final (references/page.md, "La sección de Páginas enlazadas").

Cualquier otra cosa: responde a la pregunta en las menos secciones que la respondan.

Diagramas: solo carriles

Hay dos tipos de diagrama, y solo dos:

  1. Carril: un diagrama de flujo con una caja por actor o sistema, pasos dentro de la caja que los realiza, flechas que cruzan cajas cuando el trabajo se mueve (references/diagrams.md).
  2. Carril reproducible: el mismo carril con botones Restablecer / Atrás / Siguiente / Reproducir, una flecha por pulsación, y un pie de foto debajo (references/playable.md). "Reproducible", "carril reproducible", "diagrama reproducible" y "reproducible antes/después" significan esto. "Carril" solo significa uno normal.

Cualquier otra solicitud de diagrama ("un diagrama Mermaid", "dibuja el flujo", "un diagrama de esto") recibe un carril.

Flujo de trabajo

  1. ¿Es esto una explicación de una página maestra? Busca en la carpeta del ticket una frase distintiva de la solicitud, incluso cuando el usuario pega solo el texto de un elemento y nunca nombra la maestra. Si coincide, la nueva página es la explicativa de esa maestra: usa el prefijo del nombre de archivo de la maestra y enlaza en ambos sentidos en el mismo cambio (references/page.md).
  2. Crea el archivo (references/page.md, "El archivo"), copiado de assets/template.html. Rellena los marcadores {{…}}, y cambia la clave de localStorage toc-open-CHANGE-ME por una única para la página.
  3. Decide las secciones según "Qué secciones recibe una solicitud", y escribe solo esas.
  4. Dibuja los carriles (references/diagrams.md). Antes de renderizar, enumera cada bucle, rama, ruta de error y retorno anticipado en el código cubierto, y verifica que cada uno está dibujado.
  5. Enlaza cada referencia a archivo con #L<línea>. Verifica que cada ruta existe y que cada línea de destino realmente dice lo que el texto afirma.
  6. Ejecuta las comprobaciones siguientes, luego informa en el chat con el enlace de la página (abajo). Si algo de lo que hace el código queda fuera de un diagrama, dilo en esa respuesta.

Comprobaciones antes de decir que está listo

  • La página tiene solo las secciones que la solicitud necesitaba: sin sección de problema a menos que explique un problema, sin sección de tarea a menos que se hayan discutido tareas, sin tabla a menos que se haya pedido una, nada debajo de un diagrama.
  • Cuando la página explica lo que una persona dijo o quiere, su primera frase dice lo que quiere, en palabras que el usuario usaría (references/writing.md, "Explicar lo que alguien quiso decir").
  • La página mantiene la apariencia de la plantilla: siempre oscura, cada color de references/DESIGN.md, cada enlace como una píldora azul con su marca única, sin tema claro prefers-color-scheme añadido (references/page.md, "La apariencia").
  • Las leyendas nombran significados, no colores ("donde sale mal", nunca "ocre = …"); la página no tiene lista de sus propios colores (references/page.md).
  • Cada diagrama es un carril: la página no tiene sequenceDiagram, stateDiagram, classDiagram o ningún otro tipo de diagrama.
  • Renderiza cada diagrama con mermaid-cli y mira el PNG (references/diagrams.md, "Renderizar para comprobar"). La página debe cargarse sin errores de sintaxis Mermaid.
  • Cada caja que envía, escribe, llama o lee dice hacia o desde dónde en su texto, y su flecha termina en la caja de ese sistema. Cada llamada a otro sistema es una flecha hacia fuera, más una flecha de regreso cuando el siguiente paso usa la respuesta.
  • Carriles de carril: busca en la fuente [" "] y ghost; no debe haber ninguna. En el PNG, ninguna caja de carril es más ancha o alta de lo que sus propios pasos necesitan.
  • Un carril reproducible: recórrelo desde el inicio hasta el final y de vuelta en un navegador.
  • Cada href y data-href de la barra lateral se resuelve a un id en la página, y cada enlace a archivo existe en relación a la página.
  • Una página explicativa: la maestra enlaza a ella dondequiera que discute el tema, y el enlace principal de la explicativa vuelve.
  • Páginas enlazadas: cada página lista a la otra en su sección de Páginas enlazadas, la sección es la última de la página, y cada enlace en ella abre un archivo existente.
  • Después de cambiar el estado de una tarea: una búsqueda lista la clase de casilla de verificación y la etiqueta de cada tarea una al lado de la otra, y todas las tareas hechas se ven igual (references/page.md).
  • Una pestaña del navegador abierta por automatización suele estar en segundo plano (document.visibilityState === "hidden"), por lo que los eventos de desplazamiento no se disparan allí. Prueba el scroll-spy llamando a markActive() después de cada scrollIntoView(), y no concluyas que está roto.

Mencionar una página en el chat

Cada vez que una respuesta del chat mencione una página HTML, da dos líneas que el usuario pueda pegar directamente en la barra de direcciones del navegador, cada una sola en su propia línea:

file:///Users///_/.html

/Users///_/.html

La primera línea es la URL completa file:///, la segunda es la ruta absoluta en disco. Nada más va en cualquiera de las líneas: sin texto, sin comillas invertidas, sin enlace markdown, sin viñeta, sin cita > con bloque. Pon una etiqueta corta en la línea de arriba si es necesario ("Pega esto en tu navegador:"). Añade el #id de una sección a la URL cuando quieras una sección, después de verificar que el id existe. Los archivos de código en el chat mantienen los enlaces relativos habituales.

Por qué: un enlace relativo abre el código fuente HTML en VS Code, y un enlace file:/// abre la página renderizada en el navegador. Una URL enterrada en una frase o envuelta en markdown tiene que ser extraída manualmente.

Skills relacionados