介绍
# Skillcraft — OpenClaw Skill Designer
一份创建 OpenClaw 技能的务实指南。重点关注 **OpenClaw 专用集成** —— 消息路由、Cron 调度、内存持久化、频道格式化、Frontmatter 门槛 —— 而非通用的编程建议。
**文档：** <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 实例？**
| 选择 | 含义 | |--------|-------------| | **通用** | 通用路径，无本地假设，适合 ClawHub | | **特定** | 可以引用本地技能、工具、工作区配置 |
#### 技能协同（仅限特定）
扫描系统提示词中的 `<available_skills>` 以寻找互补能力。阅读有前景的技能以了解组合机会。
#### OpenClaw 功能
结合技能需求回顾文档。从组合角度思考 —— OpenClaw 的基元能以强大的方式结合。需要查阅的关键文档：
| 需求 | 文档 | |------|-----| | 消息 | `/concepts/messages` | | Cron/调度 | `/automation/cron-jobs` | | 子代理 | `/tools/subagents` | | 浏览器 | `/tools/browser` | | Canvas UI | `/tools/` (canvas) | | 节点设备 | `/nodes/` | | 斜杠命令 | `/tools/slash-commands` |
请参阅 `{baseDir}/patterns/composable-examples.md` 以获取组合这些功能的灵感。
### 阶段 3：架构
基于第 1-2 阶段，确定适用哪些模式：
| 如果技能... | 模式 | |-----------------|---------| | 封装 CLI 工具 | `{baseDir}/patterns/cli-wrapper.md` | | 封装 Web API | `{baseDir}/patterns/api-wrapper.md` | | 监控并通知 | `{baseDir}/patterns/monitor.md` |
加载所有适用的模式并进行综合。大多数技能结合了多种模式。
**脚本与指令的划分：** 脚本处理确定性机制（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 骨架（frontmatter + 章节） 2. 脚本（如果有） —— 使其工作并测试 3. SKILL.md 正文 —— 完整指令 4. 对照第 1 阶段示例进行测试
如果是提取操作：更新工作区文件，清理旧位置，验证独立运行。
---
## 编写 Frontmatter
Frontmatter 决定了可发现性和门槛。格式遵循 [AgentSkills](https://agentskills.io) 规范并附带 OpenClaw 扩展。
```yaml --- 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":[...]}} --- ```
**关键：** `metadata` 必须是**单行** JSON 对象（解析器限制）。
### 描述 —— 为发现而写
描述决定了技能是否被加载。包括： - **核心能力** —— 它的作用 - **触发关键词** —— 用户会说的术语 - **上下文** —— 适用的情况
测试：智能体会为您的每个第 1 阶段示例短语选择此技能吗？
### Frontmatter 键
| 键 | 用途 | |-----|---------| | `name` | 技能标识符（必需） | | `description` | 发现文本（必需） | | `homepage` | 文档/仓库的 URL | | `user-invocable` | `true`/`false` —— 作为斜杠命令公开（默认：true） | | `disable-model-invocation` | `true`/`false` —— 从模型提示词中排除（默认：false） | | `command-dispatch` | `tool` —— 绕过模型，直接调度到工具 | | `command-tool` | 直接调度的工具名称 | | `command-arg-mode` | `raw` —— 将原始参数转发给工具 |
### Metadata 门槛
OpenClaw 在加载时使用 `metadata.openclaw` 过滤技能：
| 字段 | 效果 | |-------|--------| | `always: true` | 跳过所有门槛，始终加载 | | `emoji` | 在 macOS Skills UI 中显示 | | `os` | 平台过滤器 (`darwin`, `linux`, `win32`) | | `requires.bins` | 所有项必须存在于 PATH 中 | | `requires.anyBins` | 至少一项必须存在 | | `requires.env` | 环境变量必须存在或在配置中 | | `requires.config` | 配置路径必须为真值 | | `primaryEnv` | 映射到 `skills.entries.<name>.apiKey` | | `install` | 自动设置的安装程序规范 |
**沙盒说明：** `requires.bins` 在加载时检查**主机**。如果是沙盒环境，二进制文件也必须存在于容器内。
### Token 预算
每个符合条件的技能会向系统提示词添加约 97 个字符 + 名称 + 描述 + 位置路径。保持描述信息丰富但不要臃肿 —— 每个字符在每一轮都会消耗 token。
### 安装规范
```json "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"} ] ```
## 路径约定
| Token | 含义 | |-------|---------| | `{baseDir}` | 此技能的目录（OpenClaw 在运行时解析） | | `<workspace>/` | 代理的工作区根目录 |
- 对技能内部引用（脚本、状态、模式）使用 `{baseDir}` - 对工作区文件（TOOLS.md, memory/ 等）使用 `<workspace>/` - 切勿硬编码绝对路径 —— 工作区是可移植的 - 对于子代理场景，在任务描述中包含路径上下文（沙盒挂载不同）
## 参考
- 模式文件：`{baseDir}/patterns/`（cli-wrapper, api-wrapper, monitor, composable-examples） - OpenClaw 文档：<https://docs.openclaw.ai/tools/skills> - ClawHub：<https://clawhub.com>