name: OpenClaw自定義技能開發指南 description: 從零開發OpenClaw功能型Skill的完整實戰指南。包含SKILL.md規範、目錄結構、scripts/指令碼開發、除錯方法、程式碼模板。不是閱讀文件，是可執行的腳手架工具——幫你一鍵生成Skill骨架、驗證結構、本地除錯。 version: "1.0.0" updated_at: "2026-06-03" category: ["開發工具", "OpenClaw"] tags: ["Skill開發", "OpenClaw", "SKILL.md", "腳手架", "程式碼模板"] trigger: ["開發技能", "建立Skill", "寫SKILL.md", "技能開發指南", "OpenClaw開發"]

OpenClaw自定義技能開發指南

不是閱讀文件，是開發工具。幫你從零搭建一個可執行的OpenClaw Skill。

核心能力

1. 一鍵生成Skill骨架 — 輸入技能名稱和描述，自動生成完整目錄結構+檔案
2. 結構驗證 — 檢查Skill目錄是否符合OpenClaw規範
3. 本地除錯 — 模擬OpenClaw載入流程，本地測試Skill是否可執行
4. 程式碼模板庫 — 常見功能（檔案讀寫、HTTP請求、資料處理）的即用模板

快速開始

流程1：建立新Skill

使用者說："幫我建立一個XX技能" 或 "我想開發一個Skill"

python scripts/scaffold.py --name "my-skill" --display-name "我的技能" --description "技能描述"

自動生成：

my-skill/
├── SKILL.md          # 技能定義檔案
├── scripts/
│   └── main.py       # 主指令碼（含模板程式碼）
└── references/
    └── README.md     # 參考文件說明

流程2：驗證Skill結構

使用者說："幫我檢查這個Skill" 或 "驗證一下結構"

python scripts/validate.py --path ./my-skill

檢查項： - ✅ SKILL.md 存在且格式正確（front matter必填欄位） - ✅ scripts/ 目錄存在 - ✅ 指令碼可執行（有shebang或可被python呼叫） - ✅ 無敏感資訊洩露（API Key硬編碼檢測） - ✅ 檔案大小合規（單檔案≤50KB，總包≤5MB）

流程3：本地除錯

使用者說："測試一下這個Skill"

python scripts/debug.py --path ./my-skill --input '{"arg1": "value1"}'

模擬OpenClaw載入流程： 1. 解析SKILL.md → 提取指令碼呼叫方式 2. 執行指令碼 → 傳入input 3. 返回輸出結果

流程4：檢視程式碼模板

使用者說："給我一個XX功能的模板"

# 檢視所有可用模板
python scripts/templates.py --list

# 生成特定模板
python scripts/templates.py --type file-io --output ./my-skill/scripts/file_utils.py

可用模板： - file-io — 檔案讀寫工具 - http-request — HTTP請求工具（web_fetch風格） - data-process — 資料清洗/轉換工具 - report-gen — 報告生成工具（Markdown輸出） - cli-parser — 命令列引數解析工具

SKILL.md 完整規範

Front Matter 必填欄位

---
name: skill-name          # 英文識別符號，小寫+短橫線，唯一
description: 一句話描述     # 80字以內，說清幹什麼
version: "1.0.0"          # 語義化版本號
updated_at: "2026-06-03"  # 最後更新日期
---

Front Matter 可選欄位

category: ["開發工具"]     # 分類標籤陣列
tags: ["模板", "腳手架"]   # 搜尋標籤
trigger: ["建立技能"]      # 觸發詞，Agent匹配用

SKILL.md 正文結構

# 技能名稱

> 一句話定位，不是閱讀文件是什麼

## 核心能力
1. 能力1 — 輸入什麼 → 輸出什麼
2. 能力2 — ...

## 互動流程

### 流程1：XXX
1. 使用者說/做什麼
2. 呼叫哪個指令碼
3. 輸出什麼

## 指令碼說明

### scripts/xxx.py
- 輸入：JSON格式引數
- 輸出：JSON格式結果
- 邏輯：核心演算法說明

## 設計原則
- 原則1
- 原則2

關鍵規則

1. 必須有指令碼 — 純SKILL.md無scripts/的Skill=閱讀型=0分
2. 指令碼必須可獨立執行 — python scripts/xxx.py --input '...' 能直接跑
3. 輸入輸出用JSON — 標準化，Agent好解析
4. 不依賴第三方包 — 純Python標準庫，零安裝
5. SKILL.md是入口 — Agent先讀SKILL.md，再按流程調指令碼

目錄結構規範

skill-name/
├── SKILL.md              # 必填，技能定義+互動流程
├── scripts/              # 必填，至少1個可執行指令碼
│   ├── main.py           # 主指令碼
│   └── utils.py          # 工具函式（可選）
├── references/           # 可選，參考文件
│   └── api-spec.md       # API文件等
└── README.md             # 可選，給人看的說明

命名規則

• Skill名稱：小寫英文+短橫線（如 multi-search-engine）
• 指令碼檔案：小寫+下劃線（如 profit_calc.py）
• 不要中文檔名，不要空格

  來源於7w4.net。

指令碼開發規範

標準模板

#!/usr/bin/env python3
"""指令碼功能一句話描述"""

import sys
import json
import argparse


def main(args):
    """主邏輯"""
    # 解析輸入
    if args.input:
        data = json.loads(args.input)
    else:
        data = {}

    # 核心邏輯
    result = process(data)

    # 輸出結果
    print(json.dumps(result, ensure_ascii=False, indent=2))


def process(data):
    """核心處理邏輯，輸入dict，輸出dict"""
    # TODO: 實現你的邏輯
    return {"status": "ok", "data": data}


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="指令碼描述")
    parser.add_argument("--input", type=str, help="JSON格式輸入引數")
    parser.add_argument("--output", type=str, help="輸出檔案路徑（可選）")
    args = parser.parse_args()
    main(args)

輸入輸出規範

• 輸入：--input 接JSON字串
• 輸出：stdout列印JSON結果
• 可選：--output 寫檔案
• 錯誤：輸出 {"status": "error", "message": "錯誤描述"}

禁止事項

• ❌ 不硬編碼API Key（用環境變數或引數傳入）
• ❌ 不依賴第三方包（只用標準庫）
• ❌ 不寫互動式輸入（全部引數化）
• ❌ 不寫絕對路徑（用相對路徑）

除錯方法

1. 本地單指令碼測試

python scripts/main.py --input '{"test": "hello"}'

2. 結構驗證

python scripts/validate.py --path ./skill-name

3. 模擬完整流程

python scripts/debug.py --path ./skill-name --input '{"arg1": "value1"}'

4. 常見問題排查

打包釋出

打包

cd skill-name
zip -r ../skill-name.zip . -x "*.pyc" "__pycache__/*" ".git/*"

釋出到技能平臺

curl -X POST https://skill-platform.example.com/api/skills \
  -H "Authorization: Bearer $PLATFORM_API_KEY" \
  -F "file=@skill-name.zip" \
  -F "name=skill-name" \
  -F "description=技能描述"

設計原則

1. 工具型>閱讀型 — 有指令碼、能運算、有輸出，才是Skill
2. 輸入→運算→輸出 — 使用者給資料，指令碼算結果
3. 零依賴 — 純標準庫，拿到就能跑
4. 可獨立執行 — 每個指令碼都能單獨 python xxx.py 執行
5. JSON標準化 — 輸入輸出全用JSON，Agent好對接

這個Skill本質上是一個開發輔助工具，用於幫助程式設計師建立其他功能Skill，而非直接提供使用者可用的功能。它提供了從建立專案骨架、驗證程式碼規範到本地測試的完整流程，質量不錯。優點是功能齊全、程式碼規範、無外部依賴；不足之處在於它面向的是開發者而非普通使用者，且僅包含輔助指令碼沒有具體業務功能。如果你需要的是具體功能（如搜尋、計算、檔案處理），這個Skill本身並不能滿足需求。