Saltar al contenido principal

​
Qué es un repositorio enlazado

Es un repo de GitHub del que el workspace toma sus skills. Las skills se escriben y se revisan en el repo, y después de cada merge en la rama enlazada lo nuevo o cambiado llega solo a Tuqui. En Tuqui no se editan: en Configuración → Skills cada una dice «Viene de» y el nombre del repo, y para cambiarla hay que ir al repo. Alcanza solo a las skills del workspace, no a las personales. Si una skill personal tiene el mismo nombre que una del repo, la del repo la tapa. Los repos se administran en una página que cuelga de Skills: en Configuración → Skills, haz clic en Gestionar repositorios y se abre Repositorios. Para volver, usa ← Skills. No está en el menú de Configuración, y el botón solo lo ven los admins del workspace.

​
Formato del repositorio

Cada skill es una carpeta con un SKILL.md en formato Agent Skills, directamente adentro de la carpeta enlazada (por defecto, skills/). Los demás archivos de la carpeta viajan con la skill.
El frontmatter del SKILL.md lleva metadata.id:
metadata.id es obligatorio y no debe cambiar: en minúsculas con guiones, hasta 64 caracteres. Es lo que Tuqui usa para reconocer la skill. Con el mismo id puedes cambiarle el nombre o moverla de carpeta, y sigue siendo la misma skill. Dos carpetas con el mismo id hacen fallar a las dos. Una skill que no cumple el formato o pasa un límite no llega: queda la última versión válida y el error se ve en la pantalla del repo.

​
Estados de una skill del repositorio

Debajo de cada repo enlazado están la rama, la carpeta, el último commit y la hora de la última sincronización, y una tabla con el estado de cada skill: Lo nuevo de un merge llega en menos de 5 minutos. Si se pierde el aviso de GitHub, llega igual en hasta 15 minutos. Para no esperar, haz clic en Sincronizar ahora. Cada cambio que llega queda en el historial de versiones de la skill, con su commit.

​
Instalar la GitHub App de Tuqui

Tuqui lee los repos con su propia GitHub App. Pide solo lectura del contenido de los repos que elijas: no escribe en GitHub. Antes de empezar: tienes que ser admin del workspace. La App la instala en GitHub un dueño de la organización; si no lo eres, GitHub le manda el pedido a uno.
  1. Ve a Configuración → Skills, haz clic en Gestionar repositorios y después en Conectar GitHub.
  2. En GitHub, elige la organización y los repos que Tuqui puede leer.
  3. Confirma. GitHub te devuelve a Tuqui.
Resultado: la cuenta de GitHub aparece en la pantalla y ya puedes enlazar un repo. Si GitHub mandó el pedido a un dueño, cuando lo apruebe haz clic de nuevo en Conectar GitHub para terminar. El menú GitHub de la página lista las cuentas con la App instalada. Para sumar o sacar repos, o para instalar la App en otra organización, haz clic en Gestionar en GitHub: se abre GitHub, y al volver la cuenta nueva queda vinculada. Si la App se instaló directo desde GitHub, usa Buscar instalaciones en GitHub.

​
Vincular una instalación que ya existe

Si la App ya se instaló desde GitHub, no hace falta instalarla de nuevo.
  1. Haz clic en Ya la instalé desde GitHub. Si ya hay una cuenta vinculada, usa el menú GitHub → Buscar instalaciones en GitHub.
  2. GitHub te pide que autorices a Tuqui con tu usuario y te devuelve a Tuqui.
  3. Si tu usuario de GitHub es dueño de una sola cuenta nueva con la App, se vincula directo. Si es dueño de más de una, Tuqui te las muestra todas marcadas: desmarca las que no quieras en este workspace y haz clic en Vincular las elegidas.
Resultado: las cuentas elegidas aparecen en el menú GitHub. Los admins del workspace pueden enlazar repos de esas cuentas, así que vincula solo las que correspondan a este workspace. Solo puede vincular una cuenta quien es dueño de ella en GitHub.

​
Desconectar GitHub de este workspace

  1. Abre el menú GitHub y haz clic en Desconectar GitHub de este workspace, al final del menú.
  2. La confirmación dice cuántos repos se desenlazan y cuántas skills dejan de llegar. Confirma con Desconectar.
Resultado: se desvinculan todas las cuentas de GitHub del workspace, todos sus repos se desenlazan y sus skills dejan de llegar, sin borrarse. La pantalla vuelve a Conectar GitHub. La App sigue instalada en GitHub y los demás workspaces no cambian. Para quitarle el acceso a Tuqui en todos los workspaces, desinstala la App en GitHub: la confirmación trae un link por cuenta.

​
Enlazar un repositorio

Antes de empezar: la App tiene que estar instalada en el repo. Protege en GitHub la rama que vas a enlazar: quien puede mergear en ella publica skills en el workspace, scripts incluidos.
  1. Haz clic en Enlazar repositorio.
  2. Elige el Repositorio. La Rama se completa con la rama principal del repo; cámbiala si las skills están en otra.
  3. En Carpeta, deja skills/ o escribe la carpeta donde están las skills.
  4. Lee los avisos y haz clic en Enlazar.
Resultado: el repo aparece en la lista y sus skills llegan con la primera sincronización. Las skills del workspace que tengan el mismo nombre que una del repo pasan a salir del repo y quedan como Adoptada. Conservan con quién estaban compartidas, los agentes que las usan y su historial. Lo mismo pasa si más adelante el repo suma una skill con el nombre de una que ya estaba en el workspace.

​
Desenlazar un repositorio

  1. Abre el menú ⋯ del repo y haz clic en Desenlazar. En el mismo menú está Sincronizar ahora.
  2. La confirmación dice cuántas skills dejan de llegar. Confirma con Desenlazar.
Resultado: esas skills dejan de llegar, sin borrarse. Si vuelves a enlazar el repo, vuelven las mismas. Para mover skills de un repo a otro, enlaza el nuevo antes de desenlazar el viejo. Las skills con el mismo metadata.id pasan al repo nuevo sin dejar de llegar.

​
Duplicar una skill del repositorio para editarla

Si necesitas una versión propia de una skill que viene del repo, haz una copia.
  1. En Configuración → Skills, abre el menú de la skill y elige Duplicar y editar.
  2. Escribe un Nombre nuevo y haz clic en Crear copia.
Resultado: la copia es una skill propia del workspace, con los archivos que acompañan al SKILL.md. Se puede editar y ya no se actualiza desde el repo.

​
Solución de problemas

​
Skills avisa «Hay problemas en» un repositorio enlazado

Un repo no se pudo sincronizar o tiene skills que fallaron. El aviso aparece arriba de la lista en Configuración → Skills y solo lo ven los admins. Haz clic en Ver repositorios y busca el repo con el error.

​
El repo dice «Sin sincronizar desde» una hora

GitHub no respondió, la App perdió acceso al repo o la carpeta enlazada no tiene ninguna skill. Mientras tanto, Tuqui no borra ni retira nada. Lee el motivo debajo del aviso. Si la App perdió acceso, suma el repo de nuevo con GitHub → Gestionar en GitHub. Después haz clic en Sincronizar ahora.

​
Una skill dice «Falló»

El error de la tabla dice qué falta: frontmatter inválido, metadata.id ausente o repetido, o un archivo que pasa un límite. Corrígelo en el repo y mergea. Hasta entonces sigue en uso la última versión válida.

​
El repo no aparece al enlazar

La App no tiene acceso a ese repo. Haz clic en ¿No está tu repo? Darle acceso a la app en GitHub, súmalo y vuelve a abrir Enlazar repositorio.