Skill-Format

Auf dem Datenträger

Ein Skill ist ein Ordner.

Erforderlich:

• SKILL.md (oder skill.md; das veraltete skills.md wird ebenfalls akzeptiert)

Optional:

• beliebige unterstützende reguläre Dateien (siehe „Skill-Dateien“)
• .clawhubignore (Ignoriermuster für die Veröffentlichung, veraltet: .clawdhubignore)
• .gitignore (wird ebenfalls berücksichtigt)

GitHub-Import

Der webbasierte GitHub-Importer ist strenger als die lokale Veröffentlichung/Synchronisierung. Er erkennt nur SKILL.md- oder veraltete skills.md-Dateien in öffentlichen Repositorys ohne Fork-Status, die dem angemeldeten GitHub-Konto gehören. Er importiert keine privaten Repositorys, Forks, archivierten/deaktivierten Repositorys oder öffentlichen Repositorys Dritter.

Lokale Installationsmetadaten (von der CLI geschrieben):

• <skill>/.clawhub/origin.json (veraltet: .clawdhub)

Installationsstatus des Arbeitsverzeichnisses (von der CLI geschrieben):

• <workdir>/.clawhub/lock.json (veraltet: .clawdhub)

SKILL.md

• Markdown mit optionalem YAML-Frontmatter.
• Der Server extrahiert während der Veröffentlichung Metadaten aus dem Frontmatter.
• description wird als Zusammenfassung des Skills in der Benutzeroberfläche/Suche verwendet.

Für portable Agent Skills sollte name mit dem übergeordneten Verzeichnis übereinstimmen und aus 1–64 Kleinbuchstaben, Ziffern oder Bindestrichen bestehen. ClawHub verwaltet den routingfähigen Slug und den Anzeigenamen im Katalog getrennt, sodass vorhandene Namen aus anderen Clients weiterhin veröffentlicht und nicht stillschweigend umgeschrieben werden können. Kataloglisten können lange Namen visuell kürzen, ohne den gespeicherten Namen zu ändern.

Frontmatter-Metadaten

Skill-Metadaten werden im YAML-Frontmatter am Anfang Ihrer SKILL.md deklariert. Dadurch erfährt die Registry (und die Sicherheitsanalyse), was Ihr Skill zur Ausführung benötigt.

Grundlegendes Frontmatter

---name: my-skilldescription: Kurze Zusammenfassung der Funktion dieses Skills.version: 1.0.0---

Laufzeitmetadaten (metadata.openclaw)

Deklarieren Sie die Laufzeitanforderungen Ihres Skills unter metadata.openclaw (Aliasse: metadata.clawdbot, metadata.clawdis).

---name: my-skilldescription: Aufgaben über die Todoist-API verwalten.metadata:  openclaw:    requires:      env:        - TODOIST_API_KEY      bins:        - curl    primaryEnv: TODOIST_API_KEY---

Verwenden Sie requires.env für Umgebungsvariablen, die vorhanden sein müssen, bevor der Skill ausgeführt werden kann. Verwenden Sie envVars, wenn Sie Metadaten pro Variable benötigen, einschließlich optionaler Variablen mit required: false.

Vollständige Feldreferenz

Installationsspezifikationen

Wenn für Ihren Skill Abhängigkeiten installiert werden müssen, deklarieren Sie diese im Array install:

metadata:  openclaw:    install:      - kind: brew        formula: jq        bins: [jq]      - kind: node        package: typescript        bins: [tsc]

Unterstützte Installationsarten: brew, node, go, uv.

Optionale Umgebungsvariablen

Deklarieren Sie optionale Umgebungsvariablen unter metadata.openclaw.envVars und legen Sie required: false fest. Fügen Sie requires.env keine optionalen Einträge hinzu, da requires.env bedeutet, dass der Skill ohne sie nicht ausgeführt werden kann.

metadata:  openclaw:    primaryEnv: TODOIST_API_KEY    envVars:      - name: TODOIST_API_KEY        required: true        description: Todoist-API-Token für authentifizierte Anfragen.      - name: TODOIST_PROJECT_ID        required: false        description: Optionale Standard-Projekt-ID, wenn keine angegeben wird.

Warum dies wichtig ist

Die Sicherheitsanalyse von ClawHub prüft, ob die Deklarationen Ihres Skills seinem tatsächlichen Verhalten entsprechen. Wenn Ihr Code auf TODOIST_API_KEY verweist, Ihr Frontmatter diese Variable jedoch nicht unter requires.env, primaryEnv oder envVars deklariert, kennzeichnet die Analyse dies als Metadatenabweichung. Korrekte Deklarationen helfen Ihrem Skill, die Prüfung zu bestehen, und erleichtern Benutzern das Verständnis dessen, was sie installieren.

Beispiel: vollständiges Frontmatter

---name: todoist-clidescription: Todoist-Aufgaben, -Projekte und -Labels über die Befehlszeile verwalten.version: 1.2.0metadata:  openclaw:    requires:      env:        - TODOIST_API_KEY      bins:        - curl    primaryEnv: TODOIST_API_KEY    envVars:      - name: TODOIST_API_KEY        required: true        description: Todoist-API-Token.      - name: TODOIST_PROJECT_ID        required: false        description: Optionale Standard-Projekt-ID.    emoji: "\u2705"    homepage: https://github.com/example/todoist-cli---

Skill-Dateien

Die Veröffentlichung akzeptiert alle regulären Dateien im Skill-Ordner unabhängig von ihrer Erweiterung. Ignorierdateien, versteckte Pfade, symbolische Links, macOS-Metadaten und serverseitige Größenbeschränkungen gelten weiterhin.

• Dateien innerhalb der Größenbegrenzung, die gültiges UTF-8 enthalten, können als maskierter Klartext in der Vorschau angezeigt werden und werden in die begrenzte Textanalyse einbezogen.
• Andere Dateien behalten ihre exakten Bytes bei und können heruntergeladen werden.
• Sicherheitsscanner erhalten das vollständige gespeicherte Artefakt; die Texterkennung betrifft die Darstellung und Analyse und ist keine Positivliste für Uploads.

Grenzwerte (serverseitig):

• Gesamtgröße des Bundles: 50MB.
• Der Einbettungstext umfasst SKILL.md und bis zu etwa 40 UTF-8-Dateien innerhalb der Größenbegrenzung (Best-Effort-Obergrenze).

Slugs

• Standardmäßig aus dem Ordnernamen abgeleitet.
• Paket-Scopes müssen exakt mit dem ClawHub-Publisher-Handle übereinstimmen. Publisher-Handles dürfen Kleinbuchstaben, Ziffern, Bindestriche, Punkte und Unterstriche enthalten; sie müssen mit einem Kleinbuchstaben oder einer Ziffer beginnen und enden.
• Paket-Slugs müssen kleingeschrieben und npm-kompatibel sein, beispielsweise @example.tools/demo-plugin oder demo-plugin.

Versionierung und Tags

• Jede Veröffentlichung erstellt eine neue Version (SemVer).
• Tags sind Zeichenkettenverweise auf eine Version; latest wird häufig verwendet.

Lizenz

• Alle auf ClawHub veröffentlichten Skills werden unter MIT-0 lizenziert.
• Jeder darf veröffentlichte Skills verwenden, ändern und weiterverbreiten, auch kommerziell.
• Eine Namensnennung ist nicht erforderlich.
• Fügen Sie in SKILL.md keine widersprüchlichen Lizenzbedingungen hinzu; ClawHub unterstützt keine individuellen Lizenzüberschreibungen pro Skill.

Kostenpflichtige Skills

• ClawHub unterstützt keine kostenpflichtigen Skills, individuellen Preise pro Skill, Bezahlschranken oder Umsatzbeteiligungen.
• Fügen Sie SKILL.md keine Preismetadaten hinzu; diese sind nicht Teil des Skill-Formats und machen einen veröffentlichten Skill nicht kostenpflichtig.
• Wenn Ihr Skill einen kostenpflichtigen Drittanbieterdienst integriert, dokumentieren Sie die externen Kosten und das erforderliche Konto deutlich in den Skill-Anweisungen und Umgebungsvariablendeklarationen (requires.env für erforderliche Variablen oder envVars mit required: false für optionale Variablen).