10 Skill详解
SKILL
Skills 系统详解
~15 分钟 · 理解 Skills 的概念、结构与实战
“先理解 Skill 是什么、怎么工作，下一幕再告诉你该装什么。”
一句话定义
Skill = 一个文件夹 + 一份 SKILL.md，就这么简单。它不是插件、不是二进制、不需要编译——只是一段提示词 + 元数据，告诉 Agent “遇到什么场景、该怎么做”。
🔨 如果 MCP 工具是锤子，那 Skill 就是使用说明书——锤子只知道敲，说明书告诉你敲哪里、用多大力、什么顺序敲。
10.1
Skills 是什么？
2 min
核心定义
Skill 是一个纯文本指令包——一个文件夹里放一个 SKILL.md 文件。Agent 在对话开始时读取它，就像员工上班前先看工作手册。没有代码执行，没有二进制，只有提示词。
| 维度 | Skills | Tools (MCP) |
|---|---|---|
| 本质 | 提示词 + 元数据 | 可执行函数/API |
| 存在形式 | SKILL.md 文本文件 | 运行中的服务进程 |
| 安装方式 | clawhub install 或手动放文件 | 配置 MCP Server 地址 |
| 谁写 | 任何人（只需写 Markdown） | 开发者（需写代码） |
| 运行时角色 | 注入系统提示词，指导 Agent 行为 | 提供可调用的函数接口 |
| 类比 | 📖 使用说明书 / SOP | 🔨 锤子 / 螺丝刀 |
为什么需要 Skills？
Agent 不知道工具存在 — MCP 工具装了不代表 Agent 知道什么时候该用。Skill 告诉它”遇到 X 场景，调用 Y 工具”
复杂任务需要编排 — 单个工具只能完成一步，Skill 把多个工具串成完整工作流（先搜索 → 再总结 → 最后格式化）
经验可复用 — 你踩过的坑、摸索出的最佳实践，写成 Skill 就能分享给所有人，不用每次重新教 Agent
10.2
三级加载机制
2 min
- 工作区 Skills（最高优先级） — 放在项目的
.openclaw/skills/目录下，只对当前项目生效。适合项目专属的编码规范、部署流程 - 用户 Skills（中等优先级） — 放在
~/.openclaw/skills/目录下，对所有项目生效。适合个人通用习惯，如 Git 工作流、代码风格 - 内置 Skills（最低优先级） — OpenClaw 自带的技能（如 summarize、apple-reminders），开箱即用
门控过滤 — 不是所有 Skill 都会加载。Frontmatter 中的 requires 字段可以声明前置条件：
requires.bins：需要哪些 CLI 工具（如 docker, git）——没装就跳过
requires.env：需要哪些环境变量（如 API Key）——没配就跳过
requires.os：限定操作系统（darwin / linux / win32）
# 查看当前环境下哪些 Skill 通过了门控 openclaw skills list –eligible # 详细检查每个 Skill 的门控状态 openclaw skills check –verbose
10.3
Skill 的结构
3 min
SKILL.md 结构概览：每个 Skill 就是一个 Markdown 文件，由两部分组成——
Frontmatter（YAML 头部）：元数据——名称、描述、版本、触发条件、依赖声明
Markdown Body（正文）：注入给 Agent 的提示词——告诉它遇到什么场景做什么事
最小示例（5 行就是一个 Skill）：
— name: hello description: “Say hello in a fun way” — When the user says hello, respond with a creative greeting and a fun fact.
完整示例（天气查询 Skill）：
— name: weather-check description: “Check weather for any city using wttr.in” version: 1.0.0 tags: [“weather”, “utility”] requires: bins: [“curl”] metadata: openclaw: min_version: “0.2.0” — # Weather Check Skill When the user asks about the weather: 1. Use `curl wttr.in/{city}?format=3` to get the current weather 2. Present the result in a friendly, readable format 3. If the city is ambiguous, ask for clarification ## Examples – “What’s the weather in Tokyo?” → `curl wttr.in/Tokyo?format=3` – “北京天气” → `curl wttr.in/Beijing?format=3`
| 字段 | 必填 | 说明 |
|---|---|---|
| name | ✅ | Skill 唯一标识，小写 + 连字符（如 weather-check） |
| description | ✅ | ⚡ 最关键字段！Agent 根据它决定是否触发。写得太保守 = 永远不会被调用 |
| version | 否 | 语义化版本号（semver），ClawHub 发布时必填 |
| tags | 否 | 分类标签，帮助 ClawHub 搜索和推荐 |
| requires.bins | 否 | 依赖的 CLI 工具列表，缺失则 Skill 不加载 |
| requires.env | 否 | 依赖的环境变量列表，缺失则 Skill 不加载 |
| requires.os | 否 | 限定操作系统（darwin / linux / win32） |
| metadata.openclaw | 否 | OpenClaw 特定配置，如 min_version、always: true |
关键洞察
description 决定 Skill 的生死。Agent 看到用户消息后，用 description 做模糊匹配决定是否触发。
经验法则：宁可多触发、再在正文里细化，也不要写得太窄导致永远不被调用。
10.4
ClawHub 技能市场
2 min
ClawHub 是 OpenClaw 的官方技能注册中心，目前收录 13,729+ 技能，类似 npm 之于 Node.js
每个技能都有内容哈希验证，确保安装后未被篡改
默认许可证 MIT-0（无归属要求），可自由使用和修改
CLI 操作速查：
# 搜索技能 clawhub search “weather” # 安装技能 clawhub install username/skill-name # 查看技能详情（安装前检查） clawhub inspect username/skill-name # 更新已安装的技能 clawhub update username/skill-name # 发布自己的技能 clawhub publish ./my-skill/
安装后验证：
# 重启 Gateway 使新技能生效 openclaw gateway restart # 确认技能已加载 openclaw skills list
版本管理：ClawHub 使用 semver（语义化版本），安装时可指定版本 clawhub install user/skill@1.2.0
10.5
自己写一个 Skill
3 min
- 创建目录mkdir -p ~/.openclaw/skills/my-greeting/
- 编写 SKILL.mdcat > ~/.openclaw/skills/my-greeting/SKILL.md << ‘EOF’ — name: my-greeting description: “Greet the user in a fun, creative way when they say hello or hi” version: 0.1.0 — # My Greeting Skill When the user greets you (hello, hi, hey, 你好, etc.): 1. Respond with a creative, themed greeting 2. Include a random fun fact about today’s date 3. Keep it under 3 sentences EOF
- 重启 Gatewayopenclaw gateway restart
- 验证加载openclaw skills list | grep my-greeting
- 测试触发 — 打开 OpenClaw 对话，输入 “hello”，观察是否触发了你的 Skill
没触发？
最常见的原因是 description 不够激进。试试把 description 写得更宽泛：与其写 “greet when user says hello”，不如写 “respond to any greeting, salutation, or casual opening message in any language”。
10.6
进阶用法
2 min
Bundled Resources（引用资源）：在 Skill 目录下创建 references/ 文件夹，放入参考文档、示例代码等。SKILL.md 中可以引用这些文件。
my-skill/ ├── SKILL.md └── references/ ├── api-spec.yaml └── example-output.json
Scripts（脚本）：在 Skill 目录下创建 scripts/ 文件夹，放入辅助脚本。Agent 可以在 Skill 指导下执行这些脚本。
my-skill/ ├── SKILL.md └── scripts/ ├── setup.sh └── validate.py
依赖自动安装：在 frontmatter 中声明 dependencies，安装时自动拉取依赖的其他 Skill。
— name: full-stack-dev description: “Full-stack development workflow” version: 1.0.0 dependencies: – steipete/github – cougz/arcane-docker-manager requires: bins: [“git”, “docker”] —
发布到 ClawHub：一条命令即可发布，全球用户都能搜到和安装。
# 登录 ClawHub（首次） clawhub login # 发布 clawhub publish ./my-skill/ # 更新版本后重新发布 clawhub publish ./my-skill/ –bump minor
10.7
常见问题 FAQ
1 min
Q1 · Skill 安装了但没触发
三步排查：① openclaw skills list --eligible 确认已加载 ② 检查 description 是否足够宽泛 ③ 检查 requires 门控是否通过。90% 的问题出在 description 太窄。
Q2 · Skill 和 MCP Server 什么关系？
互补关系。MCP Server 提供”能力”（函数接口），Skill 提供”智慧”（什么时候用、怎么用）。一个管手，一个管脑。最佳实践：MCP 提供工具 + Skill 编排工作流。
Q3 · YAML Frontmatter 冒号报错
description 中包含冒号时必须加引号：description: "Check weather: current and forecast"。不加引号 YAML 会把冒号后的内容当成嵌套 key。
Q4 · 多个 Skill 同名怎么办？
按三级加载顺序：工作区 > 用户 > 内置。高优先级的同名 Skill 会覆盖低优先级的。可以利用这个机制在项目级别覆盖全局行为。
Q5 · 怎么统计 Skill 触发次数？
目前 OpenClaw 没有内置统计。可以在 Skill 正文中加一行”每次触发时在 ~/.openclaw/logs/skill-name.log 追加一条记录”，让 Agent 自己记。社区也有 skill-analytics 技能可用。
Q6 · always: true 是什么？要注意什么？
设置 metadata.openclaw.always: true 后，Skill 每次对话都会加载（不需要 description 匹配）。注意：会占用上下文窗口，建议只对核心 Skill 使用（如安全审计、代码规范），否则会拖慢响应。
