—— 转自通往AGI之路
一句话定义
Skills = Agent 的"操作手册"。
Tools 是手脚（读文件、发请求、跑命令），Skills 是教 Agent 怎么用手脚完成任务的指南。
打个比方：Tools 是锤子和螺丝刀，Skills 是"如何组装宜家家具"的说明书。你把锤子给一个人，他未必知道该敲哪里；但给他说明书，他就能照着一步步把书柜装好。
一、Skills 是什么？
核心定义
一个 Skill 就是一个文件夹，里面有一个 SKILL.md 文件。这个文件用 YAML frontmatter（元数据头）+ Markdown 正文，告诉 Agent："遇到这类任务，按这个流程做。"
就这么简单。一个 Markdown 文件，就是一个技能。
Skills vs Tools 的区别
这两个概念新手最容易搞混，用一张表说清楚：
关键认知：没有 Tools，Agent 没有能力做事；没有 Skills，Agent 有能力但不知道怎么做事。两者缺一不可。
为什么需要 Skills？
你可能会想：AI 不是很聪明吗？我直接告诉它"帮我搜论文"，它不就知道怎么做了？
大部分时候确实可以。但问题是：
- Agent 不知道你的环境里有什么工具。
你装了 MediaCrawler 可以爬小红书，但 Agent 不知道这个工具存在，更不知道怎么调用它。Skill 告诉它："你有这个工具，这样用。" - 复杂任务需要编排多个步骤。
"帮我搜论文"听起来简单，但实际上要：调 arXiv API → 解析 XML → 补充 Semantic Scholar 引用数据 → 格式化输出。这些步骤写在 Skill 里，Agent 照着做就行。 - 经验可以复用。
你花了一小时调好了一个搜索流程，写成 Skill 之后，每次都能复用。还能分享给别人。
一句话：Skills 把"怎么做"标准化了。
二、Skills 的三级加载机制
Agent 启动时会从三个地方加载 Skills，优先级从高到低：
第一级：工作区 Skills（优先级最高）
<workspace>/skills/项目专属技能。比如你的工作空间在 ~/.openclaw/workspace/，那就是 ~/.openclaw/workspace/skills/。
适用场景：只在当前项目中使用的技能。
第二级：用户 Skills
~/.openclaw/skills/跨项目共享的技能。clawhub install 默认安装到这里。
适用场景：所有项目都能用的通用技能，比如搜索、邮件、GitHub 操作。
第三级：内置 Skills（优先级最低）
OpenClaw 自带的技能，比如 github、memory、summarize 等 52 个。不需要安装，开箱即用。
门控过滤
加载时不是所有 Skill 都会生效。OpenClaw 会检查每个 Skill 声明的依赖：
requires.bins：需要的 CLI 工具（比如gh、docker）requires.env：需要的环境变量（比如TAVILY_API_KEY）requires.os：支持的操作系统
缺依赖的 Skill 自动跳过，不会报错，也不会加载。这意味着你可以放心装一堆 Skill，用不了的会自动忽略。
查看当前哪些 Skill 满足条件可以使用：
openclaw skills list --eligible查看哪些 Skill 因为缺依赖被跳过：
openclaw skills check --verbose三、一个 Skill 长什么样？
SKILL.md 的结构
每个 Skill 的核心就是一个 SKILL.md 文件，结构像这样：
SKILL.md 结构：
├── YAML Frontmatter（元数据）
│ ├── name + description（必填）
│ ├── version
│ └── metadata.openclaw（运行时需求）
│ ├── requires（依赖声明）
│ ├── install（自动安装规格）
│ └── emoji / os / always 等
└── Markdown Body（指令正文）
├── 触发条件
├── 工作流步骤
└── 注意事项最小示例（5 行就是一个 Skill）
---
name: hello
description: 当用户说"打个招呼"时，用中文回复一句有趣的问候
---
用一句幽默的中文问候回复用户。不要太正式，像朋友之间说话一样。对，就这么短。name + description + 一段指令，就是一个合法的 Skill。
完整示例：天气查询 Skill
---
name: weather-query
description: 查询指定城市的天气信息。当用户问"今天天气怎么样"、"北京天气"、"明天会下雨吗"等天气相关问题时触发。
version: 1.0.0
tags: [weather, utility]
metadata:
openclaw:
requires:
env: [OPENWEATHER_API_KEY]
emoji: 🌤️
---
# 天气查询
## 触发条件
当用户询问任何城市的天气情况时使用此技能。
## 工作流程
### Step 1: 提取信息
- 从用户消息中提取：目标城市、查询日期（默认今天）
- 如果用户说的是中文城市名，转换为英文（如"北京" → "Beijing"）
### Step 2: 调用 API
使用 `web_fetch` 调用 OpenWeatherMap API：
### Step 3: 格式化输出
从 API 返回的 JSON 中提取：
- 温度（当前 / 最高 / 最低）
- 天气描述
- 湿度和风速
- 体感温度
用简洁自然的语言回复，例如：
"北京现在 22°C，晴，体感 20°C。最高 25°C，最低 18°C。湿度 45%，微风。适合出门。"
## 注意事项
- API 每分钟限 60 次请求
- 如果城市名不明确，先问用户确认
- 预报数据用 `/forecast` 端点，最多 5 天Frontmatter 关键字段详解
重点说 description：这个字段决定了 Skill 的"生死"。Agent 在接到用户消息时，会扫描所有可用 Skill 的 description，判断哪些跟当前任务相关。description 写得不好 = Skill 永远不会被触发。
社区的经验是：description 要写得"有点激进"，鼓励触发而非欠触发。 宁可多触发几次（用户会纠正），也不要错过该触发的场景。
四、ClawHub — 技能市场
是什么
ClawHub 是 OpenClaw 的官方技能注册中心，网址 clawhub.com。截至 2026 年 3 月，有 13,729+ 个社区贡献的技能。
你可以把它理解成 Skills 的"App Store"——搜索、安装、更新、发布，一条龙。
CLI 操作速查
# 搜索（语义搜索，基于向量索引，不是简单的关键词匹配）
clawhub search "天气查询"
clawhub search "github issue management"
# 安装
clawhub install <slug>
# 查看不安装（先看看这个 Skill 做了什么）
clawhub inspect <slug>
# 更新全部已安装的 Skill
clawhub update --all
# 更新单个
clawhub update <slug>
# 发布自己的 Skill
clawhub publish <path>安装后验证
# 重启 Gateway 让新 Skill 生效
openclaw gateway restart
# 查看是否加载成功
openclaw skills list | grep <skill-name>
# 检查依赖是否满足
openclaw skills check --verbose版本管理
ClawHub 使用语义化版本（semver）+ 内容哈希比对。clawhub update 不只看版本号，还会比对实际内容变化，避免无意义更新。
许可证
ClawHub 上的技能统一采用 MIT-0 许可证——可以用、可以改、可以商用、不用署名。
五、自己写一个 Skill（5 分钟上手）
别被"写 Skill"这件事吓到。前面你已经看到了，最简单的 Skill 只要 5 行。下面我们来写一个真正能用的——天气查询 Skill。
Step 1：创建目录
mkdir -p ~/.openclaw/skills/weather/Step 2：编写 SKILL.md
cat > ~/.openclaw/skills/weather/SKILL.md << 'EOF'
---
name: weather
description: 查询城市天气。当用户问"天气怎么样"、"北京天气"、"明天下雨吗"、"需要带伞吗"时触发。
version: 1.0.0
---
# 天气查询
## 触发条件
用户询问任何城市的天气信息时使用。
## 工作流程
### 1. 提取城市名
- 从消息中提取城市名，中文城市转为英文拼音
- 未指定城市时，询问用户
### 2. 查询天气
使用 `web_fetch` 访问 wttr.in（免费天气 API，无需 API Key）：GET https://wttr.in/{城市}?format=j1
### 3. 格式化回复
从返回 JSON 的 `current_condition` 中提取：
- `temp_C`：当前温度
- `weatherDesc`：天气描述
- `humidity`：湿度
- `windspeedKmph`：风速
- `FeelsLikeC`：体感温度
用自然语言回复，例如：
"北京现在 22°C，晴天，体感 20°C，湿度 45%，微风。出门不用带伞。"
如果用户问未来天气，从 `weather` 数组中提取对应日期的预报数据。
## 注意事项
- wttr.in 免费无限制，但请勿高频调用
- 部分小城市可能查不到，提示用户用英文全名
EOFStep 3：重启 Gateway
openclaw gateway restartStep 4：验证
openclaw skills list | grep weather看到输出中有 weather 就说明加载成功了。
Step 5：测试
向你的 Agent 发一条消息：
"今天北京天气怎么样？"
Agent 应该会触发 weather Skill，调用 wttr.in API，给你返回天气信息。
如果没触发怎么办？ 最常见的原因是 description 写得不够"激进"，Agent 没有把用户消息和这个 Skill 关联起来。调整 description，让它覆盖更多表述方式。
六、进阶用法
写出基础 Skill 之后，还有几个进阶能力值得了解。
Bundled Resources：给 Skill 附带参考文档
如果你的 Skill 需要参考大量文档（比如一个 API 的完整规格），可以在 Skill 目录下创建 references/ 目录：
~/.openclaw/skills/my-skill/
├── SKILL.md
└── references/
├── api-spec.md
└── examples.mdAgent 在执行 Skill 时会按需加载这些文件，不会一次性塞进上下文浪费 token。
Scripts：可执行脚本
如果 Skill 需要跑一些脚本（Python、Shell 等），放在 scripts/ 目录：
~/.openclaw/skills/my-skill/
├── SKILL.md
└── scripts/
├── fetch_data.py
└── parse_result.sh在 SKILL.md 中通过 exec 工具调用这些脚本。
依赖声明 + 自动安装
在 frontmatter 中声明依赖，OpenClaw 会在加载时自动检查，缺失时提示安装：
metadata:
openclaw:
requires:
bins: [gh, jq] # 需要 gh 和 jq CLI 工具
env: [GITHUB_TOKEN] # 需要 GITHUB_TOKEN 环境变量
os: [darwin, linux] # 只支持 macOS 和 Linux
install:
bins:
gh: "brew install gh"
jq: "brew install jq"requires 做的是检查，install 做的是告诉 Agent 怎么装。
发布到 ClawHub
写好一个 Skill，觉得别人也能用？发布出去：
clawhub publish ~/.openclaw/skills/my-skill发布前用 quick_validate.py 校验结构是否合法（如果你装了 skill-creator 技能的话），或者至少确保 frontmatter 中 name 和 description 都有。
七、常见问题 FAQ
Q1: Skill 装了但没触发？
最常见原因：description 写得太保守，Agent 没有匹配上。
排查步骤：
- 确认 Skill 已加载：
openclaw skills list | grep <name> - 确认依赖满足：
openclaw skills check --verbose - 检查
description是否覆盖了用户的表述方式。比如你写的是"查询天气"，但用户说的是"明天需要带伞吗"——这两个表述差很远 - 尝试在 description 中加入更多触发词和场景描述
Q2: Skill 和 MCP Server 什么关系？
互补关系，不是竞争关系。
- MCP（Model Context Protocol）是一个开放协议，让 AI 连接外部工具和数据源。它定义的是"AI 怎么跟外部服务通信"
- Skill 是 Agent 内部的操作指南，告诉 Agent"遇到这类任务怎么做"
举个例子：你可以用 MCP 连接了一个 Notion 数据库，然后写一个 Skill 教 Agent "当用户说'记个笔记'时，把内容写入 Notion"。MCP 提供通道，Skill 提供逻辑。
Q3: YAML frontmatter 解析报错？
最常见的坑：description 中的冒号后面有空格。
# 报错：
description: 搜索技能：让 Agent 能搜索
# 正确：用引号包起来
description: "搜索技能：让 Agent 能搜索"YAML 中 : + 空格是键值分隔符，如果你的文本里有这个组合，必须加引号。
Q4: 工作区 Skills 和用户 Skills 有同名的怎么办？
工作区优先。三级加载机制中，工作区 > 用户 > 内置，同名时高优先级的覆盖低优先级的。
Q5: 怎么知道一个 Skill 被触发了几次？
目前没有内置统计。社区推荐的方式：在 SKILL.md 的工作流中加一步"执行前在 memory/ 中记录一次"，手动统计。或者看 Gateway 日志：
openclaw logs --follow日志里会显示 Agent 加载了哪些 Skill。
Q6: 能不能让某个 Skill 每次对话都加载？
可以。在 frontmatter 中设置：
metadata:
openclaw:
always: true但要谨慎使用——每次都加载意味着每次都消耗 token。