# 如何创建 OpenClaw 技能

本技能指导你为 OpenClaw 框架创建符合规范的技能，基于 ClawHub 官方生态和多个高人气参考技能的最佳实践。

## 核心概念

OpenClaw 技能（Skill）是一个自包含的指令包，由 `SKILL.md`（核心指令文件）和 `_meta.json`（元数据文件）组成，支持模块化结构、渐进式披露和 Token 高效设计。

## 创建流程

### 1. 前置准备

- 检查是否已有同类技能：在 [ClawHub](https://clawhub.ai) 搜索，避免重复
- 明确技能功能边界、适用场景和触发条件
- 参考 `spec.md` 了解完整规范

### 2. 创建技能目录

```bash
# 方式一：手动创建
mkdir -p openclaw/skills/<skill-name>
touch openclaw/skills/<skill-name>/SKILL.md
touch openclaw/skills/<skill-name>/_meta.json

# 方式二：使用脚手架工具（推荐）
npm install -g skill-scaffold
skill-scaffold <skill-name> --author <your-name> --description "描述"
```

### 3. 编写 SKILL.md

`SKILL.md` 是技能的核心，结构如下：

```markdown
---
name: my-skill-name
description: Process, merge, and extract PDF content
---

## When to Use
- 用户提到 X 时触发
- 用户需要 Y 时触发

## Core Rules
1. 规则一
2. 规则二
3. 规则三

## Quick Start
最小可行示例...

## Workflow
复杂任务的步骤清单...

## Advanced
链接至独立参考文件...
```

### 4. 编写 _meta.json

```json
{
  "name": "my-skill-name",
  "version": "1.0.0",
  "description": "Process, merge, and extract PDF content",
  "tags": ["pdf", "extraction", "utility"]
}
```

### 5. 按需添加辅助文件

- `references/` — 详细参考文档（按需加载）
- `scripts/` — 辅助脚本
- `examples/` — 使用示例

### 6. 本地验证

```bash
# 重启 OpenClaw 网关以识别新技能
openclaw gateway restart
```

### 7. 发布到 ClawHub

```bash
# 认证（需 GitHub 账号，注册满 2 周）
openclaw auth login

# 发布
openclaw skills publish <local-path> \
  --slug <skill-slug> \
  --name <skill-name> \
  --version 1.0.0 \
  --tags "tag1,tag2"
```

## 关键规范

### 描述（Description）编写规范

描述是代理识别并加载技能的**唯一依据**，至关重要：

- 上限 1024 字符
- 采用第三人称
- 首句阐述核心能力（15-25 词，以动作动词开头）
- 次句明确触发条件，必须包含 `"Use when..."`

| 错误示例 | 正确示例 |
|---------|---------|
| "Use when user needs PDFs" | "Process, merge, and extract PDF content" |
| "Helper for Docker" | "Build, deploy, and debug Docker containers" |
| "Helps with documents." | "Extract text and tables from PDF files. Use when processing PDFs or when user mentions form extraction." |

### 核心规则

1. **保持简短**：核心文件 30-50 行，上限 80 行
2. **渐进式披露**：元数据始终加载 → 核心主体触发时加载 → 辅助文件按需加载
3. **辅助文件优先**：超过 20 行的内容拆分至独立文件
4. **避免冗余**：信息仅存一处，通过引用避免重复
5. **发布前测试**：以全新代理视角审查指令是否清晰且必要

### 常见陷阱

| 陷阱 | 说明 |
|------|------|
| 解释基础概念 | 模型已知，应说明何时及如何使用 |
| 描述中使用触发条件 | 浪费字符，仅用动作动词 |
| 描述中堆砌关键词 | 像垃圾邮件，写精炼的一句话 |
| 模板内联 | 核心文件臃肿，分离到独立文件 |
| 模糊的"观察"指令 | 易被标记可疑，需明确具体数据 |
| 未声明的文件创建 | 触发安全警告，需添加数据存储说明 |

## 安全验证标准

技能发布需通过：
- 静态扫描：检查格式、字段完整性
- LLM 分析：审查用途匹配度、安装机制、权限需求
- 触发词范围：避免过宽导致意外激活
- 文件操作：修改工作区前需获取用户明确批准

## 工具链

| 工具 | 用途 |
|------|------|
| [skill-scaffold](https://clawhub.ai/nextfrontierbuilds/skill-scaffold) | CLI 脚手架工具，快速生成技能目录结构 |
| [skill-builder](https://clawhub.ai/ivangdavila/skill-builder) | 交互式技能构建引导，审查质量 |
| [skill-factory](https://clawhub.ai/smallkeyboy/smallkeyboy-create-skill) | 程序化批量创建技能 |
| `openclaw skills install` | 安装技能 |
| `openclaw gateway restart` | 重启网关识别新技能 |
| `openclaw skills publish` | 发布技能到 ClawHub |

## 官方参考技能

| 技能名称 | 作者 | 说明 |
|---------|------|------|
| [Skill Builder / Creator](https://clawhub.ai/ivangdavila/skill-builder) | ivangdavila | 模块化与渐进式披露设计，质量把控 |
| [Skill Scaffold](https://clawhub.ai/nextfrontierbuilds/skill-scaffold) | nextfrontierbuilds | 多平台兼容 CLI 脚手架工具 |
| [OpenClaw Skill Creator](https://clawhub.ai/yejay7/create-skill-openclaw) | yejay7 | OpenClaw 专属创建指南 |
| [Write A Skill](https://clawhub.ai/liyafeichina/write-a-skill) | liyafeichina | 技能编写规范与渐进式披露 |
| [Skill 创建工厂](https://clawhub.ai/smallkeyboy/smallkeyboy-create-skill) | smallkeyboy | 程序化批量创建 |
| [Create Skills](https://clawhub.ai/ryanallen/document-skills) | ryanallen | 技能文档编写指导 |
| [Clawhub Skill Creator](https://clawhub.ai/erview/clawhub-skill-creator) | erview | ClawHub 平台发布指南 |