Modern Web Guidance 1.0: instalar en Claude Code, Codex y Cursor

Instala Modern Web Guidance 1.0 como skill del proyecto y verifica una tarea de frontend antes de usarlo en todo el repositorio. Usa legacy-scan para preparar propuestas de modernización sujetas a revisión, no para reescribir código sin supervisión. Define DISABLE_TELEMETRY=1 antes del primer comando cuando no quieras enviar telemetría de uso de Modern Web Guidance.

Qué cambia con Modern Web Guidance 1.0

Modern Web Guidance proporciona a tu agente de programación instrucciones específicas sobre la plataforma web antes de que escriba código. La versión 1.0, publicada el 10 de noviembre de 2026, incluye 203 guías para casos de uso y cubre 250 funciones de la plataforma web. Los equipos de Chrome, Edge, Firefox y MDN mantienen el proyecto junto con la comunidad.

La skill, un conjunto de instrucciones para el agente, le indica que busque las guías pertinentes y obtenga su contenido. Después debe aplicar sus reglas de implementación y alternativas de compatibilidad.

La búsqueda combina un modelo local de embeddings con BM25, un método de clasificación por palabras clave. Según el README oficial del proyecto, esa búsqueda no necesita una API de modelos externa ni una clave de API.

Esto resulta útil cuando el agente conoce una API del navegador, pero omite detalles como el comportamiento de las transiciones o las alternativas de compatibilidad. Sigues siendo responsable de definir los navegadores admitidos, revisar los cambios y ejecutar las pruebas de la aplicación.

Cómo instalarlo en Claude Code, Codex o Cursor

Usa la misma instalación mediante CLI, con alcance de proyecto, para los tres agentes. El código de la instalación invoca Vercel Skills. A fecha de 2026-11-13, usa Node.js 22.20 o posterior para cumplir el requisito actual del instalador Skills. También necesitas npm/npx y permiso para descargar los paquetes necesarios.

Abre Bash en la raíz del proyecto. Desactiva la telemetría de Modern Web Guidance antes de ejecutar el comando oficial de instalación:

export DISABLE_TELEMETRY=1
npx modern-web-guidance@latest install

El instalador interactivo permite elegir los agentes de destino. Selecciona Claude Code, Codex, Cursor o solo los que uses. Para probarlo en un repositorio concreto, conserva el alcance de proyecto, que es el predeterminado del instalador.

Si usas esta instalación mediante CLI, comprueba estos archivos del proyecto y métodos de invocación:

Agente	Archivo de la skill en el proyecto	Invocación explícita
Claude Code	.claude/skills/modern-web-guidance/SKILL.md	Introduce /modern-web-guidance.
Codex	.agents/skills/modern-web-guidance/SKILL.md	Usa /skills o menciona $modern-web-guidance.
Cursor	.agents/skills/modern-web-guidance/SKILL.md	Escribe / en el chat de Agent y selecciona la skill.

Los directorios corresponden a la configuración actual del instalador para cada agente. No son rutas de caché de plugins ni de instalación global.

Inicia una sesión nueva del agente en el mismo repositorio e invoca la skill explícitamente para la primera comprobación. Si no aparece, revisa el agente seleccionado, el alcance de instalación y la ubicación del archivo antes de reinstalarla.

Para actualizar una skill instalada mediante CLI, ejecuta desde el directorio del proyecto:

npx modern-web-guidance@latest update

Revisa los archivos de la skill que hayan cambiado y repite la comprobación de recuperación de guías del siguiente apartado. Estos comandos usan @latest; no des por hecho que una actualización futura seguirá en la versión 1.0.

La instalación desde un catálogo de plugins es otra vía. Mantén su proceso de actualización separado de este procedimiento de CLI. Para conocer el empaquetado y la gestión de plugins de Claude Code, consulta cómo instalar, verificar y eliminar plugins de Claude Code.

Verifica la búsqueda, la recuperación y el uso real por parte del agente

Comprueba tanto la CLI como el uso que hace el agente de sus resultados. Que un comando termine correctamente no demuestra que el agente haya cargado la skill.

Ejecuta en Bash el ejemplo de diálogo documentado:

npx modern-web-guidance@latest search "animate a dialog modal backdrop"
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"

La búsqueda devuelve JSON con identificadores y descripciones de guías. La recuperación devuelve el contenido de la guía seleccionada. Si la salida es grande, la CLI puede mostrar la ruta de un archivo guardado en su lugar. Pide al agente que lea ese archivo completo.

Después invoca la skill instalada y asigna al agente una tarea acotada. El siguiente prompt conserva el framework y la política de navegadores, y exige obtener las guías antes de editar:

Use the modern-web-guidance skill to add an animated modal dialog.
Keep the existing framework and browser support policy.
Retrieve the relevant guidance before editing.
Afterward, report the guide IDs, required fallbacks, and tests run.

Revisa el registro de llamadas a herramientas para confirmar que se realizaron la búsqueda y la recuperación. El informe final debe identificar la guía y explicar qué decisiones de implementación se basaron en ella. Afirmar que el agente «siguió buenas prácticas» no basta como prueba.

La guía de animación de diálogos incluida en la versión publicada ofrece un punto concreto de revisión. Si el código usa la propiedad abreviada transition, coloca transition-behavior: allow-discrete después para evitar que se restablezca su valor. Prueba la entrada y salida, el comportamiento con movimiento reducido y las interacciones existentes del diálogo.

Si el primer comando falla antes de devolver resultados, comprueba primero Node.js y los permisos de descarga de paquetes. Las instrucciones de la skill publicadas distinguen expresamente la descarga del paquete del funcionamiento sin conexión. Autoriza el comando del paquete necesario, no cualquier ejecución mediante npx.

Si los resultados no son pertinentes, prueba una consulta que describa un comportamiento concreto, como «confirmation modal dialog». No recuperes una guía ajena a la tarea solo para que el proceso parezca correcto.

Usa legacy-scan para revisar, no para reescribir automáticamente

Usa legacy-scan para detectar posibles modernizaciones en un repositorio o directorio. Para cambiar un componente concreto, usa la búsqueda y recuperación de guías. Así lo explica la documentación del proceso de modernización.

Ejecuta un análisis con salida legible desde la raíz del proyecto:

npx modern-web-guidance@latest legacy-scan .

Para obtener una salida estructurada que el agente pueda revisar, usa:

npx modern-web-guidance@latest legacy-scan . --json

Obtendrás posibles cambios asociados a las guías pertinentes, no archivos fuente reescritos. El escáner estático no hace llamadas a un modelo de lenguaje. El análisis y las modificaciones posteriores del agente siguen usando su acceso habitual al modelo.

Pide al agente que siga las cuatro etapas documentadas:

1. Analizar el directorio elegido y recopilar los posibles cambios.
2. Verificar cada resultado frente al código que lo rodea y sus reglas keepWhen/dropWhen. Descartar falsos positivos en vez de tratar cada coincidencia como un cambio obligatorio.
3. Informar de los resultados verificados y las modificaciones propuestas. Exigir tu aprobación antes de iniciar la modernización.
4. Aplicar los cambios aprobados siguiendo las guías correspondientes, una vez recuperadas. Ejecutar las pruebas existentes y volver a analizar el código modificado.

Presta especial atención a las alternativas de compatibilidad intencionadas y al código condicionado a comprobaciones de soporte. Una implementación que parece antigua puede seguir siendo necesaria según tu política de navegadores.

El escáner de la versión 1.0 cubre aproximadamente el 20% de las guías: aquellas que tienen reglas deterministas para detectar patrones antiguos. Ese porcentaje corresponde al catálogo de guías, no a tu código. Por tanto, no encontrar resultados no demuestra que el proyecto esté totalmente modernizado, sea accesible o funcione correctamente.

Define la política de navegadores y .mwgrc antes de modernizar

Explicita los requisitos de compatibilidad y deja desactivadas las guías experimentales salvo que el proyecto las necesite. Por defecto, la skill considera que las funciones Baseline Widely available pueden usarse sin alternativas de compatibilidad.

Las instrucciones de configuración de Baseline explican cómo registrar el objetivo del proyecto en AGENTS.md o CLAUDE.md. Usa tu política de soporte real. No la cambies únicamente para aceptar una sustitución propuesta.

El archivo JSON opcional .mwgrc, situado en la raíz del proyecto, controla el acceso a las guías experimentales. Para registrar una política conservadora, integra estos campos en la configuración existente:

{
  "allowOriginTrials": false,
  "allowVolatileFeatures": false
}

Las guías sobre funciones volátiles cubren funciones disponibles en un solo motor de navegador. Incluyen las publicadas en los últimos 3 meses o que todavía se están estabilizando. Estas guías siguen apareciendo en las búsquedas, pero recuperarlas requiere permiso explícito. Las guías de Origin Trial tienen una autorización independiente.

Para permitir las guías de funciones volátiles, ejecuta lo siguiente en tu propio terminal interactivo de Bash:

npx modern-web-guidance@latest set-allow-volatile-features

Para las guías de Origin Trial, usa este comando independiente solo cuando sea necesario:

npx modern-web-guidance@latest set-allow-origin-trials

Los comandos solicitan confirmación y establecen el valor booleano correspondiente en true. Comprueba la ruta de configuración mostrada y la clave modificada. Después vuelve a intentar recuperar la guía.

El rechazo dentro de un agente o de una shell no interactiva es deliberado. La implementación de la autorización exige un terminal interactivo controlado por una persona. No pidas al agente que eluda esa comprobación.

Estos parámetros desbloquean las guías. No activan funciones del navegador, no inscriben tu sitio en un Origin Trial ni amplían tu política de navegadores admitidos.

Controla la telemetría y el coste de contexto

Desactiva la telemetría en el entorno que realmente ejecuta Modern Web Guidance, no solo en otro terminal. La sección de privacidad del proyecto indica que los datos recopilados incluyen instalaciones, nombres de agentes, identificadores de guías recuperadas y consultas generadas por el agente. También indica que no se recopilan los prompts originales del usuario.

Las consultas de búsqueda pueden revelar detalles de la tarea. Añade export DISABLE_TELEMETRY=1 a la configuración de inicio de Bash, como .bashrc, y asegúrate de que el entorno de comandos del agente herede la variable. Cuando sea necesario, reinicia el agente o IDE que ya esté abierto con el entorno actualizado.

En el entorno de Bash usado para las llamadas a herramientas, esta comprobación confirma el valor sin mostrarlo:

test "${DISABLE_TELEMETRY:-}" = 1

El código de salida 0 confirma que la variable vale 1 en ese entorno. No es una auditoría del tráfico de red. Tampoco permite determinar la configuración de telemetría del proveedor del agente ni de otras herramientas.

Que la búsqueda funcione sin conexión tampoco significa que todo el proceso sea local. La descarga de paquetes necesita acceso a la red. La telemetría de Modern Web Guidance permanece activada salvo que la desactives.

Para calcular el contexto, el README anuncia aproximadamente 205 tokens para modern-web-guidance y 175 tokens para chrome-extensions. Estas cifras no limitan el consumo de una tarea completa del agente. Las guías recuperadas añaden contenido a la ventana de contexto, y las verificaciones y modificaciones requieren más trabajo del agente.

Mide el uso real en tareas representativas. No calcules el ahorro solo a partir del tamaño anunciado de la skill.

Usa las mejoras de la evaluación como motivo para hacer tu propia prueba

Los resultados de Google justifican probar la skill, pero no garantizan una tasa de éxito universal ni un ahorro de tokens. La instantánea del README oficial, fechada el 2026-11-08, muestra:

Agente y etiqueta del modelo	Tareas / aserciones	Sin guías	Con guías	Mejora
claude_code / opus-5-5	215 / 1801	57%	88%	31 puntos porcentuales
codex_cli / gpt-6.1-sol	215 / 1795	54%	82%	28 puntos porcentuales
antigravity_cli / gemini-4-argon	214 / 1673	58%	94%	36 puntos porcentuales

Son tasas de aserciones superadas, no porcentajes de proyectos de producción completados correctamente. La cantidad de tareas y aserciones también cambia entre filas. No interpretes la tabla como una clasificación controlada de modelos ante una carga de trabajo idéntica.

La metodología del panel de evaluación define la tasa de éxito como comprobaciones superadas divididas entre comprobaciones ejecutadas. Las ejecuciones que fallan o agotan el tiempo antes de la evaluación se excluyen junto con su ejecución emparejada.

Google desarrolló la evaluación en torno a sus guías. Su explicación de los errores habituales de los agentes describe cómo se comparan los resultados con las expectativas definidas en cada guía. Son evaluaciones del proveedor de la herramienta, no una validación independiente de la calidad de tu aplicación.

Antes de adoptarla, compara una tarea representativa sobre un componente con y sin guías. Mantén fijos el modelo, el prompt y la política de navegadores. Revisa el comportamiento pertinente del navegador, las pruebas de regresión, el tiempo invertido y el uso real.

Para decidir por costes, considera el coste por tarea de programación completada, no solo el precio de los tokens. Conserva Modern Web Guidance cuando mejore las comprobaciones importantes de tu repositorio sin añadir costes de revisión o uso inaceptables.