Loading... # OpenClaw 自定义技能创建完整指南 # 一、概述 ## 1. 简介 ### A. 是什么 OpenClaw 是一个可扩展的 AI 助手平台，通过自定义技能（Custom Skills）机制允许用户为特定工作流、数据源和问题领域创建专属自动化工具。每个技能通过自然语言指令（SKILL.md）定义行为，无需编写复杂的代码架构。 ### B. 为什么学 - 打破 AI 助手的局限性，实现真正的个性化自动化 - 通过自然语言而非编程代码来扩展 AI 能力 - 创建持久化、可跨长时间运行的自主代理工作流 - 内置 50 多个技能仅覆盖常见场景，定制技能才能满足独特需求 ### C. 学完能做什么 - 编写符合规范的 SKILL.md 文件 - 配置 metadata.openclaw 元数据块 - 设计并测试自定义技能 - 分享技能给社区并获得反馈 ## 2. 前置知识 ### A. 必备技能 - Markdown 语法基础 - 基本的命令行操作经验 - 对 AI 助手工具调用机制的理解 ### B. 推荐知识 - YAML 配置文件格式 - GitHub API 或其他服务 API 基础 - 自然语言编写技术文档的能力 # 二、核心概念 ## 1. 基本术语 - SKILL.md：技能定义文件，使用自然语言描述技能行为 - metadata.openclaw：YAML 格式的元数据块，配置技能加载和依赖 - 自定义技能：用户为特定需求创建的专属技能 - 捆绑技能：OpenClaw 自带的 50 多个预装技能 ## 2. 工作原理 ```mermaid graph LR A[用户指令] --> B{OpenClaw 引擎} B --> C[检索技能元数据] C --> D{选择技能} D --> E[加载 SKILL.md] E --> F[解析自然语言指令] F --> G[执行工具/API 调用] G --> H[返回结果] ```  OpenClaw 通过读取 SKILL.md 中的自然语言指令来理解技能用途，无需传统的 API 文档或代码架构。AI 会根据描述和示例判断何时调用该技能。 ## 3. 技能生态系统 ```mermaid mindmap root((OpenClaw 技能)) 捆绑技能 邮件 日历 浏览器自动化 智能家居 GitHub 集成 自定义技能 领域专用工具 酒窖管理 PR 审查自动化 深度集成 特定服务集成 团队工作流 自主代理 长时间运行任务 持续监控 ```  # 三、SKILL.md 文件结构 ## 1. 文件组织 每个 OpenClaw 技能驻留在包含一个核心文件的文件夹中：SKILL.md。这个 Markdown 文件通过自然语言指令而非严格的 API 文档来教 AI 代理如何使用你的技能。 文件结构遵循简单模式： - 一级标题：技能名称 - 描述段落：技能功能说明和使用场景 - 使用示例：典型用户命令 - 实现细节：工具、脚本或 API 说明 ## 2. 描述部分编写技巧 描述部分比大多数工程师意识到的更重要。因为 OpenClaw 加载技能元数据来决定提供哪些能力，编写良好的描述决定了你的技能是否被选中处理相关任务。 **编写原则**： - 明确使用场景和触发关键词 - 说明技能解决的具体问题 - 列出适用和不适用的情况 - 提供清晰的输入输出示例 示例描述： ```markdown # 酒窖管理技能 这个技能帮助葡萄酒收藏家管理库存。可以添加新酒、查询库存、获取饮用建议和食物搭配。当用户提到葡萄酒、库存、酒窖或相关术语时触发。 适用场景：添加新酒到库存、查询特定年份或产区的酒、获取基于现有库存的饮用建议。 ``` ## 3. 实现细节说明 实现细节部分描述技能实际调用的工具、脚本或 API。OpenClaw 的灵活性在于你可以用自然语言描述行为、边缘情况和偏好。 关键内容包括： - 调用的命令行工具 - API 端点和参数 - 数据处理逻辑 - 错误处理策略 # 四、metadata.openclaw 元数据块 ## 1. 基本结构 除了自然语言指令，SKILL.md 还支持结构化的元数据块，用于配置 OpenClaw 如何加载和管理技能。这个 YAML frontmatter 出现在文件顶部，控制几个关键行为。 ```yaml --- metadata.openclaw: emoji: "🍷" requires: bins: ["sqlite3", "curl"] env: ["WINE_CELLAR_API_KEY"] config: ["cellar_path"] install: | pip install wine-python-lib mkdir -p ~/.wine-cellar --- ``` ## 2. 字段说明 ### A. emoji 字段 设置技能激活时显示的图标，为用户提供关于代理正在使用哪个功能的视觉反馈。虽然是小细节，但有助于用户理解复杂自动化期间发生的情况。 ### B. requires 部分 指定技能所需的依赖： - bins：必须在系统上存在的命令行工具数组 - env：技能期望的环境变量数组 - config：用户必须提供的配置键数组 ### C. install 字段 包含 OpenClaw 在技能设置期间运行的 shell 命令。这处理下载依赖、配置工具或执行技能所需的任何首次运行初始化。 ## 3. 依赖管理 这些元数据字段使技能能够在不同环境中可靠地工作。当你与社区分享技能时，其他人可以安装它，确切知道它需要什么依赖和配置。 ```mermaid graph TD A[安装技能] --> B{检查 metadata} B --> C[检查 bins] B --> D[检查 env] B --> E[检查 config] C --> F{工具存在?} D --> G{变量设置?} E --> H{配置提供?} F -->|否| I[安装提示] G -->|否| J[变量提示] H -->|否| K[配置提示] F -->|是| L[继续] G -->|是| L H -->|是| L L --> M[执行 install 脚本] M --> N[技能就绪] ```  # 五、构建决策：自定义 vs 使用现有技能 ## 1. 决策框架 ```mermaid graph TD A[需要自动化任务] --> B{现有技能覆盖?} B -->|是| C[使用现有技能] B -->|否| D{任务类型?} D -->|领域专用| E[构建自定义技能] D -->|深度集成| F[构建自定义技能] D -->|可组合| G[组合现有技能] C --> H[验证解决方案] E --> I[设计 SKILL.md] F --> I G --> H I --> J[实现并测试] J --> H ```  ## 2. 构建自定义技能的时机 ### A. 领域专用工具或服务 当工作流涉及捆绑技能未覆盖的领域专用工具或服务时。酒窖示例完美地说明了这一点。没有通用技能理解葡萄酒库存管理及其特定字段：年份、产区、品尝笔记和饮用窗口。 ### B. 需要专门化行为 PR 审查自动化可能使用 GitHub 技能进行基本操作，但自定义技能可以强制执行团队特定的审查清单、评论格式标准和合并策略。 ### C. 集成深度很重要 捆绑技能提供广泛兼容性，但不能为每个用例优化。如果需要与特定服务深度集成，自定义技能给你对集成工作方式的精确控制。 ## 3. 复用现有技能的时机 避免在捆绑技能可以组合解决问题时构建。OpenClaw 擅长在单个工作流中组合多个技能。在构建之前，测试现有技能链接在一起是否能完成目标。 这种方法需要较少的维护，并从捆绑技能的上游改进中受益。 # 六、社区示例学习 ## 1. 酒窖管理技能 展示有效的状态处理： - 本地存储库存数据 - 与外部服务同步 - 在添加和查询中保持一致格式 - 指示 AI 确认添加、验证葡萄酒数据 - 使用用户现有酒窖内容建议食物搭配 ## 2. PR 审查技能 展示类似生产 AI 代理系统的工具集成模式： - 连接到 GitHub API - 解析差异输出 - 应用审查标准 - 根据团队标准格式化反馈 - API 调用失败时的回退行为 - 复杂审查的清晰升级路径 ## 3. 边缘处理原则 这些社区示例展示了一个关键经验：优秀的技能优雅地处理边缘情况。它们预判可能出错的地方，并为 AI 处理这些情况提供清晰指导。 ```mermaid graph TD A[技能执行] --> B{正常流程} B -->|是| C[执行主要逻辑] B -->|否| D{异常类型} D -->|API 失败| E[回退行为] D -->|数据缺失| F[请求用户输入] D -->|权限不足| G[升级路径] E --> H[记录并继续] F --> H G --> H C --> I[返回结果] H --> I ```  # 七、测试与分享 ## 1. 测试流程 在公开分享技能之前，彻底测试可以防止尴尬的失败，并确保其他人实际使用你的作品。 ### A. 隔离测试 用各种应该触发技能的提示在隔离中测试技能。验证 AI 正确识别何时使用你的技能与其他可用选项。 ### B. 依赖测试 如果可能，在干净系统上测试依赖安装。requires 元数据只有在准确捕获所有依赖时才有帮助。缺少必需的二进制文件或环境变量会给用户带来令人沮丧的设置失败。 ### C. 安全考虑 当技能执行潜在破坏性操作时，考虑治理 AI 自动化的安全原则。 ## 2. 文档要求 清晰地记录配置。无法弄清楚如何配置技能的用户将放弃它，无论底层功能多么有用。 ## 3. 社区分享 遵循社区指南增加你的技能到达需要它的用户的机会。分享时包括： - 完整的 SKILL.md 文件 - 依赖和配置说明 - 使用示例 - 已知限制 # 八、自定义技能的真正力量 ## 1. 平台思维转变 我看到使用 OpenClaw 成功的工程师有一个共同特质：他们将助手不是视为固定产品，而是构建确切需要东西的平台。他们自动化的每个独特工作流都复合了他们的生产力优势。 这种心态转变比任何特定技术能力都重要。当你遇到没有现有工具处理良好的重复任务时，问题不是是否自动化它，而是如何将自动化表达为技能。 ## 2. 持久化与自主性 自定义技能还启用跨越扩展时间框架的自主代理工作流。因为 OpenClaw 维持持久内存并连续运行，设计良好的技能可以监控条件、采取行动并在几天或几周内报告结果。这种持久性使得基于会话的工具不可能的自动化模式成为可能。 ```mermaid sequenceDiagram participant U as 用户 participant S as 自定义技能 participant O as OpenClaw 引擎 U->>S: 定义监控任务 S->>O: 注册持久化工作流 Note over S,O: 持续运行（天/周） O->>S: 检测触发条件 S->>S: 执行自动化逻辑 S->>U: 报告结果 S->>O: 继续监控 ```  ## 3. 迭代开发过程 入门门槛随着生态系统成熟而持续下降。更好的文档、更多的社区示例和改进的工具使技能创建对非 AI 专家的工程师也可以访问。你不需要深厚的机器学习知识来构建有用的技能。 你需要的是对工作流的清晰思考和在自然语言指令中表达工作流的能力。 建议的开发路径： 1. 从一个解决你每天面临的真正问题的小自动化开始 2. 构建技能，彻底测试它，并使用一周 3. 使用自己的自定义技能的经验揭示了你在设计阶段从未预料到的改进 4. 基于实际使用迭代，然后考虑与社区分享 # 九、最佳实践总结 ## 1. SKILL.md 编写 - 使用清晰的自然语言描述 - 提供具体的使用示例 - 明确触发关键词和场景 - 详细说明边缘情况处理 ## 2. 元数据配置 - 准确声明所有依赖 - 提供清晰的配置说明 - 编写可靠的安装脚本 - 选择有意义的 emoji 图标 ## 3. 测试与分享 - 在隔离中彻底测试 - 验证依赖安装 - 考虑安全影响 - 提供完整文档 *** ## 参考资料 1. [OpenClaw Custom Skill Creation - Step by Step](https://zenvanriel.nl/ai-engineer-blog/openclaw-custom-skill-creation-guide/) 2. [OpenClaw GitHub Repository](https://github.com/openclaw/openclaw) 3. [Model Context Protocol Documentation](https://modelcontextprotocol.io) 最后修改：2026 年 02 月 12 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏