Passer au contenu principal

​
Ce qu’est un dépôt relié

C’est un dépôt GitHub d’où l’espace de travail tire ses skills. Les skills s’écrivent et se relisent dans le dépôt, et après chaque merge sur la branche reliée, ce qui est nouveau ou modifié arrive tout seul dans Tuqui. Elles ne se modifient pas dans Tuqui : dans Settings → Skills, chacune affiche « From » suivi du nom du dépôt, et pour la changer il faut passer par le dépôt. Seules les skills de l’espace de travail sont concernées, pas les skills personnelles. Si une skill personnelle porte le même nom qu’une skill du dépôt, celle du dépôt la masque. Les dépôts se gèrent sur une page rattachée à Skills : dans Settings → Skills, cliquez sur Manage repositories et la page Repositories s’ouvre. Pour revenir, utilisez ← Skills. Elle n’est pas dans le menu Settings, et seuls les administrateurs de l’espace de travail voient le bouton.

​
Format du dépôt

Chaque skill est un dossier avec un SKILL.md au format Agent Skills, placé directement dans le dossier relié (skills/ par défaut). Les autres fichiers du dossier accompagnent la skill.
Le frontmatter du SKILL.md contient metadata.id :
metadata.id est obligatoire et ne doit pas changer : en minuscules avec des tirets, 64 caractères au maximum. C’est ce qui permet à Tuqui de reconnaître la skill. Avec le même id, vous pouvez la renommer ou la déplacer dans un autre dossier : elle reste la même skill. Deux dossiers avec le même id échouent tous les deux. Une skill qui ne respecte pas le format ou dépasse une limite n’arrive pas : la dernière version valide reste en place et l’erreur s’affiche sur l’écran du dépôt.

​
États d’une skill du dépôt

Sous chaque dépôt relié s’affichent la branche, le dossier, le dernier commit et l’heure de la dernière synchronisation, ainsi qu’un tableau avec l’état de chaque skill : Ce qu’apporte un merge arrive en moins de 5 minutes. Si la notification de GitHub se perd, cela arrive quand même en 15 minutes au plus. Pour ne pas attendre, cliquez sur Sync now. Chaque changement reçu entre dans l’historique des versions de la skill, avec son commit.

​
Installer la GitHub App de Tuqui

Tuqui lit les dépôts avec sa propre GitHub App. Elle ne demande qu’un accès en lecture au contenu des dépôts que vous choisissez : elle n’écrit rien sur GitHub. Avant de commencer : vous devez être administrateur de l’espace de travail. C’est un propriétaire de l’organisation GitHub qui installe l’App ; si vous ne l’êtes pas, GitHub lui envoie la demande.
  1. Allez dans Settings → Skills, cliquez sur Manage repositories puis sur Connect GitHub.
  2. Sur GitHub, choisissez l’organisation et les dépôts que Tuqui peut lire.
  3. Confirmez. GitHub vous renvoie vers Tuqui.
Résultat : le compte GitHub apparaît à l’écran et vous pouvez relier un dépôt. Si GitHub a envoyé la demande à un propriétaire, cliquez de nouveau sur Connect GitHub une fois qu’il l’a approuvée. Le menu GitHub de la page liste les comptes où l’App est installée. Pour ajouter ou retirer des dépôts, ou pour installer l’App sur une autre organisation, cliquez sur Manage on GitHub : GitHub s’ouvre, et au retour le nouveau compte est lié. Si l’App a été installée directement depuis GitHub, utilisez Search installations on GitHub.

​
Lier une installation qui existe déjà

Si l’App a déjà été installée depuis GitHub, inutile de l’installer de nouveau.
  1. Cliquez sur I already installed it from GitHub. Si un compte est déjà lié, utilisez le menu GitHub → Search installations on GitHub.
  2. GitHub vous demande d’autoriser Tuqui avec votre utilisateur et vous renvoie vers Tuqui.
  3. Si votre utilisateur GitHub est propriétaire d’un seul nouveau compte avec l’App, il est lié directement. S’il l’est de plusieurs, Tuqui les affiche tous cochés : décochez ceux que vous ne voulez pas dans cet espace de travail et cliquez sur Link the selected ones.
Résultat : les comptes choisis apparaissent dans le menu GitHub. Les administrateurs de l’espace de travail peuvent relier des dépôts de ces comptes : ne liez que ceux qui concernent cet espace de travail. Seul un propriétaire du compte sur GitHub peut le lier.

​
Déconnecter GitHub de cet espace de travail

  1. Ouvrez le menu GitHub et cliquez sur Disconnect GitHub from this workspace, à la fin du menu.
  2. La confirmation indique combien de dépôts seront déliés et combien de skills n’arriveront plus. Confirmez avec Disconnect.
Résultat : tous les comptes GitHub de l’espace de travail sont déliés, tous ses dépôts sont déliés et leurs skills n’arrivent plus, sans être supprimées. L’écran revient à Connect GitHub. L’App reste installée sur GitHub et les autres espaces de travail ne changent pas. Pour retirer l’accès de Tuqui dans tous les espaces de travail, désinstallez l’App sur GitHub : la confirmation contient un lien par compte.

​
Relier un dépôt

Avant de commencer : l’App doit être installée sur le dépôt. Protégez sur GitHub la branche que vous allez relier : toute personne qui peut y faire un merge publie des skills dans l’espace de travail, scripts compris.
  1. Cliquez sur Link repository.
  2. Choisissez le dépôt dans Repository. Le champ Branch reprend la branche principale du dépôt ; changez-la si les skills sont sur une autre.
  3. Dans Folder, laissez skills/ ou saisissez le dossier qui contient les skills.
  4. Lisez les avertissements et cliquez sur Link.
Résultat : le dépôt apparaît dans la liste et ses skills arrivent à la première synchronisation. Les skills de l’espace de travail qui portent le même nom qu’une skill du dépôt viennent désormais du dépôt et s’affichent comme Adopted. Elles conservent leurs partages, les agents qui les utilisent et leur historique. Il en va de même si le dépôt ajoute plus tard une skill portant le nom d’une skill déjà présente dans l’espace de travail.

​
Délier un dépôt

  1. Ouvrez le menu ⋯ du dépôt et cliquez sur Unlink. Sync now se trouve dans le même menu.
  2. La confirmation indique combien de skills n’arriveront plus. Confirmez avec Unlink.
Résultat : ces skills n’arrivent plus, sans être supprimées. Si vous reliez de nouveau le dépôt, les mêmes skills reviennent. Pour déplacer des skills d’un dépôt à un autre, reliez le nouveau avant de délier l’ancien. Les skills avec le même metadata.id passent au nouveau dépôt sans interruption.

​
Dupliquer une skill du dépôt pour la modifier

Si vous avez besoin de votre propre version d’une skill qui vient du dépôt, faites-en une copie.
  1. Dans Settings → Skills, ouvrez le menu de la skill et choisissez Duplicate and edit.
  2. Saisissez un nom dans New name et cliquez sur Create copy.
Résultat : la copie est une skill propre à l’espace de travail, avec les fichiers qui accompagnent le SKILL.md. Elle se modifie et ne se met plus à jour depuis le dépôt.

​
Résolution des problèmes

​
Skills affiche « There are problems in » un dépôt relié

Un dépôt n’a pas pu se synchroniser ou contient des skills en échec. L’avertissement s’affiche au-dessus de la liste dans Settings → Skills, et seuls les administrateurs le voient. Cliquez sur View repositories et cherchez le dépôt en erreur.

​
Le dépôt affiche « Not synced since » suivi d’une heure

GitHub n’a pas répondu, l’App a perdu l’accès au dépôt, ou le dossier relié ne contient aucune skill. En attendant, Tuqui ne supprime et ne retire rien. Lisez le motif sous l’avertissement. Si l’App a perdu l’accès, ajoutez de nouveau le dépôt avec GitHub → Manage on GitHub. Cliquez ensuite sur Sync now.

​
Une skill affiche « Failed »

L’erreur du tableau indique le problème : frontmatter invalide, metadata.id absent ou en double, ou fichier qui dépasse une limite. Corrigez-le dans le dépôt et faites un merge. D’ici là, la dernière version valide reste en service.

​
Le dépôt n’apparaît pas au moment de le relier

L’App n’a pas accès à ce dépôt. Cliquez sur Your repo is not here? Give the app access on GitHub, ajoutez-le et rouvrez Link repository.