Skill format

Skill 格式

磁碟上

Skill 是一個資料夾。

必要項目：

• SKILL.md（或 skill.md；也接受舊版的 skills.md）

選用項目：

• 任何支援用的一般檔案（請參閱「Skill 檔案」）
• .clawhubignore（發布時的忽略模式，舊版為 .clawdhubignore）
• .gitignore（也會套用）

GitHub 匯入

網頁版 GitHub 匯入工具的限制比本機發布／同步更嚴格。它只會探索已登入 GitHub 帳號擁有的公開、非分支儲存庫中的 SKILL.md 或舊版 skills.md 檔案。它不會匯入私人儲存庫、分支、 已封存／停用的儲存庫或第三方公開儲存庫。

本機安裝中繼資料（由命令列介面寫入）：

• <skill>/.clawhub/origin.json（舊版為 .clawdhub）

工作目錄安裝狀態（由命令列介面寫入）：

• <workdir>/.clawhub/lock.json（舊版為 .clawdhub）

SKILL.md

• 含選用 YAML frontmatter 的 Markdown。
• 伺服器會在發布期間從 frontmatter 擷取中繼資料。
• description 會用作 UI／搜尋中的 Skill 摘要。

若要建立可攜式 Agent Skills，name 應與父目錄相符，並使用 1–64 個小寫字母、數字或連字號。ClawHub 會將可路由的 slug 與 目錄顯示名稱分開保存，因此其他用戶端的既有名稱仍可發布， 且不會遭到靜默改寫。目錄清單在視覺上可能會縮短過長的名稱， 但不會變更儲存的名稱。

Frontmatter 中繼資料

Skill 中繼資料是在 SKILL.md 頂端的 YAML frontmatter 中宣告。這會告知登錄檔（以及安全分析）你的 Skill 執行時需要什麼。

基本 frontmatter

---
name: my-skill
description: 此 Skill 功能的簡短摘要。
version: 1.0.0
---

執行階段中繼資料（metadata.openclaw）

在 metadata.openclaw 下宣告 Skill 的執行階段需求（別名：metadata.clawdbot、metadata.clawdis）。

---
name: my-skill
description: 透過 Todoist API 管理工作。
metadata:
  openclaw:
    requires:
      env:
        - TODOIST_API_KEY
      bins:
        - curl
    primaryEnv: TODOIST_API_KEY
---

針對 Skill 執行前必須存在的環境變數，請使用 requires.env。需要各變數的中繼資料時，請使用 envVars，包括使用 required: false 的選用變數。

完整欄位參考

欄位	類型	說明
requires.env	string[]	Skill 預期存在的必要環境變數。
requires.bins	string[]	必須全部安裝的命令列介面二進位檔。
requires.anyBins	string[]	至少必須存在一個的命令列介面二進位檔。
requires.config	string[]	Skill 讀取的設定檔路徑。
primaryEnv	string	Skill 的主要認證資訊環境變數。
envVars	array	含 name、選用的 required 及選用的 description 的環境變數宣告。選用環境變數請設定 required: false。
always	boolean	若為 true，Skill 將永遠啟用（不需要明確安裝）。
skillKey	string	覆寫 Skill 的叫用鍵。
emoji	string	Skill 的顯示表情符號。
homepage	string	Skill 首頁或文件的 URL。
os	string[]	作業系統限制（例如 ["macos"]、["linux"]）。
install	array	相依性安裝規格（請參閱下文）。
nix	object	Nix 外掛規格（請參閱 README）。
config	object	Clawdbot 設定規格（請參閱 README）。

安裝規格

若 Skill 需要安裝相依性，請在 install 陣列中宣告：

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

支援的安裝類型：brew、node、go、uv。

選用環境變數

在 metadata.openclaw.envVars 下宣告選用環境變數，並設定 required: false。請勿將選用項目新增至 requires.env，因為 requires.env 表示缺少這些變數時 Skill 無法執行。

metadata:
  openclaw:
    primaryEnv: TODOIST_API_KEY
    envVars:
      - name: TODOIST_API_KEY
        required: true
        description: 用於已驗證要求的 Todoist API 權杖。
      - name: TODOIST_PROJECT_ID
        required: false
        description: 使用者未指定時採用的選用預設專案 ID。

這為何重要

ClawHub 的安全分析會檢查 Skill 宣告的內容是否與其實際行為相符。如果程式碼參照 TODOIST_API_KEY，但 frontmatter 未在 requires.env、primaryEnv 或 envVars 下宣告，分析便會標記中繼資料不符。保持宣告準確有助於 Skill 通過審查，也能協助使用者瞭解他們正在安裝什麼。

範例：完整 frontmatter

---
name: todoist-cli
description: 從命令列管理 Todoist 工作、專案和標籤。
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 權杖。
      - name: TODOIST_PROJECT_ID
        required: false
        description: 選用的預設專案 ID。
    emoji: "\u2705"
    homepage: https://github.com/example/todoist-cli
---

Skill 檔案

發布接受 Skill 資料夾中的所有一般檔案，不限副檔名。忽略檔案、 隱藏路徑、符號連結、macOS 中繼資料及伺服器端大小限制仍然適用。

• 大小受限且包含有效 UTF-8 的檔案，可以逸出的純文字形式預覽，並納入 有限文字分析。
• 其他檔案會保留其確切位元組，並可供下載。
• 安全掃描器會收到完整的已儲存成品；文字偵測是呈現與 分析方面的考量，而不是上傳允許清單。

限制（伺服器端）：

• 套件組合總大小：50MB。
• 嵌入文字包含 SKILL.md + 最多約 40 個大小受限的 UTF-8 檔案（盡力而為的上限）。

Slug

• 預設衍生自資料夾名稱。
• 套件範圍必須與 ClawHub 發布者代號完全相符。發布者代號可使用小寫字母、數字、連字號、句點和底線；開頭與結尾必須是小寫字母或數字。
• 套件 slug 必須為小寫且符合 npm 安全格式，例如 @example.tools/demo-plugin 或 demo-plugin。

版本管理與標籤

• 每次發布都會建立新版本（semver）。
• 標籤是指向版本的字串指標；通常使用 latest。

授權條款

• 所有發布至 ClawHub 的 Skill 均依 MIT-0 授權。
• 任何人皆可使用、修改及重新散布已發布的 Skill，包括商業用途。
• 不要求標示出處。
• 請勿在 SKILL.md 中新增衝突的授權條款；ClawHub 不支援針對個別 Skill 覆寫授權條款。

付費 Skill

• ClawHub 不支援付費 Skill、個別 Skill 定價、付費牆或收益分潤。
• 請勿將定價中繼資料新增至 SKILL.md；該資料不屬於 Skill 格式，且不會使已發布的 Skill 成為付費項目。
• 如果 Skill 整合付費第三方服務，請在 Skill 指示與環境變數宣告中清楚記載外部費用和必要帳號（必要變數使用 requires.env，選用變數則使用 envVars 搭配 required: false）。