SKILL开发指引
# SKILL 开发指引
核心问题：如何从零开发一个 Skill 技能包，让 Agent 在正确场景自动调用你的能力？
一句话答案：写好 SKILL.md，打包目录结构，发布到技能市场——Agent 会根据 description 自动匹配触发。
# 一、技能包是什么
Skill 是以 ZIP 包形式分发的能力单元，根目录必须包含 SKILL.md。Agent 通过读取 frontmatter 与正文理解何时触发、如何调用脚本或引用资源。
# 核心概念
| 概念 | 说明 |
|---|---|
| 坐标格式 | @{空间}/{技能名}，例如 @global/code-review |
| 必填字段 | SKILL.md 的 name、description |
| 正文要求 | 说明适用场景、输入输出与限制 |
| 可选文档 | README.md 补充安装步骤、示例与 FAQ |
# Skill 与 MCP 的关系
| 维度 | Skill | MCP |
|---|---|---|
| 定位 | 教 Agent 怎么做事 | 连接外部系统 |
| 分发 | ZIP 包，技能市场安装 | 协议层，服务端运行 |
| 触发 | Agent 根据 description 自动匹配 | Agent 主动调用工具 |
| 开发成本 | 写文档 + 可选脚本 | 实现协议、启动服务 |
如果只是教 Agent 一套工作流程或方法论，用 Skill；如果需要 Agent 实时操作数据库、调用 API，用 MCP。
# 二、推荐目录结构
保持包体精简，只包含运行所需文件：
my-skill/
├── SKILL.md # 入口说明（必填）
├── README.md # 人类可读文档（推荐）
├── scripts/ # 可执行脚本（按需）
├── references/ # 参考文档、模板
└── assets/ # 图标、示例数据
1
2
3
4
5
6
2
3
4
5
6
# 各目录职责
| 目录/文件 | 是否必填 | 用途 |
|---|---|---|
SKILL.md | ✅ 必填 | Agent 读取的入口文件，定义触发条件与使用方式 |
README.md | 推荐 | 人类可读文档，补充安装步骤、示例与 FAQ |
scripts/ | 按需 | 可执行脚本，如自动化检查、数据转换 |
references/ | 按需 | 参考文档、模板文件，供 Agent 运行时查阅 |
assets/ | 按需 | 图标、示例数据等静态资源 |
原则：包体越小越好。只包含 Agent 运行所必需的文件，不要塞入构建产物或临时文件。
# 三、SKILL.md 编写要点
好的 SKILL.md 让 Agent 在正确场景自动选用你的能力。以下是四个核心要点：
# 1. description 要精准
用一句话说清「做什么」和「不做什么」，避免夸大。
# ✅ 好的 description
description: 自动检查 Java 项目的代码规范，支持 Checkstyle 和 SpotBugs 规则集
# ❌ 不好的 description
description: 最强代码审查工具，让你的代码完美无缺
1
2
3
4
5
2
3
4
5
# 2. 写明依赖
明确列出运行所需的外部条件：
- 环境变量：API Key、数据库连接串等
- 外部 API：调用了哪些第三方服务
- 文件读写范围：需要访问哪些目录
- 网络访问：是否需要联网
# 依赖声明示例
# 依赖：
# - 环境变量: GITHUB_TOKEN（用于调用 GitHub API）
# - 外部 API: https://api.github.com
# - 文件读写: 项目根目录的 .git/ 目录
# - 网络访问: 需要
1
2
3
4
5
6
2
3
4
5
6
# 3. 提供可复现示例
至少给一个 Agent 能直接执行的示例：
# 示例：使用该 Skill 检查代码规范
# 1. 进入项目目录
cd /path/to/project
# 2. 运行检查脚本
bash scripts/check-style.sh
# 3. 查看报告
cat reports/style-report.txt
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
# 4. 安全注意事项
涉及脚本执行时，说明平台差异与安全风险：
- 标明支持的操作系统（Linux / macOS / Windows）
- 提示需要哪些权限（如文件写入、网络访问）
- 声明不会执行的敏感操作（如不修改用户主目录外的文件）
# 四、完整 SKILL.md 示例
以下是一个完整的 Skill 技能包示例：
---
name: java-code-review
description: 自动审查 Java 项目的代码规范，支持 Checkstyle 规则集，生成结构化报告
---
# Java Code Review Skill
## 适用场景
当用户要求检查 Java 代码规范、审查代码质量、或运行 Checkstyle 时触发。
## 输入
- 项目根目录路径（必须包含 pom.xml 或 build.gradle）
- 可选：自定义规则集文件路径
## 输出
- Markdown 格式的审查报告
- 问题统计（按严重程度分类）
## 依赖
- 环境变量: JAVA_HOME（JDK 11+）
- 工具: Maven 或 Gradle
- 文件读写: 项目目录
- 网络访问: 不需要
## 使用示例
\`\`\`bash
# 基本用法
cd /path/to/java-project
bash scripts/run-review.sh
# 指定自定义规则
bash scripts/run-review.sh --rules /path/to/custom-rules.xml
\`\`\`
## 安全声明
- 仅读取项目目录内的文件
- 不修改任何源代码
- 不发起网络请求
- 支持 Linux 和 macOS，Windows 需 WSL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
# 五、发布与安装
# 打包
cd my-skill
zip -r ../my-skill.zip . -x "*.DS_Store" -x "*__pycache__*"
1
2
2
# 安装方式
通过 ClawHub 安装：
openclaw skill install @global/my-skill
1
或从本地 ZIP 安装：
openclaw skill install ./my-skill.zip
1
# 验证安装
openclaw skill list
# 应显示 my-skill，状态为 enabled
1
2
2
# 六、开发最佳实践
# DO
- ✅ description 写清楚边界（做什么 + 不做什么）
- ✅ 保持包体精简，只包含必要文件
- ✅ 提供可复现的示例
- ✅ 声明所有外部依赖
- ✅ 测试不同操作系统下的兼容性
# DON'T
- ❌ 不要在 Skill 中硬编码敏感信息（密码、Token）
- ❌ 不要夸大能力范围
- ❌ 不要包含构建产物、临时文件
- ❌ 不要让脚本执行未经声明的敏感操作
- ❌ 不要省略安全声明
# 总结
| 步骤 | 关键点 |
|---|---|
| 1. 设计目录结构 | 精简，只含必要文件 |
| 2. 编写 SKILL.md | description 精准、依赖明确、示例可复现 |
| 3. 声明安全边界 | 支持平台、权限要求、不会做的事 |
| 4. 打包发布 | ZIP 格式，排除无关文件 |
| 5. 验证安装 | 确认 Agent 能正确识别和触发 |
开发 Skill 的核心思路：你不是在写代码，而是在教 Agent 一项新能力。把 SKILL.md 当成给 Agent 的「说明书」，写得越清晰，Agent 匹配得越准。
本文参考 OpenClaw Skill 开发规范整理。