📦 技能编辑器

技能编辑器 编辑和完善 AgentSkills 的指南。创建或修改技能时参考此指南。

目录结构 skills// ├── 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 块（必须存在） 结构： metadata: version: 1.0.0 author: <作者名> homepage: <技能主页 URL> tags: - <标签1> - <标签2> openclaw: requires: env.vars: {} # 无依赖时必须写空对象，不能省略 关键规则： metadata 是顶级字段，与 name、description 平级 openclaw.requires.env.vars 填写脚本依赖的环境变量（如 API Token） 没有环境变量依赖时，requires.env.vars 写空对象 {}，不能省略 openclaw.requires 块 package.json（publish 时必须保留） 发布到 ClawHub 需要 package.json 中的 displayName 等元信息。 典型结构： { "name": "skill-name", "version": "1.0.0", "displayName": "技能显示名称", "description": "技能一句话描述" } 编辑时注意事项： 不要删除或覆盖 package.json 改完 SKILL.md 后检查 package.json 是否仍然完整 正确示例 无环境变量依赖：

---

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: {}

---

有环境变量依赖：

---

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 "

---

常见错误 metadata 缩进错误（嵌套在 description 下面）或字段缺失 requires.env.vars 写成空对象 {}，但实际脚本有环境变量依赖 requires 写成 require 或其他拼写 只在正文写"需要配置 API Token"，但 requires.env.vars 为空 环境变量名与脚本中实际使用的名字不一致 编辑 SKILL.md 时覆盖/删除了 package.json（publish 时丢 displayName） description 缺少触发词，导致 skill 无法被正确激活 编辑现有技能时的检查项 编辑已有 skill 前，必须先加载 skill-creator 技能，严格按其指引操作，禁止跳过直接编辑文件。 修改 description — 确认触发词仍然准确，保留中英文关键词 修改 name — 同时修改目录名，保持一致 新增环境变量依赖 — 同时在 metadata.openclaw.requires.env.vars 中声明 version 更新 — 如有实质性变更，版本号 +0.0.1 删除环境变量依赖 — 从 requires.env.vars 中移除对应条目 检查 package.json — 确保 displayName、version 等字段没有在编辑时被覆盖 常见问题处理 忘记加 metadata 在 description 行之后、--- 行之前插入 metadata 块： 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 完整性 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