名称： skillcraft
描述： 设计与构建 OpenClaw 技能。当被要求“制作/构建/设计一个技能”、将临时功能提取为技能或将脚本/指令打包以供复用时使用。涵盖 OpenClaw 特定集成（工具调用、记忆、消息路由、定时任务、画布、节点）和 ClawHub 发布。
元数据： {"openclaw":{"emoji":"🧶"}}

Skillcraft — OpenClaw 技能设计器

一份关于创建 OpenClaw 技能的指导性指南。重点在于 OpenClaw 特定集成 —— 消息路由、定时任务调度、记忆持久化、频道格式化、前置元数据门控 —— 而非通用编程建议。

文档： https://docs.openclaw.ai/tools/skills · https://docs.openclaw.ai/tools/creating-skills

模型说明

本技能专为前沿模型（Opus, Sonnet）编写。如果您使用的是较便宜的模型，并发现某个阶段描述不够详细，请自行扩展 —— 设计序列是一个脚手架，而非脚本。较便宜的模型应：

• 在架构设计前，更仔细地阅读 {baseDir}/patterns/ 中的模式文件
• 在阶段 2（能力发现）上花费更多时间 —— 明确列举 OpenClaw 特性
• 在阶段 4（规范）中更有条理 —— 在实现前写出完整结构
• 对任何 OpenClaw 特性不确定时，查阅 https://docs.openclaw.ai

设计流程

阶段 0：清点（仅限提取）

从零构建时跳过此阶段。当需要将现有功能（脚本、TOOLS.md 章节、对话模式、重复指令）打包成技能时使用。

收集现有内容、存放位置、有效部分和脆弱部分。然后进入阶段 1。

阶段 1：问题理解

与用户一起梳理：

1. 这个技能做什么？（一句话概括）
2. 它应该在何时加载？ 示例短语、任务中触发、定时触发
3. 成功是什么样子？ 每个示例的具体成果

阶段 2：能力发现

通用性

尽早提问：这是为您的设置设计的，还是应该在任何 OpenClaw 实例上都能工作？

技能协同（仅限特定）

从系统提示中扫描 <available_skills>，寻找互补能力。阅读有潜力的技能以了解组合机会。

OpenClaw 特性

结合技能需求查阅文档。以组合方式思考 —— OpenClaw 的原语能以强大方式组合。需要查阅的关键文档：

查看 {baseDir}/patterns/composable-examples.md 获取组合这些特性的灵感。

阶段 3：架构设计

基于阶段 1-2，确定适用的模式：

加载所有适用的模式并进行综合。大多数技能会组合多种模式。

脚本与指令的划分： 脚本处理确定性机制（API 调用、数据收集、文件处理）。SKILL.md 指令处理判断（解释结果、选择方法、组合输出）。划分边界是：一个智能程度较低的系统能否可靠地完成？如果可以 → 脚本。

阶段 4：设计规范

向用户展示提议的架构以供审阅：

1. 技能结构 —— 文件和目录
2. SKILL.md 大纲 —— 章节和关键内容
3. 组件 —— 脚本、模块、封装器
4. 状态 —— 无状态、会话状态或有状态（以及存放位置）
5. OpenClaw 集成 —— 使用哪些特性，它们如何交互
6. 密钥 —— 环境变量、密钥链、配置文件（在设置部分记录，切勿硬编码）

状态存放位置：
- <workspace>/memory/ —— 面向用户的上下文
- {baseDir}/state.json —— 技能内部状态（随技能迁移）
- <workspace>/state/<skill>.json —— 公共工作空间区域中的技能状态

如果是提取现有功能：包含迁移说明（哪些内容移动，哪些工作空间文件需要更新）。

验证： 它是否处理了阶段 1 的所有示例？是否存在矛盾？边缘情况？

与用户迭代直到满意为止。这是以低成本发现设计问题的阶段。

阶段 5：实现

默认：同一会话。 按照规范逐步实现，并在每个步骤后由用户审阅。仅将复杂的脚本子组件交给子代理处理 —— SKILL.md 和集成逻辑保留在主会话中。

1. 创建技能目录 + SKILL.md 骨架（前置元数据 + 章节）
2. 脚本（如果有） —— 使其正常工作并经过测试
3. SKILL.md 主体 —— 完成指令编写
4. 对照阶段 1 的示例进行测试

如果是提取现有功能：更新工作空间文件，清理旧位置，验证独立运行。

编写前置元数据

前置元数据决定了可发现性和门控。格式遵循 AgentSkills 规范，并带有 OpenClaw 扩展。

---
**名称：** my-skill
**描述：** [为可发现性优化的描述 —— 见下文]
**主页：** https://github.com/user/repo  # 可选
**元数据：** {"openclaw":{"emoji":"🔧","requires":{"bins":["tool"],"env":["API_KEY"]},"primaryEnv":"API_KEY","install":[...]}}
---

关键： metadata 必须是 单行 JSON 对象（解析器限制）。

描述 —— 为可发现性而写

描述决定了技能是否会被加载。应包含：
- 核心能力 —— 它做什么
- 触发关键词 —— 用户可能会说的术语
- 适用场景 —— 技能适用的情境

测试：代理是否会为您的每个阶段 1 示例短语选择此技能？

前置元数据键

元数据门控

OpenClaw 在加载时使用 metadata.openclaw 过滤技能：

沙盒注意： requires.bins 在加载时检查 主机。如果在沙盒中，二进制文件也必须存在于容器内。

令牌预算

每个符合条件的技能会向系统提示添加约 97 个字符 + 名称 + 描述 + 位置路径。保持描述信息丰富但不臃肿 —— 每个字符都会在每次交互中消耗令牌。

安装规范

"install": [
  {"id": "brew", "kind": "brew", "formula": "tap/tool", "bins": ["tool"], "label": "通过 brew 安装"},
  {"id": "npm", "kind": "node", "package": "tool", "bins": ["tool"]},
  {"id": "uv", "kind": "uv", "package": "tool", "bins": ["tool"]},
  {"id": "go", "kind": "go", "package": "github.com/user/tool@latest", "bins": ["tool"]},
  {"id": "dl", "kind": "download", "url": "https://...", "archive": "tar.gz"}
]

路径约定

• 使用 {baseDir} 引用技能内部内容（脚本、状态、模式）
• 使用 <workspace>/ 引用工作空间文件（TOOLS.md, memory/ 等）
• 切勿硬编码绝对路径 —— 工作空间是可移植的
• 对于子代理场景，在任务描述中包含路径上下文（沙盒挂载点不同）

参考

• 模式文件：{baseDir}/patterns/ (cli-wrapper, api-wrapper, monitor, composable-examples)
• OpenClaw 文档：https://docs.openclaw.ai/tools/skills
• ClawHub：https://clawhub.com