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:
---name: tododescription: "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 FormatJSON 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:
---name: tododescription: > 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 FormatJSON 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 個目錄逐層載入技能,後者覆蓋前者:
// 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 關注”能不能跑”——面向執行時環境:
export type OpenClawSkillMetadata = { always?: boolean; // 始终加载,无视配置 os?: string[]; // 操作系统限制 requires?: { bins?: string[]; // 必须存在的二进制(AND 关系) anyBins?: string[]; // 至少存在一个(OR 关系) env?: string[]; // 必须的环境变量 }; install?: SkillInstallSpec[]; // 自动安装指令};技能宣告”我需要 gh 命令列工具”,不存在時 OpenClaw 還知道如何幫你裝——brew、npm、go、uv 或直接下載:
export type SkillInstallSpec = { kind: "brew" | "node" | "go" | "uv" | "download"; formula?: string; // brew install gh package?: string; // npm install xxx url?: string; // 直接下载};Claude Code 關注”該不該用”——面向觸發語義,並採用漸進式披露設計:
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:
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 技能 }}還有一個雙通道設計——技能可以被使用者呼叫,也可以被模型自動呼叫,兩個方向獨立控制:
export type SkillInvocationPolicy = { userInvocable: boolean; // 用户能否用 /命令 调用 disableModelInvocation: boolean; // 模型能否自动使用};Claude Code 同樣支援斜槓命令——技能預設 user-invocable: true,自動註冊為 /skill-name 命令出現在選單中,使用者可以直接呼叫。但它還多了一層語義匹配——模型會根據 description 中的觸發短語自動判斷是否需要載入:
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 流程中顯式載入:
<!-- 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:全量注入 + 硬上限截斷。 設定明確的上限,超出時用二分搜尋找到能放進去的最大子集:
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 是預防型——安裝前掃描程式碼。 內建安全掃描器檢測技能目錄中的可疑模式:
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 機制上,在工具執行前/後插入檢查點:
{ "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(執行指令碼),還有許可權清單從全域性層面控制工具訪問:
{ "permissions": { "deny": ["WebSearch", "WebFetch"], "ask": ["Bash"] } }回到 todo 技能:OpenClaw 掃描 skills/todo/ 目錄,如果發現技能檔案中有 exec() 呼叫或網路請求,會在安裝時報警。Claude Code 則透過 Hooks 在執行時攔截——比如 todo 技能嘗試寫入 ~/.todo.json 以外的路徑時,PreToolUse 鉤子可以阻止操作。
配置管理
OpenClaw 用 YAML 集中管理所有技能的開關、API Key、環境變數:
skills: allowBundled: [github, discord] entries: notion: enabled: true apiKey: secret_xxx env: { NOTION_TOKEN: ntn_xxx } discord: enabled: false背後的型別系統支撐了細粒度控制:
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,寫入內容,儲存——下次啟動自動發現。還可以透過外掛清單批次宣告技能路徑:
{ "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 可呼叫的工具:
{ "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 的指令,支援動態內容插值:
---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 taskBased 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 基礎設施最樸素也最深刻的設計選擇。