# 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 里各写一遍）