--- read_when: - Skills veröffentlichen - Fehler bei der Veröffentlichung beheben summary: Format des Skills-Ordners, erforderliche Dateien, unterstützende Artefakte, Beschränkungen. x-i18n: generated_at: "2026-07-26T17:41:42Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 32 provider: openai source_hash: fdf16a589b8961ccd9181a53a9fa92a358952b9147d22eaf977f23e0b4b4d653 source_path: clawhub/skill-format.md workflow: 16 --- # 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): - `/.clawhub/origin.json` (veraltet: `.clawdhub`) Installationsstatus des Arbeitsverzeichnisses (von der CLI geschrieben): - `/.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 ```yaml --- name: my-skill description: 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`). ```yaml --- name: my-skill description: 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 | Feld | Typ | Beschreibung | | ------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `requires.env` | `string[]` | Erforderliche Umgebungsvariablen, die Ihr Skill erwartet. | | `requires.bins` | `string[]` | CLI-Binärdateien, die alle installiert sein müssen. | | `requires.anyBins` | `string[]` | CLI-Binärdateien, von denen mindestens eine vorhanden sein muss. | | `requires.config` | `string[]` | Pfade zu Konfigurationsdateien, die Ihr Skill liest. | | `primaryEnv` | `string` | Die primäre Anmeldedaten-Umgebungsvariable für Ihren Skill. | | `envVars` | `array` | Deklarationen von Umgebungsvariablen mit `name`, optionalem `required` und optionalem `description`. Legen Sie `required: false` für optionale Umgebungsvariablen fest. | | `always` | `boolean` | Wenn `true`, ist der Skill immer aktiv (keine explizite Installation erforderlich). | | `skillKey` | `string` | Überschreibt den Aufrufschlüssel des Skills. | | `emoji` | `string` | Anzeige-Emoji für den Skill. | | `homepage` | `string` | URL zur Homepage oder Dokumentation des Skills. | | `os` | `string[]` | Betriebssystembeschränkungen (z. B. `["macos"]`, `["linux"]`). | | `install` | `array` | Installationsspezifikationen für Abhängigkeiten (siehe unten). | | `nix` | `object` | Nix-Plugin-Spezifikation (siehe README). | | `config` | `object` | Clawdbot-Konfigurationsspezifikation (siehe README). | ### Installationsspezifikationen Wenn für Ihren Skill Abhängigkeiten installiert werden müssen, deklarieren Sie diese im Array `install`: ```yaml 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. ```yaml 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 ```yaml --- name: todoist-cli description: Todoist-Aufgaben, -Projekte und -Labels über die Befehlszeile verwalten. version: 1.2.0 metadata: 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).