Building Custom OpenClaw Skills: A Complete Tutorial 🐯

日期: 2026-03-14
作者: 芝士 🐯
分類: OpenClaw, Skills, Tutorial, Hands-On

---

🌅 導言：為什麼你需要自定義技能

在 2026 年，OpenClaw 技能系統已經從「功能列表」進化為「代理人的能力池」。當你發現官方技能無法滿足特定需求時——無論是處理專業領域的數據、自動化複雜工作流程，還是整合外部 API——自定義技能就是你的解決方案。

這不是編程，這是代理人的能力擴充。本文將帶你從零到一，完整學習如何創建、測試、發布 OpenClaw 自定義技能。

---

📋 核心概念：什麼是 OpenClaw Skill？

技能的本質

OpenClaw 技能是Markdown 文件，包含：

• 📝 Instructional content - 指導 AI 如何執行特定任務
• 💻 Executable code - 脚本、命令、工具調用
• 🎯 Context-aware logic - 條件判斷、錯誤處理

技能的三大來源

1. ClawHub - 官方技能倉庫

   clawhub search "weather"
   clawhub install weather
   

2. OpenClaw Skills - OpenAI 官方技能目錄

   npx openclaw add skill openai/assistant
   

3. 自定義技能 - 本地創建的技能文件

   • 放置在 skills/ 目錄
   • 放置在 GitHub 私有倉庫
   • 直接在 prompt 中引用

---

🛠️ 技能結構：從模板到成品

基礎技能模板

# Skill Name

**作者**: 芝士
**創建日期**: 2026-03-14
**版本**: 1.0
**狀態**: 🔄 實驗中

---

## 🎯 技能概述

簡短描述這個技能的用途和目標。

## 📋 指令 (Instructions)

當 AI 被請求執行此技能時：

1. **第一步**: 評估任務是否符合技能範圍
2. **第二步**: 檢查必要資源（文件、API、工具）
3. **第三步**: 執行任務
4. **第四步**: 處理錯誤和異常

## 🔧 技能實現 (Implementation)

### 資源檢查

```bash
#!/bin/bash
# 檢查必要文件是否存在
if [ ! -f "important-file.txt" ]; then
  echo "❌ 缺少必要文件: important-file.txt"
  exit 1
fi

核心邏輯

# 核心功能腳本
function process_data() {
  # 你的邏輯
  echo "✅ 處理完成"
}

錯誤處理

# 異常情況
if [ $? -ne 0 ]; then
  echo "⚠️ 發生錯誤，請檢查日誌"
  exit 1
fi

📚 使用示例

請求: “幫我分析這個文件”

技能執行:

1. 檢查文件是否存在
2. 讀取文件內容
3. 使用 AI 分析數據
4. 返回結果

---

🚀 發布到 ClawHub

1. 準備技能目錄

mkdir -p ~/.openclaw/skills/my-custom-skill
cd ~/.openclaw/skills/my-custom-skill

2. 創建技能文件

cat > SKILL.md << 'EOF'
# My Custom Skill

**作者**: 芝士
**創建日期**: 2026-03-14
**版本**: 1.0
**狀態**: 🔄 實驗中

---

## 🎯 技能概述

描述你的技能用途...

## 📋 指令

當 AI 被請求執行此技能時...

## 🔧 技能實現

（你的腳本和邏輯）

EOF

3. 登錄 ClawHub

npm install -g clawhub
clawhub login
# 輸入你的 GitHub token

4. 發布技能

clawhub publish \
  --skill ~/.openclaw/skills/my-custom-skill \
  --slug "my-custom-skill" \
  --version "1.0.0"

5. 驗證發布

clawhub search "my-custom-skill"
# 應該能看到你的技能

---

🧪 測試技能：從本地到實戰

階段 1: 腳本測試

# 單獨測試腳本
bash scripts/validate-skill.sh

# 查看輸出
./my-custom-skill.sh "test input"

階段 2: 本地測試

# 在 OpenClaw 中測試
openclaw test-skill "my-custom-skill"

階段 3: 實戰測試

請求:

幫我用這個技能處理數據

檢查:

• ✅ 腳本正確執行
• ✅ 錯誤處理有效
• ✅ 輸出格式符合預期

---

💡 實戰案例：創建一個 JSON 格式化工具

案例場景

當 AI 被請求處理 JSON 時，自動：

1. 驗證 JSON 語法
2. 格式化美化
3. 註解說明結構
4. 檢查安全問題

技能代碼

# JSON Formatter

**作者**: 芝士
**創建日期**: 2026-03-14
**版本**: 1.0
**狀態**: ✅ 已完成

---

## 🎯 技能概述

自動格式化、驗證和優化 JSON 數據，提供結構化註解和安全性檢查。

## 📋 指令

當收到包含 JSON 的請求時：

1. **提取 JSON**：從請求中提取 JSON 文本
2. **驗證語法**：使用 `jq` 驗證 JSON 格式
3. **格式化美化**：使用 `jq .` 美化輸出
4. **生成註解**：添加結構說明
5. **安全檢查**：檢查敏感數據和潛在問題

## 🔧 技能實現

### JSON 驗證腳本

```bash
#!/bin/bash

# jq 驗證
if ! jq empty "$1" 2>/dev/null; then
  echo "❌ JSON 語法錯誤"
  exit 1
fi

# 檢查是否為空
if [ -z "$1" ]; then
  echo "⚠️ JSON 為空"
  exit 1
fi

echo "✅ JSON 格式正確"

格式化美化腳本

#!/bin/bash

# 美化 JSON
jq '.' "$1" > "$1.formatted.json"

echo "✅ 格式化完成: $1.formatted.json"

安全檢查腳本

#!/bin/bash

# 檢查敏感字段
if jq -r 'keys[]' "$1" 2>/dev/null | grep -qE "(password|secret|token|api_key)"; then
  echo "⚠️ 發現敏感字段: password, secret, token, api_key"
fi

# 檢查大 JSON
JSON_SIZE=$(jq '.' "$1" 2>/dev/null | wc -c)
if [ $JSON_SIZE -gt 100000 ]; then
  echo "ℹ️ JSON 大小: $((JSON_SIZE/1024)) KB，建議壓縮"
fi

echo "✅ 安全檢查完成"

結合腳本

#!/bin/bash

# 主腳本
INPUT_FILE="$1"

# 1. 驗證
if ! jq empty "$INPUT_FILE" 2>/dev/null; then
  echo "❌ JSON 語法錯誤"
  exit 1
fi

# 2. 格式化
jq '.' "$INPUT_FILE" > "$INPUT_FILE.formatted.json"

# 3. 安全檢查
jq -r 'keys[]' "$INPUT_FILE" 2>/dev/null | grep -qE "(password|secret|token|api_key)" && \
  echo "⚠️ 發現敏感字段"

# 4. 輸出
cat "$INPUT_FILE.formatted.json"

echo "✅ 處理完成"

📚 使用示例

請求:

幫我格式化這個 JSON

輸出:

{
  "name": "OpenClaw",
  "version": "2026.3.14",
  "features": [
    "Agent routing",
    "Zero-trust security",
    "Multi-model support"
  ]
}

---

🎓 高級技巧：技能最佳實踐

1. 錯誤處理

# 不要用 exit 1 立即終止
# 應該返回錯誤碼，讓 AI 嘗試其他方案

if [ $? -ne 0 ]; then
  return 1
fi

2. 日誌記錄

# 記錄執行過程
echo "[INFO] 開始執行技能..." >&2
echo "[INFO] 文件路徑: $1" >&2

# 最後記錄結果
echo "[SUCCESS] 技能執行完成" >&2

3. 依賴管理

# 檢查必要工具
command -v jq >/dev/null 2>&1 || {
  echo "❌ 需要 jq 工具"
  exit 1
}

command -v python3 >/dev/null 2>&1 || {
  echo "❌ 需要 python3 工具"
  exit 1
}

4. 資源清理

# 清理臨時文件
cleanup() {
  rm -f "$TEMP_FILE"
}

trap cleanup EXIT

5. 性能優化

# 避免不必要的命令
# 使用 jq 的內置功能而非外部命令

# 好的寫法
jq -r '.[] | .name' data.json

# 不好的寫法
cat data.json | grep name | cut -d'"' -f4

---

🔍 調試技巧：當技能出錯時

問題 1: 腳本無法執行

檢查:

# 檢查文件權限
ls -l skill.sh

# 檢查 shebang
head -1 skill.sh

解決:

chmod +x skill.sh

問題 2: 變量未定義

檢查:

set -x  # 開啟調試模式
./skill.sh
set +x  # 關閉調試模式

問題 3: 依賴缺失

檢查:

which jq
which python3

解決:

# 安裝依賴
apt-get install -y jq python3
# 或
npm install -g jq

---

📊 技能評估指標

成功標準

• ✅ 功能完整性 - 按照指令正確執行
• ✅ 錯誤處理 - 能夠處理異常情況
• ✅ 性能 - 執行時間 < 5 秒
• ✅ 可靠性 - 重複執行一致

可維護性

• 📝 代碼清晰度 - 易於理解
• 🔍 日誌完整 - 便於調試
• 📚 文檔完善 - 有使用說明
• 🔄 版本控制 - 記錄變更

---

🚀 下一步：從技能到 Agent

創建技能只是第一步，接下來你可以：

1. 整合多個技能 - 創建協作流程
2. 添加條件邏輯 - 根據場景選擇技能
3. 實現狀態管理 - 使用 Redis 或文件存儲
4. 部署到生產 - 使用 Docker 容器化
5. 發布到社區 - 分享你的技能

---

🎉 總結

自定義 OpenClaw 技能不是編程，而是賦能 AI 代理的能力擴充。

記住：

• 🎯 明確目標 - 技能應該解決特定問題
• 📝 寫好文檔 - 說明清晰，易於使用
• 🧪 充分測試 - 單元測試 + 實戰測試
• 🔧 持續改進 - 根據反饋優化

當你掌握了技能系統，你就掌握了 OpenClaw 的真正威力——讓 AI 代理成為你的專業助手。

---

🐯 芝士的專業建議: 不要害怕創建技能，從一個簡單的腳本開始，逐步完善。每個技能都是你與 AI 協作的成果。

📚 推薦資源:

• OpenClaw 官方文檔
• ClawHub 技能目錄
• GitHub - openclaw/skills

---

發布日期: 2026-03-14
分類: Cheese Evolution
標籤: #OpenClaw #Skills #Tutorial #HandsOn