anhhung04/tracecat-manage-skills

Tracecat-Skills verwalten

Tracecat MCP enthält sechs Skill-Tools: list_skills, get_skill, prepare_skill_download, prepare_skill_upload, complete_skill_upload und publish_skill.

Schreibvorgänge werden gestaffelt, nicht direkt durchgeführt. Dateibytes werden niemals als Tool-Argumente übertragen: prepare_skill_upload nimmt nur Metadaten entgegen – Pfad, SHA-256, Größe, Inhaltstyp – und gibt eine kurzlebige PUT-URL pro Datei zurück; die Bytes werden über einfaches HTTP an diese URLs gesendet; complete_skill_upload fügt dann die gestaffelten Blobs an und ersetzt den Entwurf. Suchen Sie nicht nach einem Inline-content_base64-Argument und lesen Sie niemals Dateibytes in den Kontext, um sie zu senden.

Das gebündelte Hilfsprogramm entfernt die Teile, die von Hand fehleranfällig sind: den sicheren Verzeichnisdurchlauf, die Ablehnung von Symlinks, die Erzwingung der Stammdatei SKILL.md und die SHA-256-Prüfsummen.

Einen Skill hochladen

Die gleichen vier Schritte erstellen einen Skill und ersetzen einen vorhandenen. Der einzige Unterschied besteht darin, welche Identitätsargumente prepare_skill_upload erwartet.

1. Lösen Sie den Ziel-Workspace mit list_workspaces auf, rufen Sie dann list_skills auf. Bestätigen Sie bei einem neuen Skill, dass der Name frei ist – das Weglassen von skill_id erzeugt immer eine neue Zeile, sodass ein zweites Erstellen zwei Skills mit demselben name und unterschiedlichen Slugs ergibt. Nehmen Sie bei einem vorhandenen Skill dessen skill_id.

2. Erstellen Sie das Metadaten-Array:

   python3 <this-skill-dir>/scripts/upload_skill_files.py metadata <local-skill-dir>
   

   Es gibt das files-Array unverändert aus: ein Eintrag pro Datei mit path, sha256, size_bytes und content_type. Keine Dateiinhalte.

3. Rufen Sie prepare_skill_upload mit workspace_id und diesem files-Array auf, plus entweder:

   • name (und optional description) und keine skill_id, um einen Skill zu erstellen; oder
   • skill_id und keine name-description, um den Entwurf eines vorhandenen Skills zu ersetzen.

   Verwenden Sie bei einer Erstellung denselben name, den das lokale Frontmatter deklariert – der Server führt name und description mit dem gespeicherten Stamm-Frontmatter der SKILL.md zusammen, bevor er validiert, sodass ein nicht übereinstimmendes Argument stillschweigend das überschreibt, was gespeichert wird.

   Die Antwort enthält skill_id, base_revision, created sowie pro Datei upload_id, upload_url, method, headers und expires_at.

4. Senden Sie per PUT die Rohbytes jeder Datei an ihre upload_url mit der zurückgegebenen Methode und den Headern, direkt von der Diskette. Die URLs sind kurzlebig; überprüfen Sie expires_at und bereiten Sie sie erneut vor, anstatt eine veraltete erneut zu versuchen.

5. Rufen Sie complete_skill_upload mit workspace_id, skill_id, der base_revision aus Schritt 3 und einem files-Array von {"path": ..., "upload_id": ...} für jede Datei auf. Dadurch wird der Entwurf ersetzt und nicht veröffentlicht.

6. Rufen Sie publish_skill mit der skill_id auf, wenn der Skill an Voreinstellungen angebunden werden können soll. Ein unveröffentlichter Entwurf kann nicht gebunden werden.

base_revision ist eine Nebenläufigkeitssperre. Ein draft_revision_conflict bedeutet, dass jemand anderer den Entwurf seit Schritt 3 bearbeitet hat – rufen Sie get_skill auf, um die aktuelle draft_revision zu sehen und was eine vollständige Baumersetzung löschen würde, und bereiten Sie dann erneut vor.

Aktualisieren eines Live-Skills

Ein Fix, der nach complete_skill_upload aufhört, ändert nichts, was ein Agent ausführt. Drei Schritte in der richtigen Reihenfolge:

1. prepare_skill_upload mit skill_id → PUT der Bytes → complete_skill_upload. Dies ersetzt den Entwurf. Es veröffentlicht nicht.
2. publish_skill mit derselben skill_id. Skills werden versioniert; dies erstellt eine neue unveränderliche Version und verschiebt die current_version_id des Skills.
3. update_agent_preset mit der verbrauchenden Voreinstellung skills-Liste – denselben {"skill_id": ...}-Einträgen, die sie bereits hatte. Jede Bindung wird zum Zeitpunkt des Schreibens auf die aktuell veröffentlichte Version dieses Skills neu fixiert, sodass eine Voreinstellung, die vor Schritt 2 gebunden wurde, die alte Version weiter ausführt, bis dieser Aufruf sie neu schreibt.

Das Auslassen von Schritt 3 ist der klassische Fehler: die neue Version existiert, die Voreinstellung sieht sie nie.

Überprüfen Sie dies durch erneutes Abrufen. get_skill ohne path gibt das Entwurfsmanifest zurück – Pfade, Prüfsummen, Größen, draft_revision, is_publishable, validation_errors – und niemals Dateiinhalte; get_skill mit path liest eine Datei inline, wenn es sich um kleinen UTF-8-Text handelt. list_skills zeigt die current_version_id des Skills an; get_agent_preset zeigt skills[].skill_version_id und skills[].skill_version. Bestätigen Sie, dass beide verschoben wurden.

Dies ist eine routinemäßige, umkehrbare Arbeit. Jede veröffentlichte Version ist unveränderlich und weiterhin bindbar, sodass ein schlechter Push durch Veröffentlichen eines korrigierten Baums und erneutes Binden rückgängig gemacht wird. Tun Sie es, anstatt Risiken zu beschreiben; sparen Sie sich Vorsicht für Operationen auf, die tatsächlich nicht rückgängig gemacht werden können.

Deklarieren der Tools des Skills

Ein Skill bringt seine eigenen Tools mit. Deklarieren Sie sie im Frontmatter der Stammdatei SKILL.md unter metadata.tools als Registry-Aktionsnamen oder mcp.<slug> / mcp.<slug>.<tool>-Einträge, bis zu 64 pro Skill:

---
name: slack-triage
description: Erstellen und Thread-Triage-Updates in Slack posten.
metadata:
  tools:
    - tools.slack.post_message
    - tools.slack.list_replies
---

Jede Voreinstellung, an die der Skill angebunden ist, erhält diese Tools zusätzlich zu ihrer eigenen actions-Whitelist. Sie werden gewährt, sobald die Voreinstellung aufgelöst wird, unabhängig davon, ob das Modell den Skill öffnet; nur die Anweisungen des Skills werden bei Bedarf geladen.

Bevorzugen Sie dies gegenüber dem Auflisten derselben Tools in den actions jeder Voreinstellung, wenn die Tools natürlich zusammengehören und mehrere Agenten sie wiederverwenden – eine Bearbeitung und eine erneute Veröffentlichung aktualisiert dann jede verbrauchende Voreinstellung. Behalten Sie ein Tool in den actions der Voreinstellung, wenn es für diesen einen Agenten spezifisch ist.

Ein Vorbehalt: Der namespaces-Filter einer Voreinstellung gilt für die Registry-Tools in der Vereinigung und blockiert stillschweigend diejenigen außerhalb. Überprüfen Sie nach dem Anbinden eines Skills an eine namespace-beschränkte Voreinstellung tool_policy.blocked_tools bei get_agent_preset. MCP-Tools, die ein Skill deklariert (mcp.<slug> / mcp.<slug>.<tool>), werden nicht durch namespaces gefiltert und erscheinen nicht dort.

Das Ändern von metadata.tools ändert, welche Tools Agenten ausführen können, daher folgt es den gleichen drei Schritten wie jeder andere Fix: Ersetzen Sie den Entwurf, publish_skill, dann update_agent_preset, um die Bindung neu zu fixieren. Ein Lesen der resultierenden Voreinstellung zeigt die gewährten Tools als eine flache Liste in tool_policy.actions, ohne Herkunft pro Skill – die Vereinigung ist das, was Sie überprüfen können.

Größe

Bytes durchlaufen nicht mehr den Modellkontext, aber jede Datei hat dennoch eine serverseitige Größenbeschränkung und ein ganzer Baum ist immer noch einfacher zu überprüfen, wenn er klein und nur aus Text besteht.

• Bevorzugen Sie Markdown, YAML und Skripte. Hosted Sie ein großes binäres Asset woanders und verweisen Sie darauf.
• Verschieben Sie ausführliche Details in references/-Dateien, die der Agent bei Bedarf liest, anstatt in die SKILL.md.
• Wenn ein Baum zu groß ist, um ihn zu überblicken, teilen Sie den Skill selbst in zwei Skills auf. Teilen Sie keinen Baum auf mehrere complete_skill_upload-Aufrufe auf – jeder Aufruf ersetzt den gesamten Entwurf, sodass ein teilweiser Aufruf alles löscht, was er auslässt.

Harte Regeln

• Das Weglassen von skill_id erstellt; das Übergeben ersetzt. Erstellen Sie niemals gegen einen Namen, der bereits existiert – der Slug-Wiederholungsversuch lässt das Duplikat gelingen, anstatt zu fehlschlagen.
• Jeder Schreibvorgang ersetzt den gesamten Entwurf. Dateien, die im lokalen Verzeichnis fehlen, werden aus dem Skill gelöscht. Senden Sie immer den vollständigen Baum.
• Laden Sie jede vorbereitete Datei hoch, bevor Sie complete_skill_upload aufrufen, und übergeben Sie jeden Pfad mit seiner upload_id zurück.
• Betten Sie Dateibytes oder base64 niemals inline in ein Tool-Argument ein und lesen Sie niemals Bytes einer Upload- oder Download-URL in den Kontext. Streamen Sie auf die Festplatte und von der Festplatte.
• Das Veröffentlichen verschiebt keine vorhandenen Voreinstellungsbindungen. Schreiben Sie die skills-Liste der Voreinstellung neu, um eine neue Version zu übernehmen.
• Lehnen Sie Dateien und Verzeichnisse mit symbolischen Links ab und senden Sie niemals Inhalte von außerhalb des ausgewählten Skill-Stammverzeichnisses. Das Hilfsprogramm erzwingt dies; umgehen Sie es nicht.
• Die Stammdatei muss exakt SKILL.md heißen, sich auf der obersten Ebene befinden und gültiges UTF-8 sein. Der Server lehnt einen Dateisatz ohne diese ab.
• Wenn der Client keine lokalen Skripte ausführen kann, sagen Sie dies und geben Sie dem Benutzer den Hilfsprogrammbefehl zur Ausführung. Ersetzen Sie keine modellgenerierten Prüfsummen.

Referenzen

• Lesen Sie references/upload-contract.md für die wörtlichen Anfrage- und Antwortformen und was dieser Pfad schützt und was nicht.
• Lesen Sie references/troubleshooting.md, wenn ein Upload, eine Veröffentlichung oder ein erneutes Binden einer Voreinstellung nicht funktioniert.