79 lines
2.9 KiB
Markdown
79 lines
2.9 KiB
Markdown
# Skill 创建指南
|
||
|
||
基于 OpenClaw 官方 skill-creator 提炼的核心要点。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
skill-name/
|
||
├── SKILL.md # 必需：frontmatter + markdown 指令
|
||
├── scripts/ # 可选：可执行脚本（Python/Bash）
|
||
├── references/ # 可选：参考文档，按需加载
|
||
└── assets/ # 可选：输出用资源（模板、图片、字体等）
|
||
```
|
||
|
||
## SKILL.md 核心结构
|
||
|
||
### Frontmatter（必需）
|
||
|
||
```yaml
|
||
---
|
||
name: skill-name
|
||
description: 详细描述技能做什么，以及何时触发。这是唯一决定 skill 是否被加载的字段。
|
||
必须包含所有"何时使用"的信息——不要放在正文里。正文只在触发后才加载。
|
||
---
|
||
```
|
||
|
||
- 仅需 `name` 和 `description` 两个字段
|
||
- `name` 要求：小写字母 + 数字 + 连字符，不超过 64 字符
|
||
|
||
### 正文原则
|
||
|
||
1. **简洁至上**：上下文窗口是公共资源，只写 AI 不知道的信息
|
||
2. **指令式**：用祈使句写，不是描述
|
||
3. **选择自由度**：脆弱操作给低自由度（精确脚本），灵活操作给高自由度（文字指引）
|
||
4. **渐进式加载**：正文 < 500 行，详细内容放 references，按需加载
|
||
|
||
## 三层次加载
|
||
|
||
1. **元数据**（name + description）— 始终在上下文中（~100 词）
|
||
2. **SKILL.md 正文** — 触发后加载（< 5000 词）
|
||
3. **bundled resources** — 按需加载（无限制）
|
||
|
||
## 资源目录
|
||
|
||
| 目录 | 用途 | 示例 |
|
||
|:---|:---|:---|
|
||
| `scripts/` | 可执行代码，可不经加载直接执行 | `rotate_pdf.py` |
|
||
| `references/` | 参考文档，加载到上下文中阅读 | `api_docs.md`, `schema.md` |
|
||
| `assets/` | 输出用资源，不加载到上下文 | 模板、图标、字体 |
|
||
|
||
## 常见正文结构
|
||
|
||
1. **工作流型**：适合有序步骤 → `## Overview → ## Workflow → ## Step 1 → ## Step 2...`
|
||
2. **任务型**：适合工具集 → `## Overview → ## Quick Start → ## Task A → ## Task B...`
|
||
3. **参考/指南型**：适合规范标准 → `## Overview → ## Guidelines → ## Specifications...`
|
||
4. **能力型**：适合集成系统 → `## Overview → ## Core Capabilities → ### 1. ...`
|
||
|
||
## 创建流程
|
||
|
||
1. 明确使用场景（从具体例子出发）
|
||
2. 规划可复用资源（scripts/references/assets）
|
||
3. `./scripts/init_skill.py <name> --path skills/ --resources scripts,references,assets`
|
||
4. 编辑 SKILL.md 和资源文件，删除不需要的
|
||
5. `./scripts/package_skill.py skills/<name>` 打包验证
|
||
|
||
## 命名规范
|
||
|
||
- 小写字母 + 数字 + 连字符
|
||
- 优先动词开头的短语，描述动作
|
||
- 有明确的工具命名空间时加上前缀（如 `gh-address-comments`）
|
||
- 文件夹名等于技能名
|
||
|
||
## 禁止事项
|
||
|
||
- ❌ 不创建 README、CHANGELOG 等附加文档
|
||
- ❌ 不含构建过程、测试步骤、用户文档
|
||
- ❌ 不嵌套引用（references 之间不要互相引用）
|
||
- ❌ 信息不重复（不在 SKILL.md 和 references 里各写一遍）
|