> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # 建立 Skills Skills 會教導代理程式如何以及何時使用工具。每個 Skill 都是一個目錄， 其中包含具有 YAML frontmatter 和 Markdown 指示的 `SKILL.md` 檔案。 OpenClaw 會依照定義的[優先順序](/zh-TW/tools/skills#loading-order)，從多個根目錄載入 Skills。 ## 建立你的第一個 Skill Skills 位於你工作區的 `skills/` 資料夾中： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} mkdir -p ~/.openclaw/workspace/skills/hello-world ``` 你可以將 Skills 分組放在子資料夾中，以便整理；Skill 仍由 `SKILL.md` frontmatter 命名，而不是由資料夾路徑命名： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} mkdir -p ~/.openclaw/workspace/skills/personal/hello-world # Skill 名稱仍為 "hello-world"，使用 /hello-world 呼叫 ``` frontmatter 定義中繼資料；本文則提供代理程式指示。 ````markdown theme={"theme":{"light":"min-light","dark":"min-dark"}} --- name: hello-world description: 一個會輸出問候語的簡單 Skill。 --- # Hello World 當使用者要求問候語時，使用 `exec` 工具執行： ```bash echo "來自你的自訂 Skill 的問候！" ```` ```` 命名規則： - `name` 僅可使用小寫字母、數字和連字號。 - 目錄名稱與 frontmatter 的 `name` 應保持一致。 - `description` 會顯示給代理程式，也會出現在斜線命令探索結果中； 請保持為單行且少於 160 個字元。 ```bash openclaw skills list ```` OpenClaw 預設會監看 Skills 根目錄下的 `SKILL.md` 檔案。如果 監看器已停用，或你正在繼續現有工作階段，請啟動新的工作階段， 讓代理程式收到更新後的清單： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # 從聊天中封存目前工作階段並重新開始 /new # 或重新啟動閘道 openclaw gateway restart ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw agent --message "給我一句問候語" ``` 或開啟聊天，直接向代理程式提出要求。使用 `/skill hello-world` 依名稱明確呼叫它。 ## SKILL.md 參考資料 ### 必填欄位 | 欄位 | 說明 | | ------------- | --------------------- | | `name` | 使用小寫字母、數字和連字號的唯一 slug | | `description` | 顯示給代理程式並出現在探索輸出中的單行說明 | ### 選用 frontmatter 鍵 | 欄位 | 預設值 | 說明 | | -------------------------- | ------- | ---------------------------------------- | | `user-invocable` | `true` | 將 Skill 公開為使用者斜線命令 | | `disable-model-invocation` | `false` | 不將 Skill 放入代理程式的系統提示詞中（仍可透過 `/skill` 執行） | | `command-dispatch` | — | 設為 `tool`，將斜線命令直接路由至工具並略過模型 | | `command-tool` | — | 設定 `command-dispatch: tool` 時要呼叫的工具名稱 | | `command-arg-mode` | `raw` | 進行工具分派時，將原始引數字串轉送給工具 | | `homepage` | — | 在 macOS Skills 使用者介面中顯示為「Website」的 URL | 如需閘控欄位（`requires.bins`、`requires.env` 等）的資訊，請參閱 [Skills — 閘控](/zh-TW/tools/skills#gating)。 ### 使用 `{baseDir}` 在 Skill 目錄中參照檔案，而不必寫死路徑；代理程式會以 Skill 自身的目錄 解析 `{baseDir}`： ```markdown theme={"theme":{"light":"min-light","dark":"min-dark"}} 執行位於 `{baseDir}/scripts/run.sh` 的輔助指令碼。 ``` ## 新增條件式啟用 為你的 Skill 設定閘控，使其僅在相依項目可用時載入： ```markdown theme={"theme":{"light":"min-light","dark":"min-dark"}} --- name: gemini-search description: 使用 Gemini 命令列介面搜尋。 metadata: { "openclaw": { "requires": { "bins": ["gemini"] }, "primaryEnv": "GEMINI_API_KEY" } } --- ``` | 鍵 | 說明 | | ------------------ | ------------------------------------------ | | `requires.bins` | 所有二進位檔都必須存在於 `PATH` 上 | | `requires.anyBins` | 至少一個二進位檔必須存在於 `PATH` 上 | | `requires.env` | 每個環境變數都必須存在於程序或設定中 | | `requires.config` | 每個 `openclaw.json` 路徑都必須為真值 | | `os` | 平台篩選器：`["darwin"]`、`["linux"]`、`["win32"]` | | `always` | 設定 `true` 以略過所有閘控，並一律納入該 Skill | 完整參考資料：[Skills — 閘控](/zh-TW/tools/skills#gating)。 在 `openclaw.json` 中將 API 金鑰連接至 Skill 項目： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { skills: { entries: { "gemini-search": { enabled: true, apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, }, }, }, } ``` 該金鑰只會在那次代理程式回合中注入主機程序。 它不會進入沙箱；請參閱 [沙箱化的環境變數](/zh-TW/tools/skills-config#sandboxed-skills-and-env-vars)。 ## 透過 Skill Workshop 提案 若是由代理程式草擬的 Skills，或你希望 Skill 上線前先由操作者審查， 請使用 [Skill Workshop](/zh-TW/tools/skill-workshop) 提案，而不要直接寫入 `SKILL.md`。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # 提案建立全新的 Skill openclaw skills workshop propose-create \ --name "hello-world" \ --description "一個會輸出問候語的簡單 Skill。" \ --proposal ./PROPOSAL.md # 提案更新現有 Skill openclaw skills workshop propose-update hello-world \ --proposal ./PROPOSAL.md \ --description "已更新的問候 Skill" ``` 當提案包含支援檔案時，請使用 `--proposal-dir`： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw skills workshop propose-create \ --name "hello-world" \ --description "一個會輸出問候語的簡單 Skill。" \ --proposal-dir ./hello-world-proposal/ ``` 該目錄的根目錄中必須包含 `PROPOSAL.md`。支援檔案應放在 `assets/`、`examples/`、`references/`、`scripts/` 或 `templates/` 下。 審查後： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw skills workshop inspect openclaw skills workshop apply ``` 完整的提案生命週期請參閱 [Skill Workshop](/zh-TW/tools/skill-workshop)。 ## 發布至 ClawHub 請確認已設定 `name`、`description` 及所有 `metadata.openclaw` 閘控欄位。 如果你有專案頁面，請新增 `homepage` URL。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} npm i -g clawhub clawhub login ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} clawhub skill publish ./path/to/hello-world ``` 新增 `--version ` 或 `--owner `，即可覆寫推斷的 版本或以特定擁有者身分發布。如需完整流程、擁有者範圍及其他 維護命令（`clawhub sync`、`clawhub skill rename` 等），請參閱 [ClawHub — 發布](/zh-TW/clawhub/publishing)和 [ClawHub 命令列介面](/zh-TW/clawhub/cli)。 ## 最佳實務 * **保持精簡** — 指示模型要做*什麼*，而不是如何成為 AI。 * **安全優先** — 如果你的 Skill 使用 `exec`，請確保提示詞不會允許 不受信任的輸入任意注入命令。 * **在本機測試** — 分享前使用 `openclaw agent --message "..."`。 * **使用 ClawHub** — 從頭建置前，先到 [clawhub.ai](https://clawhub.ai) 瀏覽社群 Skills。 ## 相關資源 載入順序、閘控、允許清單及 SKILL.md 格式。 由代理程式草擬之 Skills 的提案佇列。 完整的 `skills.*` 設定結構描述。 在公開登錄檔中瀏覽及發布 Skills。 外掛可將 Skills 與其所記載的工具一同提供。