Mantén los documentos de habilidades de IA en un solo lugar y escríbelos para que la IA los consulte

## Edita solo el archivo fuente y regenera las copias con el generador Identifica el documento canónico de la habilidad y trata las integraciones generadas, los manifiestos y las proyecciones específicas de cada plataforma como artefactos derivados. Edita la fuente y sus referencias y, después, regenera los derivados con el generador del repositorio. Nunca edites manualmente los resultados administrados por la integración continua. Conserva en ella un modo de comprobación que regenere en memoria o en un área temporal y que falle cuando los derivados confirmados en el repositorio se desvíen de la fuente. Cuando una misma habilidad se distribuya a través de varias plataformas, comparte el contenido en lugar de mantener bifurcaciones. Registra qué archivo es propietario del contenido, los metadatos y los valores de versión para que los colaboradores no creen fuentes rivales. Mantén la instalación y el uso para usuarios finales fuera de las instrucciones para colaboradores. La documentación para colaboradores debe explicar el mantenimiento, la validación, las pruebas y el comportamiento de los lanzamientos sin duplicar la guía del producto. ## Deja las decisiones en el documento principal y los detalles en archivos de referencia Usa el documento principal de la habilidad como punto de entrada para la recuperación y carga las referencias detalladas solo cuando sean necesarias. Distribuye el contenido así: - los marcos de decisión y los patrones frecuentes, en el documento de entrada; - las guías detalladas, las plantillas y los ejemplos ampliados, en archivos de referencia; - los escenarios de referencia y los registros de justificación, en la documentación de pruebas; - la instalación y el uso, en la documentación destinada a usuarios; - los detalles del proceso de colaboración, en la guía de contribución. Usa enlaces relativos estables entre el documento de entrada y las referencias adyacentes. Conserva los anclajes de referencia de nivel superior utilizados por las tablas de enrutamiento, incluso al reestructurar subsecciones inferiores. Aplica una prueba de ubicación: si un elemento determina qué ruta elegir, mantenlo cerca del punto de entrada; si explica en profundidad cómo ejecutar una ruta ya elegida, muévelo a una referencia. ## Escribe instrucciones breves y directas, con las tablas de decisión primero Optimiza el contenido para un agente que clasifica la intención, selecciona una rama y actúa, no para un lector que recorre la guía de principio a fin. Cuando sean válidos varios enfoques, coloca una tabla de decisiones compacta antes del manual operativo. Ordena cada sección así: 1. tabla de decisiones; 2. procedimiento predeterminado; 3. alternativas; 4. reglas concisas y puntos críticos. Usa la voz imperativa y expresa un solo hecho por viñeta. Convierte estructuras de recomendación como «deberías considerar», «ten en cuenta» o «recuerda» en acciones directas. Para las distinciones poco evidentes, prefiere reglas afirmativas y negativas breves. Cada tabla, ejemplo y bloque de código debe aportar un hecho que aún no se haya indicado. Cuando el procedimiento ya transmita la instrucción, elimina las comparaciones de antes y después, las justificaciones repetidas, los apartes didácticos y los ejemplos incluidos solo por exhaustividad. Limita la justificación a una sola frase inicial. Define un objetivo de tokens para cada subsección y divide o comprime las que lo superen sin quitar criterios de decisión, acciones obligatorias, restricciones ni excepciones. ## Comprueba la estructura del documento y prueba el comportamiento de la IA tras cada cambio Adapta la validación al artefacto. Las habilidades centradas en documentación quizá no necesiten compilación, pero sí requieren comprobaciones estructurales automatizadas y pruebas manuales de comportamiento. Automatiza las comprobaciones de los campos de frontmatter obligatorios, las reglas de nombres, los límites de líneas o tokens, los enlaces internos, la sincronización de artefactos generados y las reglas de lint propias del repositorio. Trata los objetivos flexibles de tamaño como advertencias y las restricciones estrictas de integridad como fallos. Para un cambio de contenido: 1. edita la habilidad canónica o una referencia; 2. ejecuta la validación estructural local; 3. vuelve a cargar la habilidad en su entorno anfitrión; 4. ejecuta consultas realistas de usuarios que recorran la rama modificada; 5. compara el comportamiento con los escenarios de referencia para detectar regresiones. Exige en la solicitud de incorporación evidencias del antes y el después para los escenarios afectados. Para cambios sustanciales de arquitectura de la información, solicita una revisión independiente centrada en la estructura de recuperación, la compresión y las ramas de decisión ausentes. ## Exige comprobaciones en las pull requests y deja la versión a la publicación automática Protege la rama principal: exige solicitudes de incorporación, comprobaciones de validación y un título válido conforme a la convención. Si los cambios se integran mediante una fusión squash y el título de la solicitud se convierte en el commit de lanzamiento, valida ese título porque determina la versión. Asocia los tipos de cambio convencionales a incrementos de versión e incluye una señal explícita para los cambios mayores. Haz que el flujo de lanzamientos actualice el registro de cambios, los metadatos de la versión canónica, los manifiestos de plataforma y los artefactos generados en un solo cambio de lanzamiento. Nunca edites manualmente números de versión sincronizados. Conserva una única fuente canónica para la versión y deja que la canalización de lanzamientos la propague antes de crear la etiqueta. Antes de integrar, confirma lo siguiente: - los resultados generados coinciden con la fuente canónica; - las tablas de decisiones preceden a los manuales con ramificaciones; - se han eliminado las estructuras introductorias y los ejemplos redundantes; - los anclajes utilizados para el enrutamiento permanecen estables; - los escenarios de referencia modificados incluyen evidencias; - se han superado las comprobaciones obligatorias de validación y del título.