同一個 SKILL.md,兩種裝法 左邊是一張 SKILL.md 檔案卡片,分出兩條線:上面紅色的 OpenClaw 把所有技能塊整段塞進上下文視窗,塞滿後被一條豎虛線截斷,後面的變淡;下面紫色的 Claude Code 視窗分三層,第一層後設資料實心常駐,第二層正文虛線框按需載入,第三層引用檔案點線框用到再讀。 OpenClaw Claude Code SKILL.md --- name: … description: … ---

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 關注”能不能跑”——面向執行時環境:

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:

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 是預防型——安裝前掃描程式碼。 內建安全掃描器檢測技能目錄中的可疑模式:

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 檔案就能定義一個完整的自動化工作流。

六、總結

維度OpenClawClaude Code
技能載體SKILL.mdSKILL.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 基礎設施最樸素也最深刻的設計選擇。


參考資料

參考資料

  1. Extend Claude with skills — Claude Code收藏code.claude.comhttps://code.claude.com/docs/en/skills ↩

  2. Skills — OpenClaw收藏docs.openclaw.aihttps://docs.openclaw.ai/tools/skills ↩