# OpenClaw 技能规范摘要

> 基于 ClawHub 官方生态和多个高人气参考技能整理。完整规范请参阅 [ClawHub](https://clawhub.ai)。

## 文件结构

```
<skill-name>/
├── SKILL.md          # 核心指令文件（必填）
├── _meta.json        # 元数据文件（必填）
├── references/       # 按需加载的参考文档（可选）
├── scripts/          # 辅助脚本（可选）
├── examples/         # 使用示例（可选）
└── CHANGELOG.md      # 版本变更记录（推荐）
```

## SKILL.md 规范

### YAML 前置信息（Frontmatter）

```yaml
---
name: my-skill-name          # 小写 + 连字符，全局唯一
description: 15-25 词描述     # 上限 160 字符（ClawHub 搜索摘要）
---
```

**注意**：YAML 前置信息**仅需** `name` 和 `description` 两个字段，不要添加多余字段。

### 核心章节结构

| 章节 | 说明 |
|------|------|
| `## When to Use` | 定义激活触发条件（关键词、场景） |
| `## Core Rules` | 3-7 条编号规则，约束技能行为 |
| `## Quick Start` | 最小可行示例 |
| `## Workflow` | 复杂任务的步骤清单 |
| `## Advanced` | 链接至独立参考文件（渐进式披露） |

### 编写原则

- 核心文件控制在 **30-50 行**，上限 80 行
- 超过 20 行的内容拆分至独立文件
- 信息仅存一处，通过引用避免重复
- 以全新代理视角审查指令是否清晰且必要

## _meta.json 规范

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

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | string | 是 | 小写 + 连字符，与 YAML 一致 |
| `version` | string | 是 | 语义化版本号 |
| `description` | string | 是 | 与 YAML 一致 |
| `tags` | array | 否 | 搜索关键词 |

## Description 编写规范

描述是代理识别并加载技能的**唯一依据**：

- 上限 1024 字符
- 第三人称
- 首句：15-25 词，以动作动词开头，描述能力
- 次句：触发条件，包含 `"Use when..."`

## 渐进式披露（三层加载机制）

| 层级 | 内容 | 加载时机 |
|------|------|---------|
| L1 元数据 | `name`、`description` | 始终加载 |
| L2 核心主体 | `SKILL.md` 正文 | 触发时加载 |
| L3 辅助文件 | `references/`、`scripts/` | 按需加载 |

## 安全验证标准

发布时技能需通过：

1. **静态扫描**：YAML 格式、字段完整性、文件结构
2. **LLM 分析**：用途匹配度、安装机制、权限需求
3. **触发词审查**：范围不能过宽，防止意外激活
4. **文件操作审查**：修改工作区前需用户明确批准

## 发布流程

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

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

## 常见问题

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| 无效目录路径 | 使用了相对路径 | 使用绝对路径 |
| 认证失败 | GitHub 账号不满 2 周 | 等待或换账号 |
| 技能不可见 | YAML 前置信息字段过多 | 只保留 `name` 和 `description` |
| 技能未被识别 | 网关未重启 | 执行 `openclaw gateway restart` |