Escribir y publicar habilidades de agente que se activen bien y pasen la validación

## Limitar la descripción a qué hace la habilidad y cuándo usarla Trata la descripción como metadatos de enrutamiento, no como un procedimiento comprimido. Los agentes pueden elegir una habilidad a partir de su descripción antes de leer el cuerpo completo, por lo que los pasos de proceso incrustados pueden sustituir o eludir el flujo de trabajo detallado. Redacta las descripciones con una declaración breve de capacidad seguida de las condiciones de activación: qué hace la habilidad y cuándo debe usarse. Mantén la descripción dentro del límite del esquema activo, incluido un máximo de 1,024 caracteres cuando corresponda. Nunca incluyas pasos ordenados, secuencias de implementación ni procedimientos de resolución de problemas en la descripción; coloca todas las indicaciones prácticas en el cuerpo de la habilidad. Prueba las descripciones con solicitudes realistas para confirmar que se activan ante las peticiones previstas, permanecen inactivas en trabajos no relacionados y conducen al agente hasta las instrucciones completas. ## Usar solo los campos de cabecera de la especificación y referencias válidas a otras habilidades Sigue la especificación de habilidades activa en lugar de copiar campos de un repositorio vecino. Conserva en el nivel superior únicamente los campos definidos por la especificación, incluidos `name` y `description`; usa `license` y `allowed-tools` solo de acuerdo con el contrato del repositorio. Cuando esté presente, `allowed-tools` debe ser una lista delimitada por espacios. Coloca los campos específicos del repositorio dentro de `metadata`. Restringe los nombres a letras, números y guiones. Valida la longitud de las descripciones y la redacción de los activadores. Mantén los metadatos estructurados, como autor, versión semántica, dominio, activadores, función, ámbito, formato de salida y habilidades relacionadas, dentro de las enumeraciones y los formatos definidos por el repositorio. Cada entrada de habilidad relacionada debe resolverse hacia un directorio de habilidad existente. Usa de forma coherente el valor de licencia aprobado por el repositorio; cuando el repositorio fije la licencia en MIT, escribe exactamente `license: MIT`. No aceptes valores de enumeración desconocidos, referencias rotas ni campos superiores personalizados solo porque el analizador de YAML los admita. ## Mantener corto el archivo principal y llevar los detalles a archivos de referencia Mantén el archivo principal de la habilidad lo bastante compacto como para cargarlo como contexto de enrutamiento y operación. Un primer nivel práctico tiene aproximadamente entre 80 y 100 líneas e incluye la función, las indicaciones de activación, un flujo de trabajo central de cinco pasos, los comportamientos obligatorios y prohibidos, y una tabla de enrutamiento hacia referencias más detalladas. Coloca el material técnico detallado en archivos de referencia específicos de segundo nivel, normalmente de 100 a 600 líneas cada uno. Cada referencia debe tratar un solo tema, incluir ejemplos funcionales completos con los tipos pertinentes, explicar casos límite y antipatrones, e indicar cuándo se deben usar las directrices y cuándo no. Carga únicamente las referencias necesarias para la tarea actual. Crea enlaces cruzados con habilidades relacionadas cuando resulte útil, pero no dupliques todo su contenido. Considera la reducción del uso de contexto como un resultado de diseño; una estructura de dos niveles bien enrutada puede aspirar a una reducción aproximada del 50% sin omitir instrucciones necesarias. ## Usar en los ejemplos los mecanismos propios de cada framework Las directrices específicas de un framework deben usar los mecanismos establecidos por ese framework. Si el framework ofrece gestión global de errores, middleware, inyección de dependencias, enlaces del ciclo de vida u otra abstracción incorporada, los ejemplos deben usar ese mecanismo en lugar de recrearlo manualmente. No impongas una arquitectura genérica única a frameworks no relacionados solo para lograr una uniformidad visual en todo el repositorio. Tienen prioridad las convenciones del framework sobre gestión de errores, organización, pruebas e integración. Mantén los ejemplos de referencia completos y ejecutables, e incluye tipos cuando el lenguaje los admita. Revisa los ejemplos con respecto a la versión del framework incluida en el ámbito y rechaza los patrones que dupliquen comportamientos incorporados u oculten restricciones específicas del framework. ## Terminar cada archivo de habilidad con un único enlace a la documentación Todo archivo de habilidad debe terminar con exactamente un enlace de retorno canónico a la documentación en su última línea. Usa la sintaxis de enlace de Markdown con la etiqueta `Documentation` y la URL canónica, no una URL sin formato, para que los renderizadores estrictos produzcan un hipervínculo real. Deriva la ruta canónica a partir de metadatos estables, como `metadata.domain`, y del nombre del directorio de la habilidad. Aplica el dominio alternativo documentado cuando no haya metadatos. Al añadir o renombrar una habilidad, actualiza conjuntamente el directorio, el dominio y el enlace de retorno; de lo contrario, el enlace publicado puede conducir a una página inexistente. Ten en cuenta de forma explícita las distintas superficies de publicación. Los agregadores de archivos sin procesar pueden necesitar el enlace de retorno para facilitar el descubrimiento, mientras que la compilación de documentación puede excluir ese mismo enlace a sí misma de las páginas generadas, los espejos y los índices para modelos lingüísticos. Conserva ambos comportamientos en el paso de sincronización y prueba el destino renderizado. ## Revisar solapamientos y actualizar referencias al crear o cambiar una habilidad Para una habilidad nueva: 1. Comprueba si las habilidades existentes tienen responsabilidades solapadas. 2. Escribe la habilidad principal con metadatos de capacidad y activación, dejando los pasos del proceso en el cuerpo. 3. Añade referencias específicas para el contenido detallado. 4. Añade una tabla de enrutamiento desde los temas hasta las referencias. 5. Agrega el único enlace de retorno canónico a la documentación como última línea. 6. Prueba solicitudes que deban activar la habilidad y solicitudes que no deban activarla. 7. Actualiza la guía de habilidades y los índices de dominios cuando cambie la taxonomía. Antes de modificar una habilidad, lee todo su cuerpo actual y las referencias afectadas por el cambio. Conserva la estructura de descripción basada en capacidad y activación, así como la arquitectura de divulgación progresiva. Actualiza las tablas de enrutamiento, las referencias a habilidades relacionadas, los índices de documentación y las pruebas de activación siempre que cambien los nombres, el ámbito, los activadores o las dependencias. ## Sincronizar recuentos y registro de cambios con un único archivo de versión Usa un único manifiesto de versión como fuente de verdad para la versión de publicación y los recuentos calculados de habilidades, flujos de trabajo y archivos de referencia. Ejecuta la herramienta de actualización del repositorio para volver a calcular los recuentos desde el sistema de archivos y sincronizar la documentación generada. Admite modos de comprobación y simulación para que CI y quienes revisan puedan detectar desviaciones sin escribir cambios. Añade la nueva versión al principio del registro de cambios con una estructura estable de Added, Changed y Fixed, y mantén el enlace de comparación de versiones. Actualiza las guías, los árboles de decisión, las tablas de comandos y las referencias cruzadas para el contenido nuevo o modificado antes de regenerar la documentación agregada. Regenera los recursos para redes sociales que contengan recuentos solo cuando cambien los recuentos incorporados; un parche que cambie únicamente la versión no requiere un recurso nuevo. Revisa las diferencias generadas para evitar que la automatización oculte cambios no relacionados. ## Ejecutar los validadores de habilidades y de Markdown antes de publicar Ejecuta el validador de integridad de habilidades antes de publicar. Debe comprobar el análisis de YAML, los campos obligatorios, el formato del nombre, la longitud de la descripción y la cláusula de activación `Use when` obligatoria, la existencia del directorio de referencias, la estructura de las referencias y la coherencia de los recuentos. Proporciona comprobaciones limitadas a una habilidad o a una familia de validación, además de resultados legibles por máquinas para CI. Ejecuta por separado un validador de Markdown. Comprueba si hay comentarios HTML que rompan tablas, bloques de código sin cerrar, filas separadoras de tabla ausentes y recuentos de columnas incoherentes. Valida todo el repositorio después de la investigación específica. Considera el código de salida 0 como éxito y el código de salida 1 como fallo de validación, y revisa expresamente las advertencias. Nunca publiques una versión con errores de validación sin resolver solo porque haya pasado una comprobación de alcance más limitado. ## Registrar comandos y resultados antes de dar la publicación por lista Después de la sincronización y la validación, busca referencias de versión obsoletas y excluye el historial intencionado del registro de cambios. Confirma manualmente que las descripciones, las pruebas de activación, las tablas de enrutamiento, las referencias a habilidades relacionadas, los enlaces de retorno canónicos, los recuentos generados y los recursos condicionales coinciden con la publicación. Conserva las atribuciones a terceros, los avisos de licencia y las referencias de investigación cuando se hayan adaptado patrones de comportamiento o disciplina de procesos procedentes de otros trabajos. No pierdas la procedencia durante la limpieza. Registra los comandos exactos de actualización y validación, sus resultados, las advertencias revisadas y cualquier paso condicional omitido de manera intencionada. Informa que la publicación está lista solo después de que pasen todos los validadores obligatorios y de que las diferencias finales no contengan cambios sin explicación.