编辑、完善或审查 AgentSkills。当需要创建新技能、对现有 SKILL.md 进行修改、清理/审计/整理技能文件时激活此技能。触发词:编辑技能, skill 注意事项, metadata 检查, 完善技能, 清理技能, 审计技能, skill 规范, 编写 skill, 新建技能
---
name: skill-editor
description: "编辑、完善或审查 AgentSkills。当需要创建新技能、对现有 SKILL.md 进行修改、清理/审计/整理技能文件时激活此技能。触发词:编辑技能, skill 注意事项, metadata 检查, 完善技能, 清理技能, 审计技能, skill 规范, 编写 skill, 新建技能"
metadata:
version: 1.2.4
author: lejian
homepage: https://clawhub.ai/skills/skill-editor
tags:
- skill
- editor
- openclaw
openclaw:
requires:
env.vars: {}
---
# Skill Editor
编辑和完善 AgentSkills 的指南。创建或修改技能时参考此指南。
## 目录结构
```
skills/<skill-name>/
├── SKILL.md # 必须:技能定义文件
├── package.json # 必须(publish 时需要 displayName 等元信息)
├── scripts/ # 可选:脚本文件
└── references/ # 可选:参考文档
```
**不要**创建额外的文档文件(README.md、CHANGELOG.md 等)。
---
## Frontmatter 必检清单
每次编辑 SKILL.md 时,**必须**检查以下字段是否正确:
### 必要字段一览
| 字段 | 要求 | 常见错误 |
|------|------|----------|
| `name` | kebab-case,与目录名一致 | 写成驼峰、大小写不匹配目录名 |
| `description` | 触发条件描述,含中英文关键词,100 字左右 | 太短(无触发词)、太长(超过 200 字) |
| `metadata` | 顶级字段,与 name、description 平级 | 缺失、缩进错误、嵌套在 description 下 |
| `requires.env.vars` | 脚本依赖的环境变量必须声明,不能只写在正文 | 脚本用了变量但 `requires.env.vars` 为空或漏填 |
---
### metadata 块(必须存在)
**结构**:
```yaml
metadata:
version: 1.0.0
author: <作者名>
homepage: <技能主页 URL>
tags:
- <标签1>
- <标签2>
openclaw:
requires:
env.vars: {} # 无依赖时必须写空对象,不能省略
```
**关键规则**:
1. `metadata` 是顶级字段,与 `name`、`description` 平级
2. `openclaw.requires.env.vars` 填写脚本依赖的环境变量(如 API Token)
3. 没有环境变量依赖时,`requires.env.vars` 写空对象 `{}`,**不能省略 `openclaw.requires` 块**
---
### package.json(publish 时必须保留)
发布到 ClawHub 需要 package.json 中的 `displayName` 等元信息。
**典型结构**:
```json
{
"name": "skill-name",
"version": "1.0.0",
"displayName": "技能显示名称",
"description": "技能一句话描述"
}
```
**编辑时注意事项**:
- 不要删除或覆盖 package.json
- 改完 SKILL.md 后检查 package.json 是否仍然完整
> ⚠️ **clawhub publish 不会自动读取 package.json 的 displayName**,必须通过 `--name` 显式传入。如果只传 `--version` 不传 `--name`,clawhub 会使用 package.json 中的 `name` 字段而非 `displayName`,导致发布后显示的名称不正确。
---
## 正确示例
**无环境变量依赖**:
```yaml
---
name: my-skill
description: "我的技能描述"
metadata:
version: 1.0.0
author: lejian
homepage: https://clawhub.ai/skills/my-skill
tags:
- my-skill
openclaw:
requires:
env.vars: {}
---
```
**有环境变量依赖**:
```yaml
---
name: my-api-skill
description: "调用外部 API 的技能"
metadata:
version: 1.0.0
author: lejian
homepage: https://clawhub.ai/skills/my-api-skill
tags:
- api
openclaw:
requires:
env.vars:
MY_API_TOKEN: "API Token,说明配置方式"
LEJIAN_AUTH_TOKEN: "乐荐 API Token,配置方式:openclaw config set env.vars.LEJIAN_AUTH_TOKEN <token>"
---
```
---
## 常见错误
❌ `metadata` 缩进错误(嵌套在 description 下面)或字段缺失
❌ `requires.env.vars` 写成空对象 `{}`,但实际脚本有环境变量依赖
❌ `requires` 写成 `require` 或其他拼写
❌ 只在正文写"需要配置 API Token",但 `requires.env.vars` 为空
❌ 环境变量名与脚本中实际使用的名字不一致
❌ 编辑 SKILL.md 时覆盖/删除了 package.json(publish 时丢 displayName)
❌ `description` 缺少触发词,导致 skill 无法被正确激活
---
## 编辑现有技能时的检查项
> 💡 建议先加载 `skill-creator` 技能了解编辑流程,但这不是强制要求,可以直接编辑 skill 文件。
1. **修改 `description`** — 确认触发词仍然准确,保留中英文关键词
2. **修改 `name`** — 同时修改目录名,保持一致
3. **新增环境变量依赖** — 同时在 `metadata.openclaw.requires.env.vars` 中声明
4. **version 更新** — 如有实质性变更,版本号 +0.0.1
5. **删除环境变量依赖** — 从 `requires.env.vars` 中移除对应条目
6. **检查 package.json** — 确保 displayName、version 等字段没有在编辑时被覆盖
7. **版本一致性** — 修改 version 后,**必须确保 SKILL.md metadata.version 和 package.json version 完全一致**,否则 clawhub 发布后会显示旧版本
8. **发布时** — clawhub publish 的 `--version` 参数也必须与上述两处版本号保持一致,三者缺一不可
---
## 常见问题处理
### 忘记加 metadata
在 `description` 行**之后**、`---` 行**之前**插入 metadata 块:
```python
pattern = r'(description: [^\n]+\n)(\n---\n# )'
replacement = r'\1metadata:\n version: 1.0.0\n author: lejian\n homepage: ...\n tags:\n - xxx\n openclaw:\n requires:\n env.vars: {}\n\2'
```
### 检查所有 skill 的 metadata 完整性
```bash
find ~/workspace/agent/skills -name "SKILL.md" | while read f; do
if grep -q "^metadata:" "$f"; then
echo "✅ $f"
else
echo "❌ $f (missing metadata)"
fi
done
```
### 查找所有 skills 目录
```
~/workspace/agent/skills/ # 用户安装的 skill
~/workspace/agent/extensions/*/skills/ # 扩展自带的 skill
~/.npm-global/lib/node_modules/openclaw/skills/ # 内置 skill
```don't have the plugin yet? install it then click "run inline in claude" again.