Skillcraft — OpenClaw 技能设计器

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

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

模型说明

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

• 在开始架构之前，更仔细地阅读{baseDir}/patterns/目录中的模式文件
• 在阶段 2（能力发现）上花费更多时间——明确列举 OpenClaw 的功能特性
• 在阶段 4（规范制定）中更加系统化——在实施前写出完整的结构
• 参考https://docs.openclaw.ai当不确定任何OpenClaw功能时

设计流程

阶段0：功能盘点（仅提取）

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

收集现有内容：存在哪些功能、存放位置、有效部分、脆弱环节。完成后进入阶段1。

阶段1：问题理解

与用户协作完成：

1. 这个技能实现什么功能？（一句话概括）
2. 何时应该加载此技能？触发示例：特定短语、任务中触发、计划触发
3. 成功标准是什么？每个示例对应的具体成果

阶段2：能力发现

通用性考量

尽早询问：此技能专为您的配置设计，还是应适用于任何OpenClaw实例？

技能协同（仅限特定模式）

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

OpenClaw 功能

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

参见{baseDir}/patterns/composable-examples.md以获取组合这些元素的灵感。

阶段3：架构设计

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

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

脚本与指令的划分：脚本处理确定性机制（API调用、数据收集、文件处理）。SKILL.md指令处理判断性操作（结果解读、方法选择、输出组合）。划分边界是：较低智能的系统能否可靠完成此项任务？若能 → 脚本。

第四阶段：设计规范

呈现提议的架构供用户审阅：

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 扩展。

---
name: my-skill
description: [description optimised for discovery — see below]
homepage: https://github.com/user/repo  # optional
metadata: {"openclaw":{"emoji":"🔧","requires":{"bins":["tool"],"env":["API_KEY"]},"primaryEnv":"API_KEY","install":[...]}}
---

关键点： 元数据必须为单行JSON对象（解析器限制）。

描述——为发现而写

描述决定了技能是否会被加载。包含：

• 核心能力——它能做什么
• 触发关键词——用户可能会说的词语
• 上下文——适用的情境

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

前置元数据键

元数据门控

OpenClaw 在加载时使用metadata.openclaw:

沙盒说明： requires.bins检查的是主机在加载时。如果启用沙箱，二进制文件也必须存在于容器内。

令牌预算

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

安装规范

"install": [
  {"id": "brew", "kind": "brew", "formula": "tap/tool", "bins": ["tool"], "label": "Install via 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