一句话定义

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.md
    cat > ~/.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
  • 重启 Gateway
    openclaw 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 使用（如安全审计、代码规范），否则会拖慢响应。

该文观点仅代表作者本人，中视数字科技服务平台仅提供信息存储空间服务。