建立技能

技能會教導代理程式如何以及何時使用工具。每個技能都是一個目錄，其中包含一個帶有 YAML frontmatter 和 markdown 指令的 SKILL.md 檔案。 OpenClaw 會依照定義的優先順序從多個根目錄載入技能。

建立您的第一個技能

建立技能目錄
技能位於您工作區的 skills/ 資料夾中。請為您的新技能建立一個目錄：
Terminal window
```
mkdir -p ~/.openclaw/workspace/skills/hello-world
```
您可以將技能組織在子資料夾中以方便管理 — 技能仍然由 SKILL.md frontmatter 命名，而非資料夾路徑：
Terminal window
```
mkdir -p ~/.openclaw/workspace/skills/personal/hello-world
# skill name is still "hello-world", invoked as /hello-world
```

撰寫 SKILL.md

在目錄中建立 SKILL.md。Frontmatter 定義中繼資料；本文則提供代理程式指令。

---
name: hello-world
description: A simple skill that prints a greeting.
---

# Hello World

When the user asks for a greeting, use the `exec` tool to run:

```bash
echo "Hello from your custom skill!"

命名規則：
- `name` 使用小寫字母、數字和連字號。
- 保持目錄名稱和 frontmatter `name` 一致。
- `description` 會顯示給代理程式並在斜線指令探索中顯示 —
  請將其保持在單行且不超過 160 個字元。

驗證技能已載入
Terminal window
```
openclaw skills list
```
OpenClaw 預設會監看技能根目錄下的 SKILL.md 檔案。如果監看功能已停用，或者您正在繼續現有的工作階段，請開啟一個新的工作階段，以便代理程式接收更新的清單：
Terminal window
```
# From chat — archive current session and start fresh
/new

# Or restart the gateway
openclaw gateway restart
```
測試它
發送一條應該觸發該技能的訊息：
Terminal window
```
openclaw agent --message "give me a greeting"
```
或者開啟一個聊天並直接詢問代理。使用 /skill hello-world 透過名稱明確調用它。

SKILL.md 參考

必填欄位

欄位	描述
`name`	使用小寫字母、數字和連字號的唯一識別碼
`description`	顯示給代理並在發現輸出中顯示的單行描述

可選的前置資料鍵

欄位	預設值	描述
`user-invocable`	`true`	將技能公開為使用者斜線指令
`disable-model-invocation`	`false`	將技能排除在代理的系統提示詞之外（仍可透過 `/skill` 執行）
`command-dispatch`	—	設定為 `tool` 以將斜線指令直接路由到工具，繞過模型
`command-tool`	—	當設定 `command-dispatch: tool` 時要調用的工具名稱
`command-arg-mode`	`raw`	對於工具分發，將原始參數字串轉發給工具
`homepage`	—	在 macOS 技能 UI 中顯示為「網站」的 URL

關於閘道欄位（requires.bins、requires.env 等），請參閱 Skills — Gating。

使用 `{baseDir}`

在技能主體中使用 {baseDir} 來引用技能目錄內的檔案，而無需硬編碼路徑：

Run the helper script at `{baseDir}/scripts/run.sh`.

新增條件啟用

為您的技能設定閘道，使其僅在依賴項可用時才載入：

---
name: gemini-search
description: Search using Gemini CLI.
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` 以跳過所有閘道並始終包含該技能

完整參考：Skills — Gating。

環境與 API 金鑰

將 API 金鑰連接到 openclaw.json 中的技能條目：

{
  skills: {
    entries: {
      "gemini-search": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
      },
    },
  },
}

金鑰僅針對該代理輪次注入到主機程序中。它不會到達沙箱 — 請參閱 sandboxed env vars。

透過 Skill Workshop 提議

對於由代理草擬的技能，或者當您希望在技能上線前由操作員進行審查時，請使用 Skill Workshop 提案，而不是直接撰寫 SKILL.md。

# Propose a brand-new skill
openclaw skills workshop propose-create \
  --name "hello-world" \
  --description "A simple skill that prints a greeting." \
  --proposal ./PROPOSAL.md

# Propose an update to an existing skill
openclaw skills workshop propose-update hello-world \
  --proposal ./PROPOSAL.md \
  --description "Updated greeting skill"

當提案包含支援檔案時，請使用 --proposal-dir：

openclaw skills workshop propose-create \
  --name "hello-world" \
  --description "A simple skill that prints a greeting." \
  --proposal-dir ./hello-world-proposal/

目錄必須包含 PROPOSAL.md。支援檔案可以放在 assets/、 examples/、references/、scripts/ 或 templates/ 中。

審查之後：

openclaw skills workshop inspect <proposal-id>
openclaw skills workshop apply <proposal-id>

請參閱 Skill Workshop 以了解完整的提案生命週期。

發佈到 ClawHub

確保您的 SKILL.md 已完成
確保 name、description 以及任何 metadata.openclaw 閘道欄位已設定。如果您有專案頁面，請新增 homepage URL。
安裝 ClawHub 技能
ClawHub 技能記錄了目前的發布指令形式以及必要的元資料：
Terminal window
```
openclaw skills install clawhub-publish
```
發布
Terminal window
```
clawhub publish
```
請參閱 ClawHub — Publishing 以了解完整流程。

建立技能

建立您的第一個技能

SKILL.md 參考

必填欄位

可選的前置資料鍵

使用 `{baseDir}`

新增條件啟用

透過 Skill Workshop 提議

發佈到 ClawHub

最佳實踐

相關

建立技能

建立您的第一個技能

SKILL.md 參考

必填欄位

可選的前置資料鍵

使用 {baseDir}

新增條件啟用

透過 Skill Workshop 提議

發佈到 ClawHub

最佳實踐

相關

使用 `{baseDir}`