Gestion des compétences Tracecat

Gérer les compétences Tracecat

Tracecat MCP fournit six outils de compétence : list_skills, get_skill, prepare_skill_download, prepare_skill_upload, complete_skill_upload et publish_skill.

Les écritures sont mises en scène, pas inline. Les octets des fichiers ne transitent jamais comme arguments d'outil : prepare_skill_upload ne prend que les métadonnées — chemin, SHA-256, taille, type de contenu — et renvoie une URL PUT de courte durée par fichier ; les octets vont vers ces URLs via HTTP simple ; complete_skill_upload attache ensuite les blobs mis en scène et remplace le brouillon. Ne cherchez pas un argument content_base64 inline et ne lisez jamais les octets des fichiers dans le contexte pour les envoyer.

Le script assistant fourni supprime les parties sujettes à erreur lorsqu'elles sont faites à la main : la navigation sécurisée dans les répertoires, le rejet des liens symboliques, l'imposition de la racine SKILL.md et les digest SHA-256.

Téléverser une compétence

Les quatre mêmes étapes créent une compétence ou remplacent une compétence existante. La seule différence réside dans les arguments d'identité que prend prepare_skill_upload.

1. Résolvez l'espace de travail cible avec list_workspaces, puis appelez list_skills. Pour une nouvelle compétence, confirmez que le nom est libre — omettre skill_id crée toujours une nouvelle ligne, donc une seconde création produit deux compétences avec le même name et des slugs différents. Pour une compétence existante, prenez son skill_id.

2. Construisez le tableau de métadonnées :

   python3 <ce-dossier-de-compétence>/scripts/upload_skill_files.py metadata <dossier-de-compétence-local>
   

   Il imprime le tableau files textuellement : une entrée par fichier avec path, sha256, size_bytes et content_type. Aucun contenu de fichier.

3. Appelez prepare_skill_upload avec workspace_id et ce tableau files, plus soit :

   • name (et éventuellement description) et pas de skill_id, pour créer une compétence ; ou
   • skill_id et pas de name/description, pour remplacer le brouillon d'une compétence existante.

   Pour une création, passez le même name que celui déclaré dans le frontmatter local — le serveur fusionne name et description dans le frontmatter stocké de SKILL.md racine avant de valider, donc un argument non concordant réécrit silencieusement ce qui est stocké.

   La réponse contient skill_id, base_revision, created, et pour chaque fichier upload_id, upload_url, method, headers et expires_at.

4. Envoyez (PUT) les octets bruts de chaque fichier vers son upload_url avec la méthode et les en-têtes retournés, directement depuis le disque. Les URLs ont une durée de vie courte ; vérifiez expires_at et re-préparez plutôt que de réessayer une URL périmée.

5. Appelez complete_skill_upload avec workspace_id, skill_id, le base_revision de l'étape 3, et un tableau files de {"path": ..., "upload_id": ...} pour chaque fichier. Ceci remplace le brouillon et ne publie pas.

6. Appelez publish_skill avec le skill_id lorsque la compétence doit pouvoir être attachée à des préréglages. Un brouillon non publié ne peut pas être lié.

base_revision est un verrou de concurrence. Une draft_revision_conflict signifie que quelqu'un d'autre a modifié le brouillon depuis l'étape 3 — appelez get_skill pour voir le draft_revision actuel et ce qu'un remplacement d'arbre complet supprimerait, puis re-préparez.

Mettre à jour une compétence en cours d'utilisation

Une correction qui s'arrête après complete_skill_upload ne change rien de ce qu'un agent exécute. Trois étapes, dans l'ordre :

1. prepare_skill_upload avec skill_id → PUT les octets → complete_skill_upload. Ceci remplace le brouillon. Cela ne publie pas.
2. publish_skill avec le même skill_id. Les compétences sont versionnées ; cela crée une nouvelle version immuable et déplace le current_version_id de la compétence.
3. update_agent_preset avec la liste skills du préréglage consommateur — les mêmes entrées {"skill_id": ...} qu'il avait déjà. Chaque liaison est ré-épinglée à la version publiée courante de cette compétence au moment de l'écriture, donc un préréglage lié avant l'étape 2 continue d'exécuter l'ancienne version jusqu'à ce que cet appel la réécrive.

Sauter l'étape 3 est l'échec classique : la nouvelle version existe, le préréglage ne la voit jamais.

Vérifiez en re-consultant. get_skill sans path renvoie le manifeste du brouillon — chemins, digests, tailles, draft_revision, is_publishable, validation_errors — et jamais le contenu des fichiers ; get_skill avec path lit un fichier, inline quand c'est un petit texte UTF-8. list_skills montre le current_version_id de la compétence ; get_agent_preset montre skills[].skill_version_id et skills[].skill_version. Confirmez que les deux ont bougé.

C'est un travail de routine et réversible. Chaque version publiée est immuable et encore liable, donc une mauvaise publication est annulée en publiant un arbre corrigé et en re-liant. Faites-le plutôt que de raconter les risques ; réservez la prudence pour les opérations qui ne peuvent vraiment pas être annulées.

Déclarer les outils de la compétence

Une compétence porte ses propres outils. Déclarez-les dans le frontmatter racine de SKILL.md sous metadata.tools, comme noms d'actions de registre ou entrées mcp.<slug> / mcp.<slug>.<tool>, jusqu'à 64 par compétence :

---
name: slack-triage
description: Publier et suivre les mises à jour de triage dans Slack.
metadata:
  tools:
    - tools.slack.post_message
    - tools.slack.list_replies
---

Chaque préréglage auquel la compétence est attachée reçoit ces outils en plus de sa propre liste d'autorisation actions. Ils sont accordés dès que le préréglage est résolu, que le modèle ouvre ou non la compétence ; seules les instructions de la compétence sont chargées à la demande.

Préférez cela à l'énumération des mêmes outils sur les actions de chaque préréglage lorsque les outils se regroupent naturellement et que plusieurs agents les réutilisent — une modification et une republication mettent alors à jour tous les préréglages consommateurs. Gardez un outil sur les actions du préréglage lorsqu'il est spécifique à cet agent.

Une mise en garde : le filtre namespaces d'un préréglage s'applique aux outils de registre dans l'union et bloque silencieusement ceux qui sont en dehors. Après avoir attaché une compétence à un préréglage restreint par namespace, vérifiez tool_policy.blocked_tools sur get_agent_preset. Les outils MCP qu'une compétence déclare (mcp.<slug> / mcp.<slug>.<tool>) ne sont pas filtrés par namespaces et n'apparaissent pas là.

Modifier metadata.tools change ce que les agents peuvent exécuter, donc cela suit les trois mêmes étapes que toute autre correction : remplacer le brouillon, publish_skill, puis update_agent_preset pour ré-épingler la liaison. Une lecture du préréglage résultant montre les outils accordés comme une liste plate dans tool_policy.actions, sans provenance par compétence — l'union est ce que vous pouvez vérifier.

Taille

Les octets ne passent plus par le contexte du modèle, mais chaque fichier a toujours une limite de taille côté serveur et un arbre complet est toujours plus facile à relire lorsqu'il est petit et textuel.

• Privilégiez le Markdown, le YAML et les scripts. Hébergez un gros fichier binaire ailleurs et référencez-le.
• Déplacez les détails longs dans des fichiers references/ que l'agent lit à la demande plutôt que dans SKILL.md.
• Si un arbre est trop grand pour être raisonné, divisez la compétence elle-même en deux compétences. Ne divisez pas un arbre en plusieurs appels complete_skill_upload — chaque appel remplace l'intégralité du brouillon, donc un appel partiel supprime tout ce qu'il omet.

Règles strictes

• Omettre skill_id crée ; le passer remplace. Ne créez jamais pour un nom qui existe déjà — la tentative de slug rend le doublon réussi au lieu d'échouer.
• Chaque écriture remplace l'intégralité du brouillon. Les fichiers absents du répertoire local sont supprimés de la compétence. Envoyez toujours l'arbre complet.
• Téléversez chaque fichier préparé avant d'appeler complete_skill_upload, et repassez chaque chemin avec son upload_id.
• N'inlinez jamais les octets d'un fichier ou du base64 dans un argument d'outil, et ne lisez jamais les octets d'une URL de téléversement ou de téléchargement dans le contexte. Fluez vers et depuis le disque.
• Publier ne déplace pas les liaisons de préréglage existantes. Réécrivez la liste skills du préréglage pour adopter une nouvelle version.
• Rejetez les fichiers et répertoires liés symboliquement, et n'envoyez jamais de contenu provenant de l'extérieur de la racine de compétence sélectionnée. Le script assistant applique cela ; ne le contournez pas.
• Le fichier racine doit être exactement SKILL.md, au niveau supérieur, et en UTF-8 valide. Le serveur rejette un ensemble de fichiers sans lui.
• Si le client ne peut pas exécuter de scripts locaux, dites-le et donnez à l'utilisateur la commande du script assistant à exécuter. Ne remplacez pas les digest générés par le modèle.

Références

• Lisez references/upload-contract.md pour les formes littérales des requêtes et réponses et ce que ce chemin protège ou non.
• Lisez references/troubleshooting.md lorsqu'un téléversement, une publication ou un re-lien de préréglage n'aboutit pas.