用了 OpenClaw 一段时间后，你会发现一个问题：通用能力很强，但特定任务总差点意思。
写作时注意语言要口语化，避免使用太正式的表达，
同时也要注意不要暴露任何内部信息…
比如你想让它按照你的风格写推文、按固定格式生成日报、或者执行一套特定的安全检查流程。每次都在对话里重复描述需求？太累了。
这就是 Skill 存在的意义——把你的最佳实践固化成可复用的能力模块。
写一次，用无数次。Agent 自动识别什么时候该用哪个 Skill，不需要你每次手动指定。
Skill 到底是什么？
说白了，Skill 就是一个文件夹，里面放着一份给 AI 看的「操作手册」。
核心是一个叫 SKILL.md的文件（大小写敏感），里面用 YAML 格式写好元数据，用 Markdown 写好操作步骤。OpenClaw 启动时会自动扫描并加载它。
你可以把 Skill 理解成给 AI 的 SOP——标准操作流程。人类新员工入职要看操作手册，AI Agent 也一样。
Skill 放在哪？
OpenClaw 从三个地方加载 Skill，优先级从高到低：
- 工作区 Skills：~/.openclaw/workspace/skills/（你自己写的，优先级最高）
- 本地 Skills：~/.openclaw/skills/（跨 Agent 共享）
- 内置 Skills：随 OpenClaw 安装包自带
同名冲突时，优先级高的覆盖低的。所以你可以用自己的版本覆盖内置 Skill，不需要改源码。
最小可用 Skill：5 分钟上手
先来个最简单的例子，感受一下：
skills/
└── hello-world/
└── SKILL.md
SKILL.md内容：
—
name: hello-world
description: >
一个简单的问候技能。
Use when: 打招呼, say hello, 问好。
Do NOT use for: 其他任何事。
—
# Hello World Skill
当用户打招呼时，用一种有趣的方式回应。
可以根据当前时间选择合适的问候语。
就这么多。重启 OpenClaw 或让 Agent 刷新 Skills，它就生效了。
当你对 Agent 说「打个招呼」，它会自动匹配到这个 Skill 并按照指示操作。
YAML Frontmatter：Skill 的身份证
frontmatter 是 Skill 最关键的部分——OpenClaw 靠它来判断什么时候触发你的 Skill。
必填字段：
- name — 唯一标识，必须用 kebab-case（小写+连字符）
- description — 描述，必须回答三个问题：做什么？什么时候用？什么时候不用？
—
name: weekly-report
description: >
生成团队周度复盘报告，整合本周完成事项和下周计划。
Use when: 周报, weekly report, 本周总结, 周度复盘。
Do NOT use for: 日报, 晨间简报, 短内容。
metadata:
author: your-name
version: 1.0
category: reporting
—
💡 description 里的触发词非常重要。OpenClaw 用它来做语义匹配——用户说的话和哪个 Skill 的描述最相关，就触发哪个。所以触发词要写全，包括中英文、同义词、口语表达。
一个常见错误： 只写了「做什么」，没写「什么时候不用」。结果是 Skill 被误触发。比如你的周报 Skill 如果不写 Do NOT use for，用户说「帮我写个日报」也可能触发它。
文件结构：渐进式加载
这是 Skill 设计的核心理念——别把所有东西塞进一个文件。
为什么要拆？因为每次触发 Skill，Agent 都会读 SKILL.md的全部内容。如果你把一万字的规则全塞进去，每次触发都消耗大量 token，而且 Agent 反而容易「看花眼」——信息太多，重点反而抓不住。
my-skill/
├── SKILL.md # 必须。核心流程，控制在 5000 字以内
├── references/ # 可选。详细文档，按需加载
│ ├── detailed-rules.md
│ └── examples.md
├── scripts/ # 可选。验证脚本、辅助工具
│ └── check.py
└── assets/ # 可选。模板、图片等静态资源
└── template.md
正确做法：SKILL.md只放核心流程和关键规则，详细的参考文档放到 references/ 里，在 SKILL.md 中用路径引用：
详细规则
- – 算法权重详解：`references/algorithm-weights.md`
- – 检测规避策略：`references/detection-rules.md`
Agent 需要的时候会自己去读对应的 reference 文件。需要才读，不需要不读。
💡 我们实测过一个案例：一个推文写作 Skill 从 12KB 的单文件重构成 2KB 核心 + 4 个 references，token 消耗直接减少 80%，而输出质量反而提升了——因为 Agent 每次只看最关键的规则，不会被无关信息干扰。
SKILL.md怎么写才好？
原则一：写「做什么」，不写「你是谁」
# ❌ 不好的写法
你是一个专业的推文写作助手，你需要帮助用户…
# ✅ 好的写法
## 核心流程
### Step 1: 确定主题和角度
### Step 2: 搜索素材（用 web_search）
### Step 3: 按规则写作
### Step 4: 质量检查
Agent 已经知道自己是谁了，不需要你再定义。直接告诉它步骤。
原则二：用 Step 结构，别用长段落
AI 处理结构化指令比处理自然语言段落更准确。把流程拆成明确的步骤，每步说清楚做什么、怎么做、注意什么。
原则三：关键规则用列表，不用段落
# ❌ 模糊
写作时注意语言要口语化，避免使用太正式的表达，
同时也要注意不要暴露任何内部信息…
# ✅ 清晰
## 禁用词（必须替换）
首先/其次/最后、值得注意、众所周知、总而言之## 安全红线
– 禁止暴露：内部系统名、Agent 数量、API Key
– 禁止读取：vault/、敏感配置文件
原则四：能用脚本验证的就不靠语言描述
与其在 SKILL.md里写一大段「检查输出是否符合标准」，不如写个脚本：
### Step 4: 质量检查
运行检查脚本验证输出：
\\`\\`\\`bash
python scripts/check_output.py “输出内容”
\\`\\`\\`
脚本检查比 AI 自检靠谱得多。AI 说「我检查过了，没问题」——你信吗？
高级功能：环境要求和门控
如果你的 Skill 依赖特定工具或 API Key，可以在 metadata 里声明：
metadata:
openclaw:
requires:
bins: [“ffmpeg”] # 需要 ffmpeg 在 PATH 中
env: [“OPENAI_API_KEY”] # 需要这个环境变量
primaryEnv: “OPENAI_API_KEY”
OpenClaw 加载时会检查这些条件——不满足就不加载，而不是加载了然后运行时报错。
你也可以用 skills.entries 在配置文件里给 Skill 注入环境变量和 API Key，不需要写在代码或提示词里。
多 Agent 场景：谁看到什么
如果你跑多个 Agent（比如一个写作 Agent、一个分析 Agent），Skill 的可见性规则很重要：
- 工作区 Skills（<workspace>/skills/）只对该 Agent 可见
- 本地 Skills（~/.openclaw/skills/）对所有 Agent 可见
- 配置 {{CODE}} 可以禁用特定 Skill
💡 推荐做法：通用工具类 Skill（天气查询、网页摘要）放到 ~/.openclaw/skills/ 共享，专属任务类 Skill（推文写作、日报生成）放到对应 Agent 的工作区里。
实战案例：从零构建一个安全检查 Skill
假设你要做一个定期安全检查的 Skill，完整示例：
security-audit/
├── SKILL.md
├── references/
│ └── ioc-list.md # 已知恶意文件名清单
└── scripts/
└── scan.sh # 自动化扫描脚本
SKILL.md：
—
name: security-audit
description: >
执行系统安全体检，包括 IOC 扫描、密钥检查、网络暴露审计。
Use when: 安全检查, security audit, 安全体检, 系统安全。
Do NOT use for: 性能优化, 日常运维。
—
# Security Audit Skill## 核心流程
### Step 1: IOC 文件扫描
按 `references/ioc-list.md` 中的清单扫描关键目录。### Step 2: 密钥安全检查
– SSH 密钥权限是否为 600
– authorized_keys 是否有异常公钥
– 是否存在未使用的云凭证### Step 3: 网络暴露检查
– 扫描监听端口
– 检查 0.0.0.0 绑定
– DNS 缓存中是否有恶意域名### Step 4: 生成报告
以列表形式输出每项检查结果（✅/❌），最后给出综合评估。
测试你的 Skill
写完之后，跑一遍测试清单：
- 触发测试 — 用预期的触发词说一句话，Skill 能被正确匹配吗？
- 换种说法 — 用同义词或口语表达，还能触发吗？
- 反向测试 — 说一句不相关的话，Skill 不会被误触发吧？
- 质量测试 — 输出是否符合你定义的规则和格式？
💡 一个实用的测试方法：openclaw agent –message “用我的新 Skill” 直接在命令行测试，不需要启动完整的对话。
常见坑
坑 1：SKILL.md太大
超过 5000 字的 SKILL.md会导致 token 浪费和 Agent 注意力分散。拆到 references/。
坑 2：description 写得太模糊
「一个帮助用户的 Skill」——这等于没说。触发词要具体、要全面、要包含中英文。
坑 3：忘了写 Do NOT use for
结果 Skill 到处误触发，用户聊天天被打断。
坑 4：在 SKILL.md 里写 README 式的介绍
SKILL.md不是给人看的文档，是给 AI 看的操作手册。省掉背景介绍、项目历史、贡献指南。直接上步骤。
坑 5：用表格定义复杂规则
AI 处理 Markdown 表格不如列表准确。复杂规则用嵌套列表或分级标题。
Skill 社区：ClawHub
写好的 Skill 可以发布到 ClawHub 和社区分享：
- 安装：clawhub install <skill-slug>
- 更新：clawhub update –all
⚠️ 安全提醒：第三方 Skill 等同于未受信任的代码。安装前务必阅读 SKILL.md内容，确认没有恶意操作（比如读取你的私钥、发送数据到外部服务器）。
最后
Skill 体系是 OpenClaw 最强大的扩展机制。本质上，它让你把「教 AI 做事」这件事从一次性的对话变成了可复用的资产。
好的 Skill 应该像好的函数一样——做一件事，做好一件事，清晰地定义输入输出和边界。
让你的ai写第一个 Skill 吧。从那个你每次都要重复描述的任务开始。
文：xiyu@X
原创文章，作者：美来，如若转载，请注明出处：https://www.meilai.com/openclaw-skill.html
