Organizar una biblioteca de habilidades de IA para investigación y publicar solo lo revisado

## Ubicar cada habilidad en una sola etapa del proceso de investigación Define la misión de la biblioteca antes de elegir sus carpetas. Una colección orientada a la investigación debe abarcar el recorrido desde la pregunta y la revisión bibliográfica hasta la ideación, la preparación de datos, la experimentación, el entrenamiento, la evaluación, el despliegue y la comunicación. Usa categorías numeradas o estables de otro modo que reflejen ese ciclo de vida. Mantén una habilidad central de orquestación que dirija el trabajo hacia habilidades especializadas sin duplicar sus orientaciones detalladas. Para cada habilidad propuesta: - Identifica la etapa del ciclo de vida y una categoría responsable. - Indica el problema del usuario que resuelve y las condiciones para usarla. - Nombra las alternativas cercanas y explica cuándo son más adecuadas. - Evita la superposición de alcance que haga parecer que una misma tarea tiene dos responsables. Trata la taxonomía como un contrato de navegación. Actualiza el catálogo, los recuentos, las descripciones y la hoja de ruta siempre que cambien la responsabilidad o el inventario. ## Reunir todos los archivos de una habilidad en una sola carpeta Asigna a cada habilidad su propio directorio con una guía principal obligatoria. Añade únicamente las carpetas auxiliares que necesite: - `references/` para documentación oficial detallada, notas de API, tutoriales, patrones de incidencias e historial de versiones. - `scripts/` para operaciones auxiliares repetibles. - `templates/` para puntos de partida reutilizables. - `examples/` para implementaciones completas y representativas. - `assets/` para material que no sea código y que utilice la guía. La guía principal es el punto de entrada, no una enciclopedia. Debe explicar la ruta operativa y enlazar directamente con referencias detalladas situadas un nivel por debajo. No crees cadenas en las que una referencia envíe al lector a otra para encontrar instrucciones obligatorias. Mantén dentro del paquete todos los archivos necesarios para ejecutar la habilidad, de modo que la validación, la creación del archivo comprimido y la sincronización con el registro operen sobre un único límite claro. ## Empezar la guía principal con campos fijos como nombre y versión Cada guía principal comienza con una cabecera YAML válida que usa un contrato de campos fijo: - `name`: un identificador único en kebab-case, preferiblemente un gerundio que describa la actividad. - `description`: texto en tercera persona que indique tanto lo que hace la habilidad como cuándo debe usarse. - `version`: una versión semántica que se actualiza cada vez que cambian el comportamiento o las orientaciones. - `author`: un valor de responsabilidad que se usa para clasificar el origen en el registro. - `license`: la licencia de distribución. - `tags`: términos con formato de título, mientras que las siglas establecidas permanecen en mayúsculas. - `dependencies`: paquetes opcionales con restricciones de versión explícitas. No pongas entre comillas los valores escalares, salvo que la sintaxis YAML lo exija. Mantén las descripciones por debajo del límite de caracteres configurado y evita identificadores imprecisos como helper, tools o utilities. Valida el descriptor analizándolo, no mediante una inspección visual. Trata como errores bloqueantes la ausencia de campos obligatorios, las versiones no válidas, los nombres duplicados y las dependencias mal formadas. ## Mantener breve la guía principal y llevar los detalles a archivos de referencia Establece entre 200 y 500 líneas como objetivo para la guía principal. Si las orientaciones esenciales superan las 500 líneas, traslada los detalles avanzados a archivos de referencia directos en vez de eliminar decisiones necesarias al comprimir el texto o permitir que el punto de entrada crezca sin límite. La guía debe incluir: - Un propósito conciso y condiciones de activación claras. - Una comparación con alternativas relevantes. - Dos o tres flujos de trabajo completos para casos de uso complejos. - Listas de comprobación listas para copiar cuando el orden sea importante. - Ejemplos concretos de entrada y salida. - Ciclos de retroalimentación que validen, corrijan y repitan el trabajo crítico para la calidad. - Una sección de problemas comunes con soluciones específicas. Supón que el lector es competente. Explica las decisiones específicas del ámbito y los modos de fallo, no los conceptos básicos que ya se desprenden de la tarea. Asigna un identificador de lenguaje a cada ejemplo de código delimitado. Crea referencias sustanciales a partir de fuentes autorizadas, con un objetivo de cobertura explícito, como aproximadamente 300 KB, cuando el ámbito lo justifique. No rellenes documentos para alcanzar una métrica de tamaño; la integridad, la trazabilidad y la utilidad práctica siguen siendo el objetivo. ## Añadir o mejorar habilidades siguiendo siempre los mismos pasos Para una habilidad nueva: 1. Selecciona un elemento aprobado de la hoja de ruta y la categoría responsable. 2. Crea la estructura estándar del paquete. 3. Escribe y valida el descriptor antes de ampliar el cuerpo. 4. Crea los flujos de trabajo principales y las orientaciones para tomar decisiones. 5. Añade referencias directas, auxiliares, plantillas y ejemplos según sea necesario. 6. Prueba la habilidad con tareas reales representativas. 7. Actualiza el catálogo, las estadísticas y la hoja de ruta en el mismo cambio. Para una habilidad existente, conserva el contrato del descriptor, incrementa la versión, mantén la guía principal dentro de su límite, añade los flujos de trabajo o la resolución de problemas que falten y vuelve a ejecutar casos de uso representativos. Usa una rama de funcionalidad y una solicitud de revisión específica. Incluye en un mismo commit todo el paquete y sus cambios de catálogo para que el repositorio nunca anuncie una habilidad incompleta. ## Comprobar las habilidades con revisiones automáticas y tareas reales Ejecuta comprobaciones mecánicas antes de la revisión: - Confirma que exista el archivo principal y que su cabecera pueda analizarse. - Compara el número de líneas de la guía principal con el objetivo de 200 a 500. - Verifica que cada bloque de código delimitado declare un lenguaje. - Mide la cobertura de las referencias respecto al objetivo elegido. - Comprueba que los archivos referenciados existan exactamente un nivel por debajo de la guía principal. - Confirma que los nombres, las etiquetas, las versiones y las dependencias se ajusten a sus esquemas. A continuación, realiza la validación del comportamiento: - Ejecuta cada flujo de trabajo principal con entradas realistas. - Verifica los resultados y los pasos de recuperación indicados. - Provoca al menos un fallo común. - Confirma que se recomiende una alternativa cuando la habilidad no sea la herramienta adecuada. - Repite la validación después de cualquier modificación sustancial. Una carpeta de referencias grande no compensa un flujo de trabajo impreciso, y una descripción general pulida no compensa unos ejemplos inutilizables. ## Subir automáticamente al registro las habilidades cambiadas tras su aprobación Tras un cambio aprobado en la rama predeterminada, detecta qué paquetes de habilidades de nivel superior han cambiado. Para cada paquete modificado: 1. Exige la guía principal y analiza su descriptor. 2. Clasifica el origen conforme a la política de responsabilidad declarada. 3. Archiva el paquete completo, excluyendo los archivos ocultos del sistema operativo y del control de versiones. 4. Carga el archivo comprimido en el espacio de nombres correspondiente del registro. 5. Crea o actualiza la entrada correspondiente del registro. 6. Informa de los paquetes omitidos o fallidos sin tratarlos silenciosamente como sincronizados. Almacena los valores del punto de conexión y de autenticación únicamente en el almacén de secretos de la plataforma de automatización. Admite una activación manual para recuperación y pruebas, pero garantiza que la misma lógica de validación y empaquetado se ejecute tanto en el modo automático como en el manual. Verifica el flujo de trabajo con un cambio versionado inocuo, inspecciona la ejecución de la automatización, confirma la entrada del registro y el archivo comprimido, y evita usar modificaciones no revisadas únicamente para activar la canalización. ## Publicar un paquete nuevo solo cuando cambia su número de versión Controla la publicación del paquete mediante un cambio de versión en el descriptor del paquete de la rama predeterminada. Un cambio exclusivo del archivo de bloqueo no debe publicar una versión nueva. Usa el comando de versión del gestor de paquetes para que el descriptor y el archivo de bloqueo avancen juntos. Selecciona una versión de parche, menor o mayor según la compatibilidad, y suprime las etiquetas automáticas del control de versiones únicamente cuando el proceso de publicación del repositorio exija un commit independiente. Autentícate mediante un publicador de confianza configurado, no mediante un token de registro de larga duración. Adjunta la procedencia de la compilación o una certificación equivalente de la cadena de suministro a cada artefacto publicado. Antes de publicar, verifica: - La identidad del publicador de confianza coincide exactamente con los nombres del repositorio y del flujo de trabajo. - Las variables de entorno no sustituyen la autenticación de confianza por un token obsoleto. - La instalación limpia se completa correctamente a partir del archivo de bloqueo incluido en el commit. - La versión nueva es diferente de la revisión anterior. - El contenido del paquete coincide con la fuente revisada. Si se omite la publicación o falla la autenticación, corrige el control de versión o la identidad de confianza; no eludas la procedencia. ## Mejorar las habilidades existentes en lugar de sumar más Evalúa la biblioteca por el conocimiento experto ejecutable, no por el número de directorios. Una habilidad útil condensa prácticas fiables en un formato que un agente pueda seguir y verificar, y que le permita recuperarse ante fallos. Antes de integrar, confirma: - El alcance encaja en una categoría y no duplica a un responsable existente. - Se cumplen las reglas del descriptor, de nomenclatura y de versión. - La guía principal se mantiene enfocada y todos los detalles obligatorios siguen siendo accesibles. - Los flujos de trabajo, las listas de comprobación, los ejemplos, las alternativas y la resolución de problemas están presentes donde se necesitan. - Las tareas reales validan las orientaciones. - El catálogo, la hoja de ruta, la automatización del archivado y los datos de publicación del paquete siguen siendo coherentes. Prefiere mejorar una habilidad existente antes que añadir otra casi duplicada. Prefiere un flujo de trabajo completo con un ciclo de retroalimentación funcional antes que muchos ejemplos superficiales. Cuando una métrica entre en conflicto con la claridad o la corrección, conserva las orientaciones útiles para tomar decisiones y documenta por qué esa métrica no era la aproximación adecuada.