Crear un repositorio de habilidades de agentes de IA que revisan la calidad de sitios web

## Dividir el repositorio en una habilidad por cada tema de calidad web Trata el repositorio como una colección de capacidades de agente autónomas, no como un único archivo de instrucciones monolítico. Separa las auditorías amplias de las habilidades específicas de rendimiento, accesibilidad, capacidad de descubrimiento, calidad general y métricas de experiencia de usuario, para que el agente cargue únicamente la capacidad necesaria para la tarea. Conserva en la raíz la documentación de todo el repositorio, las reglas de contribución, la información de licencia y las directrices para agentes. Cada directorio de habilidad es responsable de su archivo principal de instrucciones, sus scripts de automatización y sus referencias detalladas. No ocultes directrices para usuarios, auxiliares ejecutables ni material de origen en directorios que no estén relacionados. Antes de modificar una habilidad, identifica su contrato de activación, los archivos que controla, sus dependencias, la ruta de validación y su relación con otras habilidades. ## Nombrar carpetas y archivos y completar la cabecera de SKILL.md Proporciona a cada habilidad un archivo `SKILL.md` con frontmatter de YAML válido que contenga: - un `name` en kebab-case; - un `description` de una frase que indique cuándo usar la habilidad e incluya expresiones de activación realistas; - metadatos de licencia cuando sean obligatorios; - metadatos estables de autor y versión cuando el repositorio los registre. Aplica de forma coherente las convenciones de nombres exactas: - los directorios de habilidades usan kebab-case; - el archivo principal de instrucciones se llama exactamente `SKILL.md`; - los scripts usan nombres en kebab-case y una extensión ejecutable adecuada; - los archivos de referencia siguen la convención de mayúsculas documentada por el repositorio. Mantén el paquete autocontenido y asegúrate de que todas las rutas mencionadas en la habilidad se resuelvan dentro de la estructura de repositorio compatible. ## Mantener SKILL.md por debajo de 500 líneas y pasar los detalles a referencias Mantén la habilidad principal por debajo de 500 líneas. Coloca en `SKILL.md` la activación, el flujo de trabajo central, las restricciones críticas y la navegación; traslada a las referencias las explicaciones detalladas, los ejemplos extensos y el material especializado. Redacta directrices específicas y ejecutables. Cada una debe incluir un título breve, una instrucción directa y cualquier valor o umbral necesario para aplicarla. Da prioridad a las instrucciones que expliquen qué inspeccionar, qué decisión tomar y qué evidencia demuestra la finalización. Usa scripts para el trabajo determinista o repetitivo cuando su salida consumiría de otro modo el contexto de razonamiento. No dupliques el mismo procedimiento entre la habilidad principal y varias referencias. ## Mostrar código de antes y después y tablas de umbrales buenos y malos Muestra el patrón problemático y el corregido siempre que una directriz regule un comportamiento ejecutable. Mantén los ejemplos lo bastante pequeños para entenderlos de forma aislada y verifica que funcionen realmente. Por ejemplo, una directriz sobre la estabilidad de las imágenes debe contrastar una imagen con información insuficiente con otra que declare sus dimensiones y metadatos de carga útiles: Problema: un elemento de imagen que solo contiene `src="hero.jpg"`. Mejora: el mismo elemento con `width="1200"`, `height="600"`, `alt="Hero image"` y `loading="lazy"`. Presenta los umbrales de calidad comparables en una tabla con intervalos explícitos para los niveles bueno, intermedio y deficiente. Indica la unidad y los operadores de límite para que no sea necesario deducir si un límite es inclusivo. ## Escribir scripts de shell que paran ante errores y devuelven JSON Los auxiliares de Shell deben interrumpirse de inmediato ante fallos, ser legibles por máquinas y permitir una limpieza segura: - declara el Shell previsto mediante un shebang; - activa un comportamiento de interrupción inmediata ante fallos, como `set -e`; - envía los mensajes de progreso y estado al error estándar; - envía los resultados legibles por máquinas, como JSON, a la salida estándar; - crea archivos temporales de forma segura y registra trampas de limpieza; - mantenlos autocontenidos o documenta todas las dependencias externas y los requisitos previos. Mantén los diagnósticos destinados a personas fuera del flujo legible por máquinas. Comprueba los comportamientos de éxito, fallo, entrada mal formada y limpieza antes de considerar un auxiliar como automatización reutilizable. ## Dedicar cada referencia a un solo tema y enlazarla desde la habilidad Dedica cada referencia a un único tema, incluye ejemplos prácticos y enlaces al material canónico. Mantén cada referencia por debajo de 200 líneas cuando sea posible, para que el agente pueda cargarla por separado sin incorporar contexto no relacionado. Enlaza todas las referencias desde la habilidad principal o desde un índice mantenido. Retira los enlaces obsoletos y las directrices duplicadas, y conserva como responsable de los hechos cambiantes la fuente canónica más cercana. Utiliza las referencias para aportar profundidad, no como depósito indiscriminado. Una referencia debe ayudar al agente a tomar o ejecutar una decisión concreta. ## Comprobar cabecera, ejemplos, enlaces y scripts antes de publicar una habilidad Antes de enviar o publicar una habilidad: 1. Analiza y valida el frontmatter de YAML. 2. Confirma que la descripción contenga expresiones de activación utilizables. 3. Ejecuta o verifica de otro modo todos los ejemplos ejecutables. 4. Confirma que todos los archivos referenciados existan y que todos los enlaces internos se resuelvan. 5. Ejecuta los scripts mediante su interfaz documentada y verifica el comportamiento de los canales de salida. 6. Valida el paquete con la especificación aplicable de habilidades de agente. Considera necesaria, pero insuficiente, una comprobación sintáctica correcta. La descripción de activación, los ejemplos, las referencias y los scripts deben coincidir con el comportamiento que promete la habilidad. ## Ordenar los problemas de crítico a bajo y no atar los consejos a un framework Clasifica los hallazgos de forma coherente: 1. **Crítico:** vulnerabilidades de seguridad o fallo funcional completo. 2. **Alto:** fallos graves de rendimiento o barreras importantes de accesibilidad. 3. **Medio:** oportunidades significativas de rendimiento, capacidad de descubrimiento o calidad de búsqueda. 4. **Bajo:** estilo del código y oportunidades menores de optimización. Mantén las directrices web independientes de entornos de trabajo concretos. Muestra primero HTML, CSS y JavaScript estándar, coloca las notas específicas de cada entorno en secciones independientes y da prioridad a las API estándar de la plataforma, salvo que una dependencia de un entorno de trabajo sea esencial para la tarea. Revisa los problemas de corrección y las barreras de acceso de mayor impacto antes de dedicar esfuerzo a mejoras de estilo. ## Actualizar una habilidad sin romper las frases que la activan Conserva la retrocompatibilidad al actualizar las descripciones de las habilidades y mantén en funcionamiento las expresiones de activación existentes. Actualiza los metadatos de versión junto con la implementación y documenta los cambios incompatibles en el registro de cambios o la descripción del commit que exija el repositorio. Cuando cambie la estructura, actualiza conjuntamente la habilidad principal, las referencias afectadas, los scripts, los ejemplos y los enlaces. Revisa la diferencia final para detectar ampliaciones accidentales del alcance, material generado obsoleto e instrucciones duplicadas. Vuelve a ejecutar la lista de validación específica después de cada cambio de comportamiento. No declares que una habilidad actualizada está lista mientras su ruta de activación, sus ejemplos o los recursos referenciados sigan sin verificarse.