﻿---
lang: zh-TW
title: "技能即能力——OpenClaw 與 Claude Skills 機制對比"
description: "兩個 AI Agent 平臺不約而同選擇了 SKILL.md 作為技能載體，卻在後設資料設計、觸發邏輯、Token
  管理和安全模型上走向不同方向。本文以 Todo List 技能為貫穿案例，逐層拆解兩者的設計差異。"
pubDate: 2026-02-24
tags: [ "开源", "AI", "架构" ]
clc: "TP18"
hero: "./hero.zh-TW.svg"
refs:
  - id: "1"
    title: "Extend Claude with skills — Claude Code"
    url: "https://code.claude.com/docs/en/skills"
    collect: "claude-skills"
  - id: "2"
    title: "Skills — OpenClaw"
    url: "https://docs.openclaw.ai/tools/skills"
    collect: "openclaw-tools-skills"
---

Skill（技能）正在成為 AI Agent 平臺的核心抽象——一個可裝載、可組合的能力單元，讓 Agent 按需獲得領域專業性。

Claude Code 把 Skill 作為擴充套件能力的一等公民：一個 Markdown 檔案就是一個技能，放進目錄就自動生效[^1]。最近比較火的開源專案 OpenClaw 同樣以 Skill 為核心組織 Agent 能力[^2]。兩者不約而同選擇了同一個載體——`SKILL.md`，卻在機制設計上走向了不同的方向。

本文以一個 Todo List 技能為貫穿案例，對比兩者從設計到實現的差異。

## 一、一個技能，兩種實現

需求很簡單：用本地 JSON 檔案儲存待辦事項，支援增刪改查。

兩個平臺做了同一個決定：**一個 `SKILL.md` 檔案 = 一個技能**。YAML frontmatter 宣告後設資料，Markdown body 就是技能本身——寫給 AI 的"操作手冊"。下面分別是 OpenClaw 和 Claude Code 兩個版本的完整實現：

**OpenClaw 版 — `skills/todo/SKILL.md`：**

```yaml
---
name: todo
description: "Local todo list management with JSON file storage"
metadata:
  openclaw:
    emoji: "✅"
    requires: { bins: ["jq"] }
    install:
      - kind: brew
        formula: jq
---
# Todo List Skill

Manage a local todo list stored in `~/.todo.json`.

## File Format
JSON array of objects: `[{"id": 1, "text": "买牛奶", "done": false, "created": "2025-01-01"}]`

## Operations
- **Add**: append new item with auto-increment id
- **List**: show all items, optionally filter by done/undone
- **Done**: mark item as completed by id
- **Remove**: delete item by id

Use `jq` for all JSON manipulation. Example:
`jq '. += [{"id": (map(.id) | max + 1), "text": $text, "done": false}]' --arg text "$TEXT" ~/.todo.json`
```

**Claude Code 版 — `.claude/skills/todo/SKILL.md`：**

```yaml
---
name: todo
description: >
  Use this skill when the user wants to manage tasks or todos.
  Trigger phrases: "add a todo", "my task list", "mark as done",
  "what's left to do", "帮我记一下", "还有什么没做",
  "待办事项", "任务列表".
user-invocable: true
---
# Todo List Skill

Manage a local todo list stored in `~/.todo.json`.

## File Format
JSON array: `[{"id": 1, "text": "买牛奶", "done": false, "created": "2025-01-01"}]`

## Operations
- **Add**: Read file → append item with auto-increment id → write back
- **List**: Read file → format as table, group by status
- **Done**: Read file → flip `done` flag by id → write back
- **Remove**: Read file → filter out by id → write back

Always use the Read and Write tools for file operations. Create `~/.todo.json` with `[]` if it doesn't exist.

For detailed schema and migration guide, see `references/schema.md`.
For bulk import/export, run `scripts/import-export.sh`.
```

兩個檔案做的事一模一樣，但 frontmatter 的側重點已經顯露差異：OpenClaw 宣告執行時依賴（`jq`）和安裝方式；Claude Code 填滿觸發短語，並引用 `references/` 和 `scripts/` 做漸進式披露。

接下來我們圍繞這個案例，逐層拆解兩者在發現機制、後設資料設計、觸發邏輯、Token 管理、安全模型和擴充套件生態上的差異。

## 二、技能的骨架：定義、發現與組織

### 發現機制

兩者都選擇了"基於檔案系統的自動發現"，不需要顯式註冊程式碼。但發現的來源和優先順序差異很大。

**OpenClaw 從 6 個目錄逐層載入技能**，後者覆蓋前者：

```typescript
// workspace.ts — 优先级从低到高
for (const skill of extraSkills)    merged.set(skill.name, skill);  // 最低
for (const skill of bundledSkills)  merged.set(skill.name, skill);
for (const skill of managedSkills)  merged.set(skill.name, skill);
for (const skill of personalAgentsSkills) merged.set(skill.name, skill);
for (const skill of projectAgentsSkills)  merged.set(skill.name, skill);
for (const skill of workspaceSkills) merged.set(skill.name, skill); // 最高
```

使用者可以在專案 `skills/` 下放一個同名技能覆蓋內建版本。內建技能達 **54 個**，涵蓋 GitHub、Discord、Slack、Notion、1Password、Spotify 等。

**Claude Code 同樣以目錄為單位組織**，支援全域性和專案兩層：

```
~/.claude/skills/               # 全局技能（跨项目可用）
└── skill-name/
    ├── SKILL.md                # 技能定义
    ├── references/             # 参考文档
    └── scripts/                # 可执行脚本

.claude/skills/                 # 项目级技能（仅当前项目）
└── skill-name/
    └── SKILL.md
```

放一個 `SKILL.md` 到對應目錄，技能就自動生效——支援熱過載，自動出現在 `/` 斜槓命令選單中。此外，Claude Code 還有一個**外掛**機制，可以將 commands、agents、skills、hooks 打包成一個可分發的整體，但這是可選的高階功能，普通使用者不需要理解外掛概念。

**核心差異**：兩者都是**目錄級獨立實體**，都支援多層覆蓋。OpenClaw 有 6 層優先順序疊加 + 54 個內建技能，覆蓋面更廣；Claude Code 是全域性/專案兩層 + 外掛可選擴充套件，結構更簡潔。

比如我們的 todo 技能，OpenClaw 使用者放到 `skills/todo/SKILL.md`，它就出現在 6 層覆蓋的某一層——如果內建也有同名技能，專案級的會覆蓋內建版本；Claude Code 使用者放到 `~/.claude/skills/todo/SKILL.md`（全域性）或 `.claude/skills/todo/SKILL.md`（專案級），下次對話自動生效。兩種放法，同一個結果：目錄即註冊。

### 後設資料設計

兩者的 frontmatter 反映了截然不同的關注點。

**OpenClaw 關注"能不能跑"**——面向執行時環境：

```typescript
// types.ts
export type OpenClawSkillMetadata = {
  always?: boolean;        // 始终加载，无视配置
  os?: string[];           // 操作系统限制
  requires?: {
    bins?: string[];       // 必须存在的二进制（AND 关系）
    anyBins?: string[];    // 至少存在一个（OR 关系）
    env?: string[];        // 必须的环境变量
  };
  install?: SkillInstallSpec[];  // 自动安装指令
};
```

技能宣告"我需要 `gh` 命令列工具"，不存在時 OpenClaw 還知道如何幫你裝——brew、npm、go、uv 或直接下載：

```typescript
export type SkillInstallSpec = {
  kind: "brew" | "node" | "go" | "uv" | "download";
  formula?: string;   // brew install gh
  package?: string;   // npm install xxx
  url?: string;       // 直接下载
};
```

**Claude Code 關注"該不該用"**——面向觸發語義，並採用**漸進式披露**設計：

```yaml
description: This skill should be used when the user asks to
  "create a hook", "add a PreToolUse hook", "validate tool use",
  or mentions hook events (PreToolUse, PostToolUse, Stop).
```

| 層級 | 內容 | 何時載入 | 大小限制 |
|------|------|----------|---------|
| 後設資料 | name + description | 始終在上下文中 | ~100 詞 |
| SKILL.md body | 核心指導 | 觸發短語匹配時 | 1500–2000 詞 |
| references/ | 詳細文件 | 按需讀取 | 無限制 |
| scripts/ | 可執行指令碼 | 直接執行，無需讀入 | 無限制 |

後設資料永遠載入（開銷極低），完整技能只在被觸發時才注入 prompt——一種**上下文視窗友好型**設計。

回到我們的 todo 技能：OpenClaw 版宣告 `requires: { bins: ["jq"] }`——如果機器上沒有 jq，它知道用 `brew install jq` 幫你裝。Claude Code 版則在 description 裡寫滿觸發詞——使用者說"幫我記一下"、"我的任務列表"、"還有什麼沒做"，模型都能匹配上。同一個技能，一個操心"能不能跑"，一個操心"該不該觸發"。

## 三、技能的觸發與 Token 管理

### 呼叫機制

**OpenClaw 是命令驅動**——把每個技能註冊為斜槓命令，使用者直接輸入 `/github pr list`：

```typescript
// skill-commands.ts
export function resolveSkillCommandInvocation(params) {
  // 解析 /skillname args 或 /skill skillname args
  const match = trimmed.match(/^\/([^\s]+)(?:\s+([\s\S]+))?$/);
  if (commandName === "skill") {
    // /skill github pr list → 查找 github 技能
  }
}
```

還有一個雙通道設計——技能可以被使用者呼叫，也可以被模型自動呼叫，兩個方向獨立控制：

```typescript
export type SkillInvocationPolicy = {
  userInvocable: boolean;           // 用户能否用 /命令 调用
  disableModelInvocation: boolean;  // 模型能否自动使用
};
```

**Claude Code 同樣支援斜槓命令**——技能預設 `user-invocable: true`，自動註冊為 `/skill-name` 命令出現在選單中，使用者可以直接呼叫。但它還多了一層**語義匹配**——模型會根據 description 中的觸發短語自動判斷是否需要載入：

```yaml
description: This skill should be used when the user asks to
  "create an agent", "add an agent", "write a subagent",
  "agent frontmatter", "agent examples", "agent tools"...
```

也支援在命令或 agent 流程中顯式載入：

```markdown
<!-- create-plugin 命令中 -->
**MUST load plugin-structure skill** using Skill tool before this phase.
```

**核心差異**：兩者都支援 `/命令` 式顯式呼叫。不同的是，OpenClaw 僅靠命令派發 + 模型呼叫雙通道；Claude Code 在此基礎上增加了語義匹配——即使使用者沒有輸入 `/` 命令，模型也能根據意圖自動載入相關技能。

拿 todo 技能舉例：OpenClaw 使用者輸入 `/todo add 买牛奶`，命令解析器匹配到 todo 技能，注入 prompt。Claude Code 使用者可以 `/todo add 买牛奶`（走斜槓命令），也可以直接說"幫我記一下，明天要買牛奶"——模型看到 description 裡的觸發短語匹配，自動載入技能。同一個意圖，一個靠使用者記住命令名，一個靠模型理解自然語言。

### Token 管理策略

兩者都面臨同一個工程問題：**技能越多，prompt 越長，token 越貴**。

**OpenClaw：全量注入 + 硬上限截斷。** 設定明確的上限，超出時用二分搜尋找到能放進去的最大子集：

```typescript
const DEFAULT_MAX_SKILLS_IN_PROMPT = 150;       // 最多 150 个技能
const DEFAULT_MAX_SKILLS_PROMPT_CHARS = 30_000;  // 最多 3 万字符

if (!fits(skillsForPrompt)) {
  let lo = 0, hi = skillsForPrompt.length;
  while (lo < hi) {
    const mid = Math.ceil((lo + hi) / 2);
    fits(skillsForPrompt.slice(0, mid)) ? lo = mid : hi = mid - 1;
  }
  skillsForPrompt = skillsForPrompt.slice(0, lo);
}
```

還有一個小最佳化——路徑壓縮，把 `/Users/alice/.bun/.../SKILL.md` 縮為 `~/.bun/.../SKILL.md`，每個路徑省 5–6 token。

**Claude Code：三層按需載入。** 不是"全塞進去再截斷"，而是分級注入：

```
skill-name/
├── SKILL.md              ← 触发时加载（~2000 词）
├── references/            ← 按需读取（无限制）
│   ├── patterns.md
│   └── advanced.md
└── scripts/               ← 直接执行，不读入上下文
    └── validate.sh
```

以 todo 技能為例，三層載入的實際內容是：`SKILL.md` 只寫核心操作指南——增刪改查的 JSON 操作方式、檔案路徑約定；`references/schema.md` 放詳細的資料格式文件（欄位定義、狀態列舉、版本相容規則）；`scripts/migrate.sh` 放版本遷移指令碼——使用者說"升級我的 todo 格式"時直接執行，不佔上下文視窗。同一個技能，只有使用者實際觸發時才載入核心指南，深層文件和指令碼始終按需。

## 四、安全與配置

### 安全模型

**OpenClaw 是預防型——安裝前掃描程式碼。** 內建安全掃描器檢測技能目錄中的可疑模式：

```typescript
// skill-scanner.ts
const LINE_RULES = [
  { ruleId: "dangerous-exec", severity: "critical",
    pattern: /\b(exec|execSync|spawn|spawnSync)\s*\(/,
    requiresContext: /child_process/ },
  { ruleId: "dynamic-code-execution", severity: "critical",
    pattern: /\beval\s*\(|new\s+Function\s*\(/ },
  { ruleId: "crypto-mining", severity: "critical",
    pattern: /stratum\+tcp|coinhive|cryptonight|xmrig/i },
];

const SOURCE_RULES = [
  { ruleId: "env-harvesting", severity: "critical",
    message: "Environment variable access + network send",
    pattern: /process\.env/,
    requiresContext: /\bfetch\b|\bpost\b|http\.request/i },
];
```

還阻止技能設定 `LD_PRELOAD`、`OPENSSL_CONF` 等危險環境變數。

**Claude Code 是攔截型——執行時驗證行為。** 安全模型建立在 Hooks 機制上，在工具執行前/後插入檢查點：

```json
{
  "PreToolUse": [{
    "matcher": "Write|Edit",
    "hooks": [{
      "type": "prompt",
      "prompt": "Validate file write safety. Check: system paths,
        credentials, path traversal. Return 'approve' or 'deny'."
    }]
  }]
}
```

鉤子可以是 `prompt`（讓 LLM 判斷）或 `command`（執行指令碼），還有許可權清單從全域性層面控制工具訪問：

```json
{ "permissions": { "deny": ["WebSearch", "WebFetch"], "ask": ["Bash"] } }
```

回到 todo 技能：OpenClaw 掃描 `skills/todo/` 目錄，如果發現技能檔案中有 `exec()` 呼叫或網路請求，會在安裝時報警。Claude Code 則透過 Hooks 在執行時攔截——比如 todo 技能嘗試寫入 `~/.todo.json` 以外的路徑時，PreToolUse 鉤子可以阻止操作。

### 配置管理

**OpenClaw 用 YAML 集中管理**所有技能的開關、API Key、環境變數：

```yaml
skills:
  allowBundled: [github, discord]
  entries:
    notion:
      enabled: true
      apiKey: secret_xxx
      env: { NOTION_TOKEN: ntn_xxx }
    discord:
      enabled: false
```

背後的型別系統支撐了細粒度控制：

```typescript
export type SkillsConfig = {
  allowBundled?: string[];                // 内置技能白名单
  load?: { extraDirs?: string[]; watch?: boolean };
  limits?: SkillsLimitsConfig;
  entries?: Record<string, SkillConfig>;  // 逐技能配置
};
```

**Claude Code 的配置跟隨外掛**，透過 `plugin.json` 清單宣告，執行時配置用 `.claude/plugin-name.local.md` 或環境變數，路徑引用統一使用 `${CLAUDE_PLUGIN_ROOT}` 保持可移植性。

## 五、擴充套件生態與命令模板

### 建立與分發

建立一個技能有多簡單？以我們的 todo 技能為例：

**OpenClaw**：`mkdir skills/todo && vim skills/todo/SKILL.md`，寫入內容，儲存——下次啟動自動發現。還可以透過外掛清單批次宣告技能路徑：

```json
{
  "id": "my-plugin",
  "skills": ["skills/todo", "skills/my-other-skill"]
}
```

**Claude Code**：`mkdir -p .claude/skills/todo && vim .claude/skills/todo/SKILL.md`，寫入內容，儲存——熱過載，立刻出現在 `/` 斜槓命令選單。無需任何註冊程式碼。

對於需要批次分發的場景，Claude Code 提供了**外掛**作為高階打包機制——一個外掛可以同時包含命令、agent、技能、鉤子和 MCP 伺服器：

```
my-plugin/
├── .claude-plugin/plugin.json  # 清单
├── commands/review.md          # /review 斜杠命令
├── agents/code-reviewer.md     # 专业子 agent
├── skills/api-testing/SKILL.md # 技能
├── hooks/hooks.json            # 事件钩子
└── .mcp.json                   # MCP 服务器集成
```

其中 MCP 整合值得一提——外掛可以啟動外部 MCP 伺服器，將外部 API 變成 Claude 可呼叫的工具：

```json
{
  "database-tools": {
    "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
    "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
    "env": { "DB_URL": "${DB_URL}" }
  }
}
```

但請注意：外掛是**可選的分發機制**，不是使用技能的前提。絕大多數使用者只需要 `SKILL.md` 這一個檔案。

### 命令模板：Claude Code 的獨特設計

Claude Code 有一個 OpenClaw 中沒有的概念——**Command 模板**。命令是寫給 Claude 的指令，支援動態內容插值：

```markdown
---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
description: Create a git commit
---

## Context
- Current git status: !`git status`
- Current git diff: !`git diff HEAD`
- Recent commits: !`git log --oneline -10`

## Your task
Based on the above changes, create a single git commit.
```

注意 `` !`git status` `` 語法——backtick 包裹的命令會在模板渲染時實際執行，結果內聯到 prompt 中。`$ARGUMENTS` 變數承載使用者傳入的引數。一個 Markdown 檔案就能定義一個完整的自動化工作流。

## 六、總結

| 維度 | OpenClaw | Claude Code |
|------|----------|-------------|
| **技能載體** | `SKILL.md` | `SKILL.md` |
| **技能組織** | 獨立實體，多來源層疊 | 獨立實體，全域性/專案兩層 |
| **發現機制** | 6 層目錄，顯式優先順序覆蓋 | 全域性/專案目錄掃描 + 外掛可選 |
| **後設資料重點** | 執行時依賴（bins/env/os） | 語義觸發（trigger phrases） |
| **呼叫方式** | `/命令` 派發 + 模型呼叫 | `/命令` + 模型語義匹配 + Skill tool |
| **Token 管理** | 全量注入 + 上限截斷 | 三層漸進式載入 |
| **安全模型** | 靜態程式碼掃描 + 環境變數阻斷 | 事件鉤子 + 許可權清單 |
| **配置方式** | YAML 集中配置 | 目錄約定 + 外掛清單（可選） |
| **擴充套件模型** | 外掛宣告技能路徑 | 目錄放置即生效 + 全棧外掛可選 |
| **內建技能數** | 54 個 | 少量內建 + 外掛市場擴充套件 |
| **依賴管理** | 宣告依賴 + 自動安裝 | 手動確保依賴 |
| **命令模板** | 無 | 支援動態插值 |

兩個專案從同一個起點出發——SKILL.md——在使用者層面的體驗其實相當接近：都是往目錄裡放一個 Markdown 檔案，技能就自動生效，都支援 `/命令` 呼叫，都不需要編寫註冊程式碼。

差異不在組織方式，而在**後設資料設計**和 **Token 管理策略**：

**OpenClaw** 的後設資料面向**執行時環境**——技能宣告自己需要哪些二進位制、哪些環境變數、在哪些作業系統上可用，甚至還知道如何幫你安裝缺失的依賴。54 個內建技能覆蓋開發者和消費者場景，讓 AI Agent 成為跨平臺的多面手。Token 管理策略是"全量注入 + 硬上限截斷"——簡單直接。

**Claude Code** 的後設資料面向**語義觸發**——description 中寫滿觸發短語，讓模型自主判斷何時載入。Token 管理策略是"三層漸進式披露"——後設資料始終在場，SKILL.md 按需載入，references 延遲讀取——一種上下文視窗友好型設計。外掛機制則提供了可選的高階打包能力。

一個強調**執行時能力**，一個強調**認知效率**。

但最終它們共享了同一個洞見：**Skill 是 AI Agent 從"通用"走向"專業"的關鍵抽象**。不是靠更大的模型、更長的上下文，而是靠一個個 Markdown 檔案，把人類的領域知識和工作流程，變成 AI 可以按需裝載的能力模組。

技能即能力。檔案系統即能力倉庫。這或許是 AI Agent 基礎設施最樸素也最深刻的設計選擇。

---

## 參考資料
