web-to-markdown

Visión general de la skill web-to-markdown

web-to-markdown es una skill de conversión de formato muy específica para transformar páginas web en vivo en Markdown limpio mediante un CLI local web2md. Su valor no está en “resumir una página”, sino en “renderizar la página real en un navegador de verdad, extraer el cuerpo principal del artículo o documento y convertir ese resultado en Markdown portable”. Por eso, encaja especialmente bien para usuarios que trabajan con páginas renderizadas con JavaScript, sitios de documentación, entradas de blog, flujos protegidos que requieren renderizado interactivo o tareas de archivado en las que una simple petición HTTP no basta.

Para quién encaja mejor web-to-markdown

Esta skill web-to-markdown es ideal para usuarios que necesitan:

• convertir una o varias URLs en Markdown legible
• manejar páginas que dependen de JavaScript del lado del cliente
• guardar contenido en archivos para analizarlo o reutilizarlo después
• extraer contenido tipo artículo en lugar de raspar todos los elementos de la página

Si tu objetivo real es “obtener el contenido principal de una página a la que ya puedo acceder en un navegador”, esta skill encaja mejor que un prompt genérico.

Qué hace diferente a web-to-markdown

El diferenciador clave es su pipeline:

• Puppeteer mediante un navegador local de la familia Chromium
• Readability para extraer el contenido principal
• Turndown para convertir a Markdown

Esa combinación está pensada para contenido ya renderizado, no para HTML en bruto. En la práctica, eso significa que la skill web-to-markdown puede funcionar en páginas donde las herramientas basadas en fetch fallan o devuelven contenido incompleto.

La condición estricta de activación importa

Esta skill tiene una restricción poco habitual, pero importante: solo debe usarse cuando el usuario la solicite explícitamente por nombre, con una redacción como use the skill web-to-markdown. Si falta ese disparador explícito, la skill no debe aplicarse. Para quien consulta el directorio, esto significa que adoptarla es sencillo, pero invocarla con disciplina sí importa.

El trabajo real que resuelve

La mayoría de los usuarios no buscan “una skill de automatización de navegador”. Buscan uno de estos resultados:

• “Convierte este artículo en Markdown para poder guardarlo.”
• “Convierte esta página de documentación, aunque se renderice del lado del cliente.”
• “Procesa un lote de URLs y conviértelas en archivos .md.”
• “Abre la página en un navegador real para pasar un login o una verificación y luego guarda el contenido.”

Ese es el caso de uso real para el que web-to-markdown está optimizada.

Cuándo no conviene elegir esta skill

Omite web-to-markdown si:

• solo necesitas un resumen rápido, no una salida en Markdown
• una petición HTTP simple ya te devuelve el contenido de forma limpia
• necesitas un crawler o scraper completo de un sitio
• quieres automatización basada en Playwright; esta skill usa explícitamente web2md, no otros stacks de navegador

Cómo usar la skill web-to-markdown

Entiende el contexto de instalación antes del primer uso

Conviene tratar web-to-markdown como dos dependencias:

1. la propia skill en tu entorno de agente
2. un CLI local web2md operativo y un navegador disponible de la familia Chromium

Una ruta práctica de instalación de la skill es:

npx skills add softaworks/agent-toolkit --skill web-to-markdown

El repositorio está en:
https://github.com/softaworks/agent-toolkit/tree/main/skills/web-to-markdown

No basta con añadir la skill si tu equipo no puede ejecutar web2md o lanzar Chrome/Chromium/Brave/Edge. Ese requisito de navegador local es el principal bloqueo de adopción y conviene validarlo cuanto antes.

Lee primero estos archivos

Esta skill es pequeña, así que el mejor orden de lectura es:

1. skills/web-to-markdown/SKILL.md
2. skills/web-to-markdown/README.md

SKILL.md te da la regla de activación, las entradas necesarias y la forma general del flujo. README.md es donde confirmas los casos de uso previstos, como páginas renderizadas con JS, modo interactivo y conversión por lotes.

Qué entradas necesita web-to-markdown

Para usar web-to-markdown de forma fiable, proporciona:

• una url o una lista de URLs
• modo de salida:
  • imprimir en stdout con --print
  • escribir en un archivo con --out ./file.md
  • escribir en un directorio con --out ./some-dir/
• controles opcionales del navegador cuando hagan falta:
  • --chrome-path <path> si falla la detección del navegador
  • --interactive para muros de login, pantallas de consentimiento o verificación humana

Si no especificas el comportamiento de salida, el agente tiene que adivinar. Es una fricción innecesaria y suele ser de lo más fácil de dejar explícito.

El requisito exacto de invocación

Esta skill web-to-markdown solo debe activarse cuando el usuario escriba explícitamente algo como:

• use the skill web-to-markdown ...
• use a skill web-to-markdown ...

Si estás probando la skill, di el nombre directamente. No es una simple convención del repositorio; es parte central de la lógica de ejecución.

Cómo convertir una petición vaga en un prompt sólido

Petición débil:

• convert this page

Petición sólida:

• use the skill web-to-markdown to convert https://example.com/article to Markdown and save it to ./notes/article.md

Aún mejor:

• use the skill web-to-markdown to convert these 5 docs URLs to Markdown, save them in ./docs-md/, and use interactive mode if a consent screen appears

Los buenos prompts reducen fallos porque le indican a la skill:

• qué página o páginas debe procesar
• dónde debe guardar la salida
• si puede hacer falta interacción en el navegador
• si se trata de una tarea puntual o de un lote

Patrones de comando prácticos que conviene pedir

Algunos patrones útiles de uso de web-to-markdown son:

• una sola página al terminal: --print
• una sola página a archivo: --out ./page.md
• muchas páginas a una carpeta: --out ./pages/
• página difícil con navegador visible: --interactive
• ruta explícita al binario del navegador: --chrome-path <path>

La guía del repositorio hace que estos patrones sean más valiosos que peticiones abiertas como “scrape this site”, que son más amplias que el diseño de la skill.

Mejor flujo de trabajo para una sola página

Un flujo con alta probabilidad de éxito sería:

1. confirmar que el usuario invocó explícitamente web-to-markdown
2. recoger la URL
3. decidir si la salida debe imprimirse o guardarse
4. usar --interactive solo en páginas que necesiten ayuda humana
5. revisar el resultado en Markdown para detectar secciones faltantes o ruido de navegación
6. volver a ejecutar con mejores ajustes del navegador si la extracción quedó incompleta

Esto suele ser más rápido que intentar sobrediseñar el prompt desde el principio.

Mejor flujo de trabajo para varias URLs

Para trabajo por lotes:

1. pasa a la skill una lista de URLs
2. elige un directorio de salida
3. asume que, al guardar en una carpeta, los nombres de archivo se derivarán de los títulos de las páginas
4. revisa algunas salidas al azar antes de lanzar un lote grande

La principal razón para trabajar por lotes es la consistencia. El principal riesgo es asumir que todas las plantillas de páginas de un sitio se extraerán igual de bien.

Bloqueos habituales de configuración local

La mayoría de las instalaciones fallidas de web-to-markdown no se deben al prompt. Se deben al entorno local:

• web2md no está instalado o no está en PATH
• no hay ningún navegador compatible disponible localmente
• la autodetección del navegador falla y obliga a usar --chrome-path
• la página necesita un navegador visible e interacción humana

Si quieres una prueba rápida de adopción, prueba con un artículo público y con una página cargada de JS antes de usar la skill en flujos de producción.

Qué calidad de salida esperar

web-to-markdown apunta a generar Markdown limpio del contenido principal, no una copia píxel a píxel de la página original. Eso implica que:

• el cuerpo de artículos y documentación suele salir bien
• encabezados, pies, anuncios y elementos de interfaz de la página normalmente pierden protagonismo
• widgets poco comunes, app shells y herramientas embebidas pueden no convertirse de forma limpia

Esa compensación suele ser deseable para archivado y análisis, pero conviene tenerla clara antes de instalar.

Preguntas frecuentes sobre la skill web-to-markdown

¿web-to-markdown es mejor que un prompt normal?

Sí, cuando la necesidad real es convertir una página ya renderizada. Un prompt genérico puede hablar sobre una URL, pero no abre por sí mismo un navegador, espera a que cargue JavaScript, extrae el cuerpo legible y produce Markdown. Esta skill web-to-markdown resulta útil precisamente porque operacionaliza ese flujo.

¿web-to-markdown es buena para principiantes?

Sí, si tu tarea es simple: una URL, un archivo de salida, una página directa. El principal reto para principiantes es la configuración local, no el diseño de la skill. Si puedes ejecutar un CLI local de automatización de navegador, la skill es accesible.

¿web-to-markdown maneja páginas con mucho JavaScript?

Ese es uno de sus motivos principales de existir. Usa un navegador local real a través de Puppeteer, por lo que se adapta mejor a páginas renderizadas con JS que los enfoques basados en obtención de HTML en bruto.

¿web-to-markdown puede superar pantallas de login o verificación?

A veces, con --interactive. El repositorio admite explícitamente un modo en el que Chrome se muestra y se pausa para que el usuario complete los pasos humanos necesarios. Es una ventaja práctica para páginas protegidas o semiprotegidas.

¿Cuándo no debería usar la skill web-to-markdown?

No la uses cuando:

• el usuario no haya solicitado explícitamente web-to-markdown
• una simple carga de página ya resuelva la tarea
• necesites scraping estructurado de muchos componentes de una página
• quieras una ruta de conversión sin navegador

La skill es especializada, y esa especialización es una fortaleza, no una debilidad.

¿Funciona con cualquier navegador?

El encaje documentado es con navegadores de la familia Chromium, como Chrome, Chromium, Brave o Edge, mediante puppeteer-core. Si falla la autodetección, tendrás que indicar la ruta manualmente.

¿Esto sirve solo para artículos?

No. Los artículos son el caso más sencillo, pero la skill web-to-markdown también puede servir para páginas de documentación y otras páginas con mucho contenido en las que “extraer el cuerpo principal” es el modelo de salida adecuado. Encaja peor en dashboards o aplicaciones muy interactivas.

Cómo mejorar el uso de la skill web-to-markdown

Dale a web-to-markdown instrucciones de salida explícitas

Una petición mejor no es solo “convert this URL”, sino:

• print it
• save it to ./tmp/page.md
• save all results under ./exports/

Esto elimina ambigüedad y hace más probable que la primera ejecución encaje con tu flujo de trabajo.

Usa el modo interactivo solo cuando la página lo necesite

--interactive es útil para barreras de consentimiento, flujos de login y prompts de verificación, pero es más lento y menos automatizable. Evítalo en páginas públicas rutinarias. En páginas bloqueadas, úsalo pronto en lugar de reintentar a ciegas.

Prueba pronto la detección del navegador

Si la primera ejecución no logra abrir un navegador, no sigas cambiando el prompt. Corrige el contexto de ejecución:

• confirma que existe un navegador de la familia Chromium
• proporciona --chrome-path <path> cuando sea necesario

Para muchos usuarios, este es el consejo de instalación más importante de web-to-markdown.

Elige páginas representativas antes de un despliegue grande

Antes de convertir cientos de URLs, prueba:

• un artículo sencillo
• una página renderizada con JS
• una página con fricción por consentimiento o login

Esto te dirá si la skill encaja con la mezcla real de páginas de tu sitio, no solo con casos ideales.

Refuerza los prompts con restricciones específicas de la página

Si sabes que una página es complicada, dilo:

• use the skill web-to-markdown on this docs page; it renders client-side, save to ./docs/intro.md
• use the skill web-to-markdown on this member page with interactive mode because I need to pass a verification screen first

Ese contexto extra cambia más la calidad de la ejecución que añadir redacción genérica.

Valida el primer resultado en Markdown y luego itera

Después de la primera salida, comprueba:

• ¿se capturó el contenido principal?
• ¿la salida incluye demasiada navegación o boilerplate?
• ¿la página quedó solo parcialmente renderizada?
• ¿el comportamiento de nombres de archivo o carpetas coincidió con lo esperado?

Luego vuelve a ejecutar con mejores controles. web-to-markdown suele mejorar con un reintento concreto y dirigido, no con prompts largos y especulativos.

Conoce los principales modos de fallo

Los fallos más habituales son:

• no hay frase de activación explícita, así que la skill no debería ejecutarse
• problemas al lanzar el navegador local
• páginas que requieren interacción visible
• páginas cuyo “contenido principal” es ambiguo para Readability
• usuarios que esperan scraping de un sitio completo en lugar de conversión de páginas

Reconocer esto pronto te ayuda a decidir si seguir con web-to-markdown o cambiar de herramienta.

Usa web-to-markdown para el estándar de salida adecuado

Obtendrás los mejores resultados cuando tu criterio de éxito sea:

• Markdown limpio y legible
• prioridad del contenido principal frente al chrome de la página
• salida portable para notas, archivos, análisis o procesamiento posterior con IA

Si tu criterio de éxito es “preservar cada detalle del diseño”, esta skill no es la herramienta correcta. Ajustar tus expectativas a su diseño es la forma más rápida de mejorar los resultados.