{"skill":{"slug":"skill-editor","displayName":"技能编辑器","summary":"编辑、完善或审查 AgentSkills。当需要创建新技能、对现有 SKILL.md 进行修改、清理/审计/整理技能文件时激活此技能。触发词：编辑技能, skill 注意事项, metadata 检查, 完善技能, 清理技能, 审计技能, skill 规范, 编写 skill, 新建技能","description":"---\nname: skill-editor\ndescription: \"编辑、完善或审查 AgentSkills。当需要创建新技能、对现有 SKILL.md 进行修改、清理/审计/整理技能文件时激活此技能。触发词：编辑技能, skill 注意事项, metadata 检查, 完善技能, 清理技能, 审计技能, skill 规范, 编写 skill, 新建技能\"\nmetadata:\n  version: 1.2.4\n  author: lejian\n  homepage: https://clawhub.ai/skills/skill-editor\n  tags:\n    - skill\n    - editor\n    - openclaw\n  openclaw:\n    requires:\n      env.vars: {}\n---\n\n# Skill Editor\n\n编辑和完善 AgentSkills 的指南。创建或修改技能时参考此指南。\n\n## 目录结构\n\n```\nskills/<skill-name>/\n├── SKILL.md          # 必须：技能定义文件\n├── package.json      # 必须（publish 时需要 displayName 等元信息）\n├── scripts/          # 可选：脚本文件\n└── references/       # 可选：参考文档\n```\n\n**不要**创建额外的文档文件（README.md、CHANGELOG.md 等）。\n\n---\n\n## Frontmatter 必检清单\n\n每次编辑 SKILL.md 时，**必须**检查以下字段是否正确：\n\n### 必要字段一览\n\n| 字段 | 要求 | 常见错误 |\n|------|------|----------|\n| `name` | kebab-case，与目录名一致 | 写成驼峰、大小写不匹配目录名 |\n| `description` | 触发条件描述，含中英文关键词，100 字左右 | 太短（无触发词）、太长（超过 200 字） |\n| `metadata` | 顶级字段，与 name、description 平级 | 缺失、缩进错误、嵌套在 description 下 |\n| `requires.env.vars` | 脚本依赖的环境变量必须声明，不能只写在正文 | 脚本用了变量但 `requires.env.vars` 为空或漏填 |\n\n---\n\n### metadata 块（必须存在）\n\n**结构**：\n\n```yaml\nmetadata:\n  version: 1.0.0\n  author: <作者名>\n  homepage: <技能主页 URL>\n  tags:\n    - <标签1>\n    - <标签2>\n  openclaw:\n    requires:\n      env.vars: {}   # 无依赖时必须写空对象，不能省略\n```\n\n**关键规则**：\n\n1. `metadata` 是顶级字段，与 `name`、`description` 平级\n2. `openclaw.requires.env.vars` 填写脚本依赖的环境变量（如 API Token）\n3. 没有环境变量依赖时，`requires.env.vars` 写空对象 `{}`，**不能省略 `openclaw.requires` 块**\n\n---\n\n### package.json（publish 时必须保留）\n\n发布到 ClawHub 需要 package.json 中的 `displayName` 等元信息。\n\n**典型结构**：\n\n```json\n{\n  \"name\": \"skill-name\",\n  \"version\": \"1.0.0\",\n  \"displayName\": \"技能显示名称\",\n  \"description\": \"技能一句话描述\"\n}\n```\n\n**编辑时注意事项**：\n- 不要删除或覆盖 package.json\n- 改完 SKILL.md 后检查 package.json 是否仍然完整\n\n> ⚠️ **clawhub publish 不会自动读取 package.json 的 displayName**，必须通过 `--name` 显式传入。如果只传 `--version` 不传 `--name`，clawhub 会使用 package.json 中的 `name` 字段而非 `displayName`，导致发布后显示的名称不正确。\n\n---\n\n## 正确示例\n\n**无环境变量依赖**：\n\n```yaml\n---\nname: my-skill\ndescription: \"我的技能描述\"\nmetadata:\n  version: 1.0.0\n  author: lejian\n  homepage: https://clawhub.ai/skills/my-skill\n  tags:\n    - my-skill\n  openclaw:\n    requires:\n      env.vars: {}\n---\n```\n\n**有环境变量依赖**：\n\n```yaml\n---\nname: my-api-skill\ndescription: \"调用外部 API 的技能\"\nmetadata:\n  version: 1.0.0\n  author: lejian\n  homepage: https://clawhub.ai/skills/my-api-skill\n  tags:\n    - api\n  openclaw:\n    requires:\n      env.vars:\n        MY_API_TOKEN: \"API Token，说明配置方式\"\n        LEJIAN_AUTH_TOKEN: \"乐荐 API Token，配置方式：openclaw config set env.vars.LEJIAN_AUTH_TOKEN <token>\"\n---\n```\n\n---\n\n## 常见错误\n\n❌ `metadata` 缩进错误（嵌套在 description 下面）或字段缺失\n❌ `requires.env.vars` 写成空对象 `{}`，但实际脚本有环境变量依赖\n❌ `requires` 写成 `require` 或其他拼写\n❌ 只在正文写\"需要配置 API Token\"，但 `requires.env.vars` 为空\n❌ 环境变量名与脚本中实际使用的名字不一致\n❌ 编辑 SKILL.md 时覆盖/删除了 package.json（publish 时丢 displayName）\n❌ `description` 缺少触发词，导致 skill 无法被正确激活\n\n---\n\n## 编辑现有技能时的检查项\n\n> 💡 建议先加载 `skill-creator` 技能了解编辑流程，但这不是强制要求，可以直接编辑 skill 文件。\n\n1. **修改 `description`** — 确认触发词仍然准确，保留中英文关键词\n2. **修改 `name`** — 同时修改目录名，保持一致\n3. **新增环境变量依赖** — 同时在 `metadata.openclaw.requires.env.vars` 中声明\n4. **version 更新** — 如有实质性变更，版本号 +0.0.1\n5. **删除环境变量依赖** — 从 `requires.env.vars` 中移除对应条目\n6. **检查 package.json** — 确保 displayName、version 等字段没有在编辑时被覆盖\n7. **版本一致性** — 修改 version 后，**必须确保 SKILL.md metadata.version 和 package.json version 完全一致**，否则 clawhub 发布后会显示旧版本\n8. **发布时** — clawhub publish 的 `--version` 参数也必须与上述两处版本号保持一致，三者缺一不可\n\n---\n\n## 常见问题处理\n\n### 忘记加 metadata\n\n在 `description` 行**之后**、`---` 行**之前**插入 metadata 块：\n\n```python\npattern = r'(description: [^\\n]+\\n)(\\n---\\n# )'\nreplacement = 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'\n```\n\n### 检查所有 skill 的 metadata 完整性\n\n```bash\nfind ~/workspace/agent/skills -name \"SKILL.md\" | while read f; do\n  if grep -q \"^metadata:\" \"$f\"; then\n    echo \"✅ $f\"\n  else\n    echo \"❌ $f (missing metadata)\"\n  fi\ndone\n```\n\n### 查找所有 skills 目录\n\n```\n~/workspace/agent/skills/                  # 用户安装的 skill\n~/workspace/agent/extensions/*/skills/     # 扩展自带的 skill\n~/.npm-global/lib/node_modules/openclaw/skills/  # 内置 skill\n```","tags":{"latest":"1.2.4","editor":"1.2.0","skill":"1.2.0"},"stats":{"comments":0,"downloads":438,"installsAllTime":0,"installsCurrent":0,"stars":0,"versions":7},"createdAt":1777699131974,"updatedAt":1778492826217},"latestVersion":{"version":"1.2.4","createdAt":1777709085420,"changelog":"将 skill-creator 强制要求改为可选建议，避免 Goal Hijack 风险","license":"MIT-0"},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"romicboy","userId":"s172sh6z2pmn5q6em9s06b2qzx85krbk","displayName":"沈荣明","image":"https://avatars.githubusercontent.com/u/2356195?v=4"},"moderation":null}