Crear habilidades de agente desde la documentación de un proyecto y mantenerlas al día

## Ver quién mantiene una habilidad antes de editarla Determina cómo se gestiona cada habilidad antes de crear o actualizar archivos. Usa habilidades generadas para proyectos que publican documentación, pero no mantienen un paquete de habilidades de agente; habilidades sincronizadas para proyectos que ya publican sus propias habilidades; y habilidades escritas a mano para conocimientos especializados seleccionados deliberadamente. No mezcles estos flujos de trabajo. Las habilidades generadas se sintetizan a partir de la documentación, las habilidades sincronizadas se copian de su fuente de habilidades original y las habilidades escritas a mano permanecen intactas salvo que la tarea las incluya explícitamente. ## Tomar de la documentación solo lo que ayuda al agente en sus tareas Céntrate en capacidades, puntos de decisión, patrones prácticos de uso, ejemplos funcionales y las circunstancias en las que un agente debe elegir un enfoque en lugar de otro. Da prioridad al conocimiento que mejore de forma sustancial la ejecución de las tareas. Omite las introducciones dirigidas al usuario, los recorridos de instalación, el material genérico de primeros pasos, los textos promocionales y los conceptos que un modelo competente ya pueda manejar con fiabilidad. Reescribe y sintetiza el material de origen en vez de copiar la documentación literalmente. Mantén la habilidad compacta. Crea únicamente las referencias necesarias para cubrir conceptos distintos, evita archivos redundantes y explica tanto cómo funciona un patrón como por qué o cuándo debe utilizarse. ## Añadir un proyecto nuevo al registro y generar su habilidad Añade una nueva fuente generada al registro canónico de proyectos del repositorio, incluyendo su ubicación de origen y un identificador estable del proyecto. Inicializa o sincroniza la fuente mediante el flujo de trabajo admitido por el repositorio, en lugar de crear una copia local sin seguimiento. Lee la documentación del proyecto y todas las instrucciones de generación específicas del proyecto con suficiente detalle para comprender sus capacidades y convenciones. Organiza el material útil en categorías como conceptos fundamentales, funciones, prácticas recomendadas y flujos de trabajo avanzados. Crea el directorio de salida cuyo nombre coincida con el identificador registrado de la fuente generada. Escribe los archivos de referencia, construye el índice de la habilidad y registra metadatos de generación que contengan la revisión exacta de la fuente. ## Actualizar las habilidades generadas solo donde cambió la documentación Lee la revisión de la fuente registrada en los metadatos de generación y compárala con la fuente actual. Limita la diferencia de la fuente al área de documentación que rige la habilidad generada. Actualiza solo las referencias afectadas por esa diferencia y, cuando sea necesario, actualiza la versión del proyecto, la fecha de generación, la tabla de temas y las descripciones del índice. Conserva las referencias no afectadas y evita regenerar contenido no relacionado solo porque el repositorio de origen haya avanzado. Después de la revisión, sustituye la revisión registrada por la revisión exacta utilizada para la actualización, de modo que la próxima comparación disponga de una base fiable. ## Copiar sin editar a mano las habilidades mantenidas en el origen Para una habilidad mantenida en el origen, utiliza el registro para determinar qué habilidad de origen debes copiar y qué nombre de salida debes usar. El nombre de salida puede diferir intencionadamente del directorio de origen, así que nunca lo deduzcas únicamente a partir del nombre de la fuente. En la primera importación, copia el árbol de habilidades configurado y registra la revisión de origen en los metadatos de sincronización. Para las actualizaciones, compara la revisión registrada con el directorio actual de habilidades de origen, copia únicamente los archivos modificados incluidos en la configuración y actualiza la revisión registrada. Nunca modifiques manualmente el contenido de una habilidad sincronizada. Aporta las correcciones al responsable de origen y recupéralas mediante el flujo de trabajo de sincronización, para que las copias locales no se desvíen. ## Escribir un índice breve con enlaces a cada referencia Proporciona al índice de la habilidad un frontmatter válido con un nombre en kebab-case, una descripción concisa de la capacidad, metadatos de procedencia, la fecha de generación o sincronización y la versión pertinente de la herramienta o del proyecto. Añade un breve párrafo de orientación y, después, agrupa las referencias en categorías claras. Para cada tema, proporciona una descripción breve y un enlace relativo a la referencia correspondiente, de modo que un agente pueda cargar solo el material necesario para la tarea actual. Mantén el índice conciso y orientado a la navegación. No dupliques en el índice el contenido completo de las referencias ni añadas entradas para archivos que no existen. ## Tratar un solo tema práctico en cada archivo de referencia Proporciona a cada archivo de referencia un frontmatter con un nombre estable y una descripción específica, seguido de un título conceptual claro. Trata una capacidad o un flujo de trabajo coherente por archivo, en lugar de combinar funciones no relacionadas. Incluye orientación práctica de uso, ejemplos de código funcionales cuando el concepto sea ejecutable, restricciones clave y el razonamiento que sustenta los patrones recomendados. Omite el contexto que no ayude a un agente a tomar o ejecutar una decisión. Termina con referencias a las fuentes que identifiquen la documentación utilizada para sintetizar el contenido. Mantén esas referencias rastreables sin convertir la habilidad en una copia del material de origen. ## Registrar la revisión y la fecha de la fuente de cada habilidad Para las habilidades generadas, registra la ubicación de la fuente, la revisión exacta de la fuente y la fecha de generación. Para las habilidades sincronizadas, registra la ubicación de la habilidad de origen, la revisión exacta de origen y la fecha de sincronización. Mantén la versión del índice alineada con el estado real de la fuente y usa la última fecha de generación o sincronización de acuerdo con la política del repositorio. No declares una versión o revisión del proyecto más reciente que aquella de la que se derivó el contenido. Trata el registro como la lista canónica de proyectos admitidos y ubicaciones de fuentes. Evita duplicar URL de repositorios modificables o correspondencias de propiedad entre archivos de habilidades cuando el registro ya sea su fuente responsable. ## Revisar los cambios finales en busca de enlaces rotos y revisiones antiguas Antes de finalizar, confirma que la clasificación de la fuente, la entrada del registro, la regla de nomenclatura de salida, los enlaces del índice, el frontmatter de las referencias, la organización de categorías, los metadatos de revisión y las citas de las fuentes sean coherentes entre sí. Verifica que el contenido generado se haya sintetizado en lugar de copiarse, que el contenido sincronizado no presente desviaciones manuales, que las habilidades escritas a mano no se hayan modificado sin estar dentro del alcance y que cada referencia aporte un valor distinto al agente. Revisa la diferencia final para detectar archivos no relacionados, referencias excesivas, versiones obsoletas, ejemplos ausentes, enlaces rotos y cambios de fuente no registrados. Informa de cualquier limitación de la fuente o de las herramientas que haya impedido completar la generación o la sincronización.