create-skill

创建技能

这是一个用于在 openclaw-superpowers 中引入新技能的元技能。每当你或贡献者想要添加新技能时，都请遵循此流程。

步骤 1：定义技能

开始编写前，请回答以下问题：

1. 此技能的作用是什么？（一句话）
2. Agent 应在何时使用它？（触发条件）
3. 它属于核心技能还是 OpenClaw 原生技能？
   • 核心技能： 通用 Agent 方法（头脑风暴、调试、规划）。适用于任何 Agent 运行时。
   • OpenClaw 原生技能： 需要持久化、长时间运行的会话或记忆。专为 OpenClaw 的常驻运行模式设计。
4. 现有技能是否已覆盖此功能？ 如果是，请扩展现有技能，而不是创建新技能。
5. 此技能是否需要在会话或唤醒之间保留状态？ 如果需要 → stateful: true + STATE_SCHEMA.yaml。

步骤 2：选择名称

• 使用 kebab-case：my-new-skill
• 名称应描述操作，而非类别：使用 retry-with-backoff，而不是 error-handling-utils
• 保持简短——最多 2–4 个词

步骤 3：搭建技能骨架

创建目录和文件：

skills/<core|openclaw-native>/<skill-name>/
  ├── SKILL.md
  └── STATE_SCHEMA.yaml   # only if stateful: true

使用 SKILL.md 的 frontmatter 模板（可选字段以注释形式展示）：

---
name: <skill-name>
description: <One sentence — what it does and when to use it.>
# cron: "<5-field cron expression>"   # optional: if skill runs on a schedule
# stateful: true                       # optional: if skill persists state
---

完整的内容结构请参见 TEMPLATE.md。

步骤 4：编写内容

遵循以下约定（总结自现有技能）：

• 直截了当。 开篇阐述核心原则，不要写前言。（“计划可避免无用功。”而不是“此技能可帮助你编写计划。”）
• 给出明确指示。 逐步明确告诉 Agent 要做什么。避免含糊的指导。
• 简洁。 此仓库中最好的技能都少于 50 行。如果内容更长，请拆分成更小的技能。
• 明确判断标准。 告诉 Agent 何时使用，何时不该使用。
• 使用检查清单执行验证步骤（参见 verification-before-completion）。
• 如果技能适用于跨多个会话的工作，请添加检查点指导。
• 在正文中描述状态保存方式是错误的。 如果技能描述了将进度保存到 Markdown 或记忆文件，请改用 stateful: true + STATE_SCHEMA.yaml。

步骤 5：验证

提交前，请检查：

• Frontmatter 正确——name 与目录名一致，description 是一个清晰的句子
• 文件路径正确——skills/<core|openclaw-native>/<name>/SKILL.md
• 与现有技能没有重叠——如果存在重叠，请合并或明确区分
• 遵循模板——包含 When to Use、The Process 和 Key Principles 部分
• 少于 80 行——如果更长，请考虑拆分
• 可执行——每个步骤都告诉 Agent 要做什么，而不是思考什么
• 可测试——查看输出即可判断 Agent 是否正确遵循了技能
• 如果设置了 stateful: true——STATE_SCHEMA.yaml 存在，且包含 version: 和 fields: 键
• 如果设置了 cron:——表达式符合有效的 5 字段 cron 语法

步骤 6：注册

无需手动注册。OpenClaw 会自动从扩展目录中发现技能。请确保：

1. 目录位于 skills/core/ 或 skills/openclaw-native/ 下
2. 文件名恰好为 SKILL.md
3. 安装符号链接已就位（install.sh 会处理）
4. 对于有状态技能，install.sh 会自动创建 ~/.openclaw/skill-state/<skill-name>/
5. 对于设置了 cron: 的技能，install.sh 会在下次运行时将其注册到 OpenClaw 的 cron 中

常见错误

• 过于抽象。“仔细考虑边界情况”不是一个技能步骤。“列出 3 个边界情况，并为每个情况编写一个测试”才是。
• **范围过广。**如果一个技能涵盖多个不同的工作流，就将其拆分。
• **缺少触发条件。**没有明确的“何时使用”标准，Agent 就不知道何时调用它。
• **重复现有技能。**创建类似内容前，请检查 brainstorming、writing-plans、systematic-debugging 和 verification-before-completion。
• **用散文描述状态。**如果你的技能描述了将进度保存到 Markdown 或记忆文件中，请改用 stateful: true 和 STATE_SCHEMA.yaml——这种方式结构化、机器可读且可恢复。