Skip to content

如何自定义skills （agentskills.io 规范）

先理清核心规则： Skill = 独立文件夹 + SKILL.md，纯声明式配置，不需要写代码；遵循渐进式披露机制。 存放路径：~/.openclaw/skills/[你的skill名称]/SKILL.md

一、目录规范（强制）

~/.openclaw/skills/
└── mkdocs-builder/           # 文件夹名称推荐和name保持一致
    └── SKILL.md              # 文件名固定大写SKILL.md，不能改名

注意： 1. 不能多层嵌套；所有skill直接放在skills一级子目录 2. 文件夹名不要空格、中文尽量少用 3. 修改文件后执行 openclaw skills refresh 重载

二、SKILL.md 标准结构模板

文件分为两大部分：Frontmatter（顶部---配置区） + 正文SOP 

---
# Frontmatter 元数据（机器读取，用于索引匹配、权限控制）
name: mkdocs-builder
description: >
  MkDocs文档自动化工具。
  用户要求构建站点、启动本地预览、排查mkdocs.yml语法错误时启用；
  支持 mkdocs build、mkdocs serve，读取配置定位YAML报错。
allowed-tools: read_file, run_bash
# optional: priority: 5 数字越大优先级越高，避免多个skill同时匹配冲突
---
# 业务SOP（模型命中后，渐进式完整注入上下文）
## 执行步骤
1. 检查当前工作目录是否存在 mkdocs.yml
2. 根据用户指令选择动作：
- 构建静态网站：执行 mkdocs build
- 本地开发预览：执行 mkdocs serve
3. 构建报错时，读取mkdocs.yml，定位行号，给出YAML修复建议

## 约束规则
- 执行bash命令前，向用户告知即将运行的指令
- 禁止自动删除文件、清空目录
- 如果目录不存在mkdocs.yml，立刻停止并询问路径

Frontmatter字段详解

  1. name 唯一标识，小写横杠命名，全局不可重名。

  2. description 【渐进式披露核心】 只写触发场景、适用意图，不要堆砌详细步骤。

    OpenClaw 只会把所有skill的description汇总成简短清单常驻上下文，用来判断要不要加载完整skill。 ❌ 错误：把执行步骤写进description，破坏渐进披露，token暴涨 ✅ 正确：只描述「什么情况下启用这个技能」

  3. allowed-tools 白名单！限制该技能能调用哪些底层工具，安全边界。 常用内置工具：

  4. read_file 读取本地文件
  5. write_file 写入文件
  6. run_bash 执行终端命令

  7. web_fetch 请求网页

    不在列表内的工具，Agent无法调用

  8. priority（可选） 取值 1~10，默认5。多条skill同时匹配用户问题时，优先加载优先级高的。

三、从零创建自定义Skill实操步骤

1）创建目录

mkdir -p ~/.openclaw/skills/go-code-review

2）编写 SKILL.md

---
name: go-code-review
description: >
  Go代码静态审查技能。
  用户要求评审go源码、查找潜在bug、检查规范、优化逻辑时启用；
  读取go源码，分析语法、并发风险、错误处理规范。
allowed-tools: read_file, run_bash
priority: 6
---
# 代码评审流程
1. 获取用户指定的Go文件路径
2. 读取源码内容
3. 重点检查：
- error 是否妥善处理，不忽略err
- goroutine 并发竞态风险
- 资源是否关闭（io.Close）
- 硬编码、魔术数字问题
4. 分点输出问题 + 修改建议，附带代码示例

# 约束
不允许直接修改文件；仅输出评审意见。

3）重载生效

openclaw skills refresh
# 验证是否加载成功
openclaw skills list
看到状态 ✓ ready 代表成功。

4）TUI内测试

openclaw tui
# 发送指令触发
帮我评审当前目录 main.go 的代码

四、设计最佳实践（适配渐进式披露）

1. description 撰写公式

【场景】 + 【触发关键词】 + 【能力简述】 示例：

Elasticsearch查询助手。用户需要构造DSL、排查集群日志、索引管理时启用，可以执行curl查询es接口。

2. 正文SOP结构化

固定三段式，模型更容易遵守： 1. 执行步骤 2. 校验清单 3. 硬性禁止约束

3. 权限最小原则

allowed-tools 只放必须用到的工具 例如文档构建skill不需要write_file就不要加上，缩小风险面。

五、常见踩坑清单

  1. ❌ 文件名叫 skill.md（小写） → ✅ 必须 SKILL.md
  2. ❌ 多层目录嵌套：skills/project/skill/ → 不支持
  3. ❌ 修改SKILL.md后不执行 refresh → 加载旧版本
  4. ❌ description写超长流程 → 破坏渐进披露，上下文膨胀
  5. ❌ allowed-tools 漏写工具 → Agent想调用但被系统拦截，任务卡住
  6. ❌ 多个skill description高度相似，同时命中 → 使用 priority 区分优先级

六、进阶玩法

  1. 技能互相调用 在SOP里引导Agent主动触发其他Skill，实现工作流组合。
  2. 条件分支控制 在正文写明：满足A条件执行方案1，满足B条件执行方案2，由LLM做分支判断（区别于LangGraph代码硬编码流程图）。
  3. Human-in-the-loop 在约束中写明：高危操作（删除文件、大批量变更）必须先询问用户确认。

七、对比两条技术路线帮你理清边界

  • OpenClaw Skill：自然语言SOP驱动，配置文件，无代码，适合业务自动化、本地运维任务
  • LangGraph：Python代码定义状态、节点、路由，强编程模型，适合高度可控、复杂多智能体系统

如果你告诉我一个场景（比如 ES日志排查、mkdocs发布自动化、数据库分析），我可以直接生成一份开箱即用完整的 SKILL.md。