OpenClaw 的【skill】从入门到精通

什么是skill

Skill 是给 AI 提供指令、工具定义和相关资源的一个完整目录 。开发Skill不一定需要你写很多代码，关键在于写出清晰有效的 Markdown 格式指令

核心设计原则

单一职责原则 ：一个Skill专注解决一个问题。设计高度聚焦的"PDF解析"技能，而不是一个庞大又不好维护的"万能文档处理"技能。

渐进式披露：分三层设计你的Skill。第一层在YAML前置信息中用精简语言说功能。第二层在Markdown正文匹配任务时提供完整流程。第三层将参考文档、长文本等放在链接文件中按需加载，高效利用AI的上下文资源。

可组合性与可移植性：避免假设你的Skill是唯一运行的，让它能与其他Skill和谐共存。同时，按规范开发的Skill可在OpenClaw、Claude Code等不同平台上通用

skill 的标准格式

text 复制代码

my-awesome-skill/          # 技能根目录（命名遵循小写字母、数字、连字符）
├── SKILL.md               # 【必需】核心文件，即技能说明书
├── scripts/               # 【可选】存放Python、Node.js、Bash等可执行脚本，是技能干活的核心逻辑
├── references/            # 【可选】存放参考文档、API手册等补充知识，AI可按需加载
├── templates/或者assets   # 【可选】存放模板、图片、配置等静态资源
└── (其他文件)              # 如 plugin.json、package.json 等，取决于开发语言

SKILL.md 文件的格式

由两部分组成：

markdown 复制代码

---
# YAML Frontmatter（元数据区，AI快速辨识技能的"身份证"）
name: my-skill-name          			# 技能唯一标识
description: 简洁描述技能功能  		 # 供AI理解何时使用，
version: 1.0.0              					# 语义化版本号
author: your-name           				# 作者信息
user-invocable: true					# 是否可被用户直接调用（默认 true）
metadata:
     openclaw:
     emoji: "📝"							# 展示图标
     os:										# 操作系统支持
         - darwin
     	- linux
     	- win32
     requires:								
         anyBins: []								# 命令依赖
	        - python3	
	     env:									# 环境变量依赖
        		- API_KEY
     install:								     # 工具依赖
        - id: uv-pypdf
	        kind: uv							# 安装方式（如pip，uv，pnpm，brew，apt)
	        package: pypdf				# 依赖库名称
	        label: Install pypdf 

---

# Markdown 正文（核心的"行动指南"区）
这里是提供给AI的详细工作流程、使用说明和最佳实践。告诉AI在什么情况下、按什么步骤、调用哪些Tools来完成目标。

<scenarios>
适用场景说明
</scenarios>

<input>
输入参数要求
</input>

<output>
输出参数要求
<output>

<tools>
工具列表及选择规则
</tools>

<process>
执行流程
</process>

<error>
错误处理
</error>

</success_criteria>
成功标识
</success_criteria>

skill 编写技巧

描述（description）要「触发词 + 用途」
指令正文「结构清晰：触发 → 步骤 → 格式 → 示例」
依赖声明（requires）要写，如果要 git、python3、API Key，一定要写在 requires 里，Agent 会自动检查并提示用户安装 / 配置
多用约束词（减少幻觉），如：必须、只能、不要、禁止、严格按照、输出格式固定为。
一个 Skill 只做一件事；复杂任务拆成多个 Skill，再用「工作流 Skill」串联
使用xml 格式对md文件中的内容分块
使用模板约束输入输出字段，添加工具调用记录元数据
添加技能完成的成功标识，能用工具/脚本进行验证的要验证，不要使用模糊的说明
不要在技能中解释/说明知识，大模型比你聪明
能用工具/脚本进行验证的要验证，不要使用模糊的

skill 调用与测试

本地测试：把 Skill 放到项目 ~/.openclaw/skills，直接对话触发
查看加载：openclaw skill list 看是否加载成功
日志排查：~/.openclaw/logs/ 看技能加载 / 调用错误
迭代优化：效果不好就改 description 和步骤，纯文本修改，不用重启

skill 的运行流程

触发-解析-执行-回调-结果整合

这一流程与 AgentSkills 的"渐进式披露三层结构"一致：先元数据，再正文，再资源；也与 OpenClaw 的"加载/过滤/注入/执行/回填"相吻合。
多来源与覆盖优先级：bundled → ~/.openclaw/skills → /skills，同名 skill 可被更高优先级覆盖。
技能加载优先级（同名技能冲突时），当同一技能名出现在多个位置时，高优先级会覆盖低优先级：

优先级位置

最高 /skills

↓ /.agents/skills

↓ ~/.agents/skills

↓ ~/.openclaw/skills

↓ bundled skills（内置）

最低 skills.load.extraDirs

优先级	位置
最高	/skills
↓	/.agents/skills
↓	~/.agents/skills
↓	~/.openclaw/skills
↓	bundled skills（内置）
最低	skills.load.extraDirs