Vista Previa: Página HTML con Comentarios Seleccionables
Convierte cualquier plan, propuesta, borrador o texto final en una página HTML donde se puede seleccionar texto → dejar comentarios, y se abre en el ordenador del usuario para que él (o su cliente) la revise. Al terminar, pulsa "Copiar todo" y los comentarios y casillas marcadas se convierten en un markdown que se puede pegar de vuelta en la conversación para hacer los cambios.
Dónde está este skill
La carpeta donde se encuentra este archivo es la carpeta del skill (en adelante $SKILL_DIR). Antes de ejecutar cualquier comando, establécela:
SKILL_DIR="${CLAUDE_SKILL_DIR:-$HOME/.claude/skills/preview}"
[ -f "$SKILL_DIR/scripts/md-to-preview.py" ] || SKILL_DIR="$(cd "$(dirname "$(find "$HOME/.claude/skills" .claude/skills -path '*/preview/scripts/md-to-preview.py' 2>/dev/null | head -1)")/.." && pwd)"
echo "$SKILL_DIR"
- Solo necesita Python 3.9 o superior, todo con la biblioteca estándar, sin pip ni instalar nada.
- En macOS usa
python3; en Windows, si no existe el comandopython3, usapythonopy. - Si no se encuentra la carpeta del skill, detente e informa al usuario que debe confirmar que la carpeta
previewestá en~/.claude/skills/y que no implemente su propio sistema de comentarios.
| Archivo | Propósito |
|---|---|
scripts/md-to-preview.py | Generador principal: convierte md en página de vista previa |
scripts/convert/inject.py | HTML ya maquetado, solo añade la funcionalidad de comentarios |
scripts/convert/visuals.py, flow.py, tables.py | Componentes visuales, diagramas de flujo, conversión de tablas (el generador los llama automáticamente) |
assets/preview-comment-overlay.html | Interfaz de comentarios por selección de texto |
assets/preview-tokens.css | Colores, fuentes, espaciado; para cambiar la apariencia, edita aquí |
assets/fonts/ | Fuentes incluidas: Noto Sans TC, Geist, Geist Mono (licencia SIL OFL) |
assets/example.md | Ejemplo completo: una propuesta ficticia de proyecto que usa todos los componentes |
Regla 1: Los comentarios siempre son por selección de texto
Cuando el usuario dice "Añadir comentarios" o "Una versión con comentarios", se refiere a poder seleccionar cualquier texto → dejar un comentario, como en Google Docs, no a poner un campo de entrada al lado de cada párrafo. La interfaz de comentarios de este skill es exactamente esa: seleccionar texto, y se usa directamente, sin hacer nada más.
Regla 2: Primero reescribe, luego genera la página
Primero identifica el tipo de página
| Tipo | Ejemplo | Cómo se maneja |
|---|---|---|
| Explicativo | Planes, propuestas, informes, comparativas, páginas para que tomen una decisión | Reescribe siguiendo las pautas de abajo para que sea legible, luego genera la página. No metas el borrador de trabajo directamente en el generador |
| Revisión de texto original | Contratos, textos finales, transcripciones, textos dados por el cliente | No toques ni una palabra del contenido. Genera la página con --no-lint. Como mucho, añade un > [!Conclusión] al principio indicando qué hay que revisar en esta página |
Formato para contenido explicativo
- Resume en la primera pantalla: al principio, usa
> [!Conclusión]para una frase de conclusión, y luego> [!Tú decides]para listar lo que el lector debe hacer. El contexto va después; el lector puede tomar decisiones sin desplazarse hacia abajo. - Cada cosa se dice una sola vez: lo dicho en el cuadro de conclusión no se repite en el texto; lo dicho en una tabla o gráfico no se repite en un párrafo. No escribas secciones de "Resumen".
- Lenguaje claro: usa las palabras que el lector usa habitualmente. La primera vez que aparezca un término técnico, usa una analogía o un
> [!En lenguaje claro]para explicarlo. - Si se puede dibujar, no se escribe: primero pregúntate "¿Qué relación describe este párrafo?" y elige el componente según la tabla. Como máximo tres líneas de texto por párrafo; cada sección
##debe tener al menos un componente visual o una tabla. - Breve: una idea por frase. Elimina muletillas como "en otras palabras", "es decir", "cabe destacar".
- Lo que se elimina es la repetición, no la información: los números, fechas, nombres y consecuencias no se pueden omitir ni modificar.
Referencia rápida de componentes visuales
Escribe unas pocas líneas de sintaxis breve, y el generador dibujará el gráfico. Separa con ｜ (pleca ancha) y las flechas con →. Consulta assets/example.md para la sintaxis completa.
| ¿De qué trata este párrafo? | Componente | Sintaxis |
|---|---|---|
| Antes vs después, ahora vs después del cambio | Comparativa | ```comparativa: primera línea Ahora → Después del cambio, luego cada línea ítem｜Antes → Después |
| Cómo está compuesto el sistema, cómo fluyen los datos | Arquitectura | ```arquitectura: cada línea un nivel nivel｜caja, caja; dentro del nivel usa A → B; entre niveles puedes poner una línea ↓ explicación |
| Cuándo ocurre qué | Línea de tiempo | ```línea_de_tiempo: cada línea tiempo｜título｜descripción; ✅ al inicio = completado, 👉 = ahora |
| Secuencia, pasos, cadena de causa-efecto | Pasos | ```pasos: cada línea título｜descripción, se numera automáticamente; hasta 4 pasos se muestran en horizontal, 5 o más en vertical |
| Varios números clave | Números | ```números: cada línea número unidad｜etiqueta｜nota pequeña; deja un espacio entre el número y la unidad para que se vea más pequeño |
| Varias opciones, quién hace qué, elementos paralelos | Tarjetas | ```tarjetas (también opciones, distribución): cada línea título｜una línea｜otra línea; ★ al inicio marca la opción recomendada |
| Comparación en varias columnas | Tabla | Tabla Markdown normal. Cuando el encabezado tiene a la vez "Ahora/Antes" y "Después/Nuevo/Recomendado", la columna antigua se vuelve gris automáticamente y la nueva, verde claro |
| Flujo con ramificaciones | Diagrama de flujo | Diagramas ASCII o mermaid (graph/flowchart con TD, LR); si no se puede convertir bien, se deja el original |
| Conclusión, decisión del lector, aviso, riesgo | Cuadro destacado | > [!Conclusión] título, desde la línea siguiente > contenido. Válidos: Conclusión, Tú decides, Aviso, Riesgo, Completado, En lenguaje claro, Explicación |
| Estado | Etiqueta de color | En línea: {verde:Completado} {amarillo:Esperándote} {rojo:Bloqueado} {azul:En progreso} {gris:No se hará} |
| Palabras clave en una frase | Resaltado | ==palabra clave==, como máximo uno por párrafo |
- Los colores tienen significado fijo: azul = conclusión e información, verde = completado y después del cambio, amarillo = aviso y espera, rojo = riesgo y bloqueado. "Tú decides" solo se usa una vez en toda la página.
- Si la sintaxis es incorrecta, no rompe la página: se muestra como un bloque de código gris. Al terminar, revisa si hay algo que debería ser un gráfico pero sigue siendo gris.
- Si hay secuencia o causa-efecto, usa pasos o línea de tiempo; si los elementos son independientes, usa tarjetas.
- El texto dentro de los gráficos es texto real, se puede seleccionar para comentar igual.
Revisión de maquetación
Al generar la página, se imprime automáticamente una "Revisión de maquetación": si falta el cuadro de conclusión al inicio, si un párrafo es demasiado largo, si hay pocos componentes visuales, palabras repetitivas, guiones largos, o la misma información dicha dos veces. Si hay advertencias, corrige el md y vuelve a ejecutar hasta que aparezca "Revisión de maquetación: superada". Para texto original (revisiones de textos), usa --no-lint.
Ahorro de recursos
- Los gráficos siempre se definen con sintaxis breve, nunca se escribe HTML o SVG a mano, ni se generan imágenes aparte.
- Para cambiar el contenido, modifica el md y vuelve a ejecutar el generador; no toques directamente el HTML de salida.
- Las listas muy largas se pueden plegar con
--fold "3".
Regla 3: Siempre usa el generador
- La página de vista previa siempre se genera con
scripts/md-to-preview.py(fuente md) oscripts/convert/inject.py(HTML ya maquetado). No escribas CSS a mano ni implementes tu propio sistema de comentarios. - Para cambiar la apariencia, edita
assets/preview-tokens.cssy vuelve a ejecutar el generador.
Flujo de ejecución
Paso 1: Identificar la fuente y la identidad
Dedúcelo de la conversación; si no queda claro, pregunta:
- ¿Qué se va a previsualizar? (contenido recién escrito en la conversación, archivo proporcionado por el usuario)
- ¿Quién va a comentar? La identidad por defecto es
yo,visitante. Si es para que lo vea un cliente, cámbialo a por ejemplocliente,yo(el primero es la identidad por defecto).
Si la fuente es contenido de la conversación, guárdalo primero como archivo md en la carpeta de trabajo actual del usuario (si no existe, en una carpeta VistaPrevia en el escritorio), con un nombre en chino que describa el contenido, por ejemplo Propuesta-ClienteEjemplo.md.
Paso 2: Generar la página
Si la fuente es md (lo más común):
python3 "$SKILL_DIR/scripts/md-to-preview.py" "<fuente>.md" "<salida>.html" \
--identities "yo,visitante" --badges "Borrador,2026-10-19"
| Parámetro | Función |
|---|---|
--identities | Lista de identidades separadas por comas; la primera es la predeterminada |
--badges | Etiquetas grises pequeñas debajo del título, separadas por comas; si no se proporciona, no se muestran |
--key | Nombre usado para almacenar los comentarios en el navegador; debe ser único por página; si no se proporciona, se usa el nombre del archivo de salida |
--title | Título del documento; si no se proporciona, se usa el primer título # del md |
--fold "3,4" | Pliega los títulos de los niveles especificados en secciones expandibles; útil para páginas largas |
--no-lint | Omite la revisión de maquetación (para contratos, textos finales, etc.) |
--no-overlay | Versión limpia sin funcionalidad de comentarios |
--icon | Carácter o emoji para el icono de la pestaña; si no se proporciona, se usa el primer carácter del título |
--fonts copy／link／none | Manejo de fuentes; por defecto copy |
Fuentes: por defecto, se crea una carpeta preview-fonts/ junto al HTML de salida. 🚨 Si vas a enviar la página a alguien, empaqueta el HTML y la carpeta preview-fonts/ juntos; si envías solo el HTML, se usarán las fuentes del sistema (funciona, pero se ve peor).
Imágenes: las líneas independientes del md con  se convierten en imágenes con pie de foto; la ruta es relativa al HTML de salida.
Si la fuente ya es HTML maquetado (por ejemplo, una propuesta hecha a mano): no se toca el diseño, solo se añade la funcionalidad de comentarios.
python3 "$SKILL_DIR/scripts/convert/inject.py" "<página>.html" -o "<página>-con-comentarios.html" --identities "yo,cliente"
-odebe ser un archivo nuevo; la herramienta no sobrescribe la fuente.- Si la página ya tiene comentarios y quieres actualizarlos, añade
--replace.
Paso 3: Abrir para que el usuario lo vea
Abre la página con el navegador predeterminado:
# macOS
open "<salida>.html"
# Windows (si el terminal de Claude es Git Bash, usa start; en PowerShell, usa Start-Process "<salida>.html")
start "" "<salida>.html"
# Linux
xdg-open "<salida>.html"
Informa al usuario de tres cosas:
- Selecciona cualquier texto y aparecerá "Añadir comentario".
- Las casillas se pueden marcar haciendo clic directamente.
- Cuando termines, pulsa el botón "Copiar todo" en la esquina superior derecha y pega el contenido de vuelta en la conversación.
Paso 4 (opcional): Enviar al cliente para comentarios
- Comprime el HTML y la carpeta
preview-fonts/en un zip y envíalo al cliente. Pídele que descomprima y haga doble clic en el HTML. - Configura las identidades según el rol del cliente, por ejemplo
--identities "cliente,yo". - Los comentarios se guardan en el navegador del cliente; no se sincronizan automáticamente. Pídele que al terminar pulse "Copiar todo" y te envíe el texto por email o mensaje.
Marcado de casillas de verificación
Cuando el usuario tiene que decidir elemento por elemento de una lista, y las opciones son fijas, hazlo con casillas de verificación, no le pidas que escriba respuestas. Por ejemplo: funciones que se van a implementar o no, selección de recursos, lista de comprobación previa al lanzamiento. Si solo hay una o dos opciones, o se necesita una justificación, haz preguntas directas o usa comentarios por selección de texto.
Cómo escribirlo
En el md, usa el formato de lista de tareas; el generador las convertirá en casillas cliqueables:
### Imprescindible
- [x] Formulario de pedidos (el cliente lo rellena y se guarda automáticamente en la base de datos)
- [ ] Calendario de turnos (cada empleado solo ve su propio turno)
- [ ]= no marcado,- [x]= marcado por defecto.- Cada grupo debe tener su propio título (
##o###): al exportar, se agrupan usando "el título anterior más cercano". - Cada elemento debe tener un nombre y una breve descripción que se entienda por sí solo; no escribas solo "sí" o "no".
- No uses el mismo texto de opción dos veces bajo el mismo título.
Qué ve el usuario
- El estado de las casillas se guarda en su navegador; al recargar la página no se pierde. Al pulsar "Vaciar" se borran solo los comentarios, no las casillas.
- Al pulsar "Copiar todo", al principio aparece un bloque:
## Resultado de casillas (marcadas 2/5)
### Confirmación de alcance › Imprescindible
- [x] Formulario de pedidos (el cliente lo rellena y se guarda automáticamente en la base de datos)
- [ ] Calendario de turnos (cada empleado solo ve su propio turno)
Al recibir el resultado de las casillas
- Guarda el resultado de las casillas tal cual en un archivo; después trabaja sobre esa copia, no de memoria.
- Los elementos no marcados significa que no se hacen o se mantienen como están; no añadas tu propio criterio.
- Si dentro del mismo grupo hay elementos marcados que son contradictorios, pregunta al usuario.
- Si afecta a acciones externas (enviar correos, borrar archivos, publicar), primero muestra la lista final y solo actúa cuando el usuario diga "adelante".
Cómo aplicar el "Resumen de comentarios" cuando se recibe
Cuando el usuario pulsa "Copiar todo" y pega el contenido de vuelta, este tiene el siguiente formato: cada comentario incluye el texto original seleccionado (cita), la ubicación (título del párrafo), contexto y el contenido del comentario.
Interpretación uno por uno
| Aspecto del comentario | Interpretación |
|---|---|
| Solo un texto nuevo, sin verbo | Reemplazar: cambiar la cita por el texto del comentario |
| "Eliminar", "Quitar" | Eliminar el párrafo de la cita (solo el ámbito de la cita) |
| "Añadir", "Agregar", "Incluir otro debajo" | Añadir: poner contenido cerca de la cita |
| Descriptivo ("Se podría...", "Me gustaría...") | Modificar según la petición |
| Vago, admite dos interpretaciones | Elegir la opción que implique el menor cambio; al informar, deja claro qué opción elegiste |
- Usa primero "ubicación" y "contexto" para localizar el punto exacto antes de modificar. Si el mismo texto aparece varias veces en la página, usa el contexto para asegurarte de que solo afectas a una.
- Es posible que los comentarios de esta ronda repitan los de la anterior; primero comprueba cuáles ya se han aplicado.
Aplicar, regenerar, y volver a abrir
- Modifica el md original y luego vuelve a ejecutar el generador con el mismo comando y el mismo
--key; no modifiques directamente el HTML de salida (se sobrescribiría al regenerar). Con la misma clave, los comentarios antiguos se conservan. - Vuelve a abrir la página para que el usuario la vea.
- Informa: lista uno por uno "comentario X → qué se ha cambiado"; si era ambiguo, indica tu elección.
Notas técnicas (para Claude, no se las digas al usuario)
- El anclaje de comentarios usa "texto seleccionado + contexto"; si el contenido cambia ligeramente, se puede reubicar automáticamente. Si no se encuentra, se marca como "El texto original ha cambiado".
- El resaltado usa la API CSS Custom Highlight del navegador, sin modificar la estructura de la página. Chrome, Edge y Safari modernos lo soportan; en navegadores que no lo soporten, simplemente no se verá el resaltado amarillo, pero los comentarios del panel lateral funcionan igual.
- Los comentarios y las casillas se guardan en localStorage del navegador, cada página con su propio
--key; de lo contrario, los comentarios de diferentes páginas se mezclarían. - La interfaz de comentarios expone
window.PreviewCommentsdespués de cargarse:.refresh()reubica los resaltados,.data()devuelve todos los comentarios,.exportMd()devuelve el markdown exportado. - El z-index de las ventanas emergentes de la página debe ser inferior a 10400 para que los botones de comentarios no queden ocultos.