ClawTank
所有文章
如何建立自訂 OpenClaw Skills：完整開發者教學

如何建立自訂 OpenClaw Skills：完整開發者教學

|4 分鐘閱讀

OpenClaw 的 Skills 系統是它最強大的擴展機制。透過一個 SKILL.md 檔案，你可以教會 AI 助理全新的能力——從連接特定 API，到執行複雜的工作流程，到整合內部工具。

本文將從零開始，完整介紹 Skill 的開發流程：基本結構、指令撰寫、工具宣告、實際範例、測試方法和發佈流程。

什麼是 Skill

Skill 就是一份教 AI 助理「如何做某件事」的說明書。它的核心是一個 SKILL.md 檔案——一份 Markdown 文件，包含結構化的後設資料和自然語言的指令[1]。

當你說「幫我查匯率」時，OpenClaw 會找到匯率相關的 Skill，讀取指令，然後按照指令執行。

Skill 能做什麼

  • 呼叫外部 API（天氣、匯率、新聞等）
  • 操作檔案系統（讀取、寫入、轉換）
  • 執行 Shell 指令
  • 整合第三方服務（GitHub、Notion、Jira 等）
  • 定義複雜的多步驟工作流程

Skill 不是傳統的「程式碼外掛」——它不包含可執行程式碼，而是描述指令和工具使用方式，AI 基於這些描述決定如何行動[2]。

目錄結構

my-skill/
  SKILL.md          # 必要：Skill 定義檔
  README.md         # 建議：給人類讀的說明
  examples/         # 選配：使用範例
  tools/            # 選配：自訂工具腳本
  tests/            # 選配：測試案例

最簡單的情況下，你只需要一個 SKILL.md 檔案。

SKILL.md 結構詳解

YAML Frontmatter

---
name: currency-converter
version: 1.0.0
description: "即時匯率查詢與貨幣轉換"
author: "your-name"
tags: ["finance", "currency", "exchange-rate"]
triggers:
  - "匯率"
  - "換算"
  - "currency"
tools:
  - name: fetch
    description: "HTTP 請求工具"
config:
  api_key:
    description: "Exchange Rate API key (optional)"
    required: false
---
欄位 必要 說明
name 是 唯一識別名稱，kebab-case
version 是 語意化版本號
description 是 一句話描述功能
author 否 作者名稱
tags 否 分類標籤
triggers 否 觸發關鍵字
tools 否 需要的工具列表
config 否 使用者需提供的設定值

指令主體

Frontmatter 之後是自然語言的操作指令——Skill 最重要的部分：

# Currency Converter

你是一個匯率查詢和貨幣轉換助手。

## 行為規則

1. 使用者詢問匯率或貨幣轉換時啟用此 Skill
2. 使用 Exchange Rate API 獲取即時匯率
3. 結果必須包含：匯率、轉換金額、資料時間戳
4. API 不可用時，告知使用者並提供最近的已知匯率

## API 使用方式

基礎 URL: `https://api.exchangerate-api.com/v4/latest/`

回應格式：
```json
{
  "base": "USD",
  "rates": { "TWD": 32.15, "JPY": 149.50 }
}

回覆格式

  • 匯率顯示到小數點後 4 位
  • 金額轉換顯示到小數點後 2 位
  • 標註資料來源和更新時間
  • 未指定幣別時預設 TWD

### 撰寫原則

**越具體越好。** AI 不會讀心。希望匯率到小數點後 4 位，就明確寫出來。

**包含邊界情況。** API 不可用怎麼辦？幣別代碼錯誤怎麼辦？邊界情況處理越多，品質越高。

**示範優於描述。** 與其寫「以友善的方式回覆」，不如給一個實際範例。

## 工具宣告

OpenClaw 提供的內建工具<sup>[3]</sup>：

| 工具 | 說明 |
|------|------|
| `fetch` | HTTP 請求（API 呼叫、網頁抓取） |
| `shell` | 執行 Shell 指令 |
| `file_read` / `file_write` | 檔案讀寫 |
| `browser` | 瀏覽器操作 |
| `memory` | 記憶系統存取 |

自訂工具腳本放在 `tools/` 目錄，在指令中說明使用方式即可。

## 實際範例：GitHub Issue 管理 Skill

### SKILL.md

```yaml
---
name: github-issues
version: 1.0.0
description: "GitHub Issue 管理——列出、建立、更新和搜尋 Issues"
author: "openclaw-community"
tags: ["github", "issues", "development"]
triggers:
  - "github issue"
  - "bug report"
  - "建立 issue"
tools:
  - name: fetch
    description: "呼叫 GitHub API"
config:
  github_token:
    description: "GitHub Personal Access Token"
    required: true
  default_repo:
    description: "預設 repo (owner/repo)"
    required: false
---

# GitHub Issue Manager

你是一個 GitHub Issue 管理助手。

## 認證

所有 API 請求帶上 `Authorization: Bearer {github_token}`。

## 列出 Issues

API: `GET https://api.github.com/repos/{owner}/{repo}/issues`
參數：`state` (open/closed/all), `labels`, `sort`, `per_page` (預設 10)

## 建立 Issue

收集標題（必要）和描述（建議），未提供描述時根據標題自動生成。

API: `POST https://api.github.com/repos/{owner}/{repo}/issues`

建立前向使用者確認內容。建立成功後回報編號和連結。

## 搜尋 Issues

API: `GET https://api.github.com/search/issues?q={query}+repo:{owner}/{repo}`

## 錯誤處理

- 401: 提示重新設定 Token
- 404: Repo 不存在或無權限
- 403 (rate limit): 告知已達速率限制

## 安全規則

- 建立或修改前先確認
- 不要未經確認就關閉 Issue
- 未指定 repo 時使用 default_repo

安裝與測試

# 建立 Skill 目錄
mkdir -p ~/.openclaw/skills/github-issues
cp SKILL.md ~/.openclaw/skills/github-issues/

# 設定配置
openclaw config set skills.github-issues.github_token "ghp_your_token"
openclaw config set skills.github-issues.default_repo "your-org/your-repo"

# 重新載入
openclaw skills reload

# 確認安裝
openclaw skills list

測試時直接透過對話驗證：

你：列出 my-org/my-repo 的 open issues
你：建立一個 bug report：「登入頁面密碼欄位不接受特殊字元」

測試清單

  • 列出 open/closed issues
  • 建立 issue（只有標題 / 標題+描述+標籤）
  • 關閉和重新開啟 issue
  • 搜尋 issues
  • Token 過期、Repo 不存在等錯誤場景

進階技巧

使用記憶系統

## 記憶使用
- 記住使用者最常操作的 repo 作為預設值
- 記住偏好的 Issue 模板格式
- 儲存最近操作的 Issue 編號方便快速引用

多步驟工作流程

## Sprint Review 流程

當使用者說「sprint review」時：
1. 列出過去兩週關閉的 Issues
2. 按標籤分類統計
3. 找出仍 open 的高優先級 Issues
4. 生成 Sprint Review 摘要

智慧標籤

## 自動標籤

根據描述判斷：
- 含「壞了」「不能用」「錯誤」→ 加 `bug`
- 含「希望」「建議」→ 加 `enhancement`
- 含「緊急」「production」→ 加 `priority-high`

最佳實踐

觸發詞要精確

# 好的
triggers: ["github issue", "bug report", "feature request"]

# 太模糊（會和其他 Skill 衝突）
triggers: ["幫我", "查一下"]

提供範例對話

在 SKILL.md 中加入範例互動，幫助 AI 理解預期的回覆格式和風格。

定義安全邊界

明確列出 Skill 不應該做的事：不能未經確認就刪除資料、不能在 Issue 中包含敏感資訊、批量操作前必須確認。

處理設定缺失

當必要設定未提供時，引導使用者完成設定，包含具體的指令和連結。

發佈到 ClawHub

ClawHub 是 OpenClaw 的 Skill 市集[4]。

# 驗證格式
openclaw skills validate ./my-skill/SKILL.md

# 登入
openclaw hub login

# 發佈
openclaw hub publish ./my-skill/

# 更新
openclaw hub publish ./my-skill/ --update

品質指南：寫好 README、提供使用範例、測試主要功能、遵循語意化版本號、回應社群回饋。

如果你不想自己維護基礎設施來測試 Skills，ClawTank 提供即開即用的 OpenClaw 環境，方便快速迭代開發。

常見問題

Skill 沒被觸發： 確認觸發詞正確，或手動指定 使用 github-issues skill，列出 open issues。

工具呼叫失敗： 用 openclaw tools list 確認工具已啟用。

同步 Skills： Skills 在 ~/.openclaw/skills/ 目錄下，可以用 Git 管理或從 ClawHub 重裝。

總結

OpenClaw 的 Skills 系統用 Markdown 實現了強大的擴展能力。不需要寫複雜程式碼，用清楚的自然語言描述行為即可。從一個簡單的需求開始——查詢常用 API 或自動化重複工作——當你習慣了這個模式，你會發現 Skill 開發是 OpenClaw 最有趣的部分。

References

  1. OpenClaw Skills Documentation
  2. Understanding Prompt-Based Tool Use in AI Agents
  3. OpenClaw Built-in Tools Reference
  4. ClawHub Skill Registry
  5. Semantic Versioning Specification
  6. GitHub REST API Documentation

準備好部署 OpenClaw 了嗎？

不需要 Docker、SSH、DevOps。不到 1 分鐘即可部署。

免費開始使用