从需求到落地：手把手教你编写第一个OpenClaw自定义技能

一、技能包开发基础

1.1 技能包的核心组成

一个完整的技能包由以下部分组成：

my-skill/ ├── skill.yaml # 元数据定义（必需） ├── prompt.md # 核心提示词（必需） ├── examples/ # 使用示例（推荐） │ ├── basic.md │ └── advanced.md ├── tools/ # 自定义工具（可选） │ └── helper.ts ├── templates/ # 模板文件（可选） │ └── output.md └── README.md # 文档（推荐）

1.2 skill.yaml 结构详解

这是技能包的"身份证"，定义了所有关键信息：

# skill.yaml - 技能包配置文件# 基本信息name:my-custom-skillversion:1.0.0description:一个自定义技能包示例author:Your Namelicense:MIT# 触发配置trigger:# 命令触发command:my-skill# 关键词触发（可选）keywords:-自定义-custom# 兼容性compatibility:openclaw:">=1.0.0"models:-claude-sonnet-4-6-claude-opus-4-6-gpt-4-qwen-max# 依赖（可选）dependencies:skills:-code-review@^1.0.0tools:-Read-Edit-Bash# 配置选项（可选）config:schema:type:objectproperties:strictMode:type:booleandefault:falsedescription:是否启用严格模式outputFormat:type:stringenum:[markdown,json,html]default:markdown

1.3 prompt.md 核心提示词

这是技能包的"灵魂"，定义了AI的行为：

# prompt.md - 核心提示词模板 你是一个专业的{{domain}}专家助手。你的职责是帮助用户完成与{{domain}}相关的任务。 ## 角色定义 你具备以下能力： 1. 深入理解{{domain}}的核心概念和最佳实践 2. 能够分析、设计、实现相关方案 3. 提供专业、准确、可操作的建议 ## 工作流程 当用户请求帮助时，按照以下步骤执行： 1. **需求理解** - 分析用户的真实需求 - 识别关键约束条件 - 确认任务范围 2. **方案设计** - 提出解决方案 - 说明设计思路 - 列出优缺点 3. **实现执行** - 按步骤实施 - 生成代码或文档 - 验证结果 4. **结果交付** - 总结完成的工作 - 说明后续建议 - 提供使用指南 ## 输出规范 - 使用清晰的标题层级 - 代码块标注语言类型 - 重要内容使用加粗 - 列表使用一致的格式 ## 注意事项 - 始终考虑边界情况 - 关注安全性问题 - 遵循行业最佳实践 - 保持代码可维护性

二、实战：创建代码注释生成技能

让我们创建一个实用的技能包：自动为代码生成专业注释。

2.1 创建项目结构

# 创建技能包目录mkdir-pcomment-generatorcdcomment-generator# 创建基本文件touchskill.yaml prompt.md README.mdmkdir-pexamples templates

2.2 编写 skill.yaml

name:comment-generatorversion:1.0.0description:自动为代码生成专业的注释文档author:Developerlicense:MITtrigger:command:gen-commentskeywords:-注释-文档-commentcompatibility:openclaw:">=1.0.0"models:-claude-sonnet-4-6-gpt-4-qwen-max-deepseek-coderdependencies:tools:-Read-Editconfig:schema:type:objectproperties:style:type:stringenum:[jsdoc,tspoint,python,go]default:jsdocdescription:注释风格language:type:stringdefault:zh-CNdescription:注释语言includeExamples:type:booleandefault:truedescription:是否包含使用示例

2.3 编写 prompt.md

# 代码注释生成器 你是一位专业的代码文档工程师，擅长为各种编程语言的代码编写清晰、专业的注释文档。 ## 你的任务 分析用户提供的代码，为其生成完整的注释文档，包括： - 文件级注释（文件用途、作者、版本等） - 函数/方法注释（功能描述、参数、返回值、示例） - 类/接口注释（职责、属性、方法概览） - 复杂逻辑的行内注释 ## 注释风格 根据配置的注释风格生成对应格式： ### JSDoc风格（JavaScript/TypeScript） ```javascript /** * 格式化日期字符串 * @param {Date} date - 要格式化的日期对象 * @param {string} format - 格式模板，默认 'YYYY-MM-DD' * @returns {string} 格式化后的日期字符串 * @example * formatDate(new Date(), 'YYYY/MM/DD'); // '2024/01/15' */ function formatDate(date, format = 'YYYY-MM-DD') { // 实现... }

TSDoc风格（TypeScript）

/** * 用户服务类 * * 负责处理用户相关的业务逻辑，包括注册、登录、信息更新等操作。 * * @remarks * 该类依赖 {@link Database} 进行数据持久化， * 使用前需确保数据库连接已初始化。 * * @example * ```typescript * const userService = new UserService(db); * const user = await userService.findById('123'); * ``` */exportclassUserService{// ...}

Python风格

defcalculate_total(items:list[dict])->float:"""计算订单总金额。 Args: items: 订单项列表，每个项包含 price 和 quantity 字段。 Returns: float: 订单总金额。 Raises: ValueError: 当 items 为空或包含无效数据时。 Example: >>> items = [{'price': 10, 'quantity': 2}] >>> calculate_total(items) 20.0 """# 实现...

Go风格

// Package user provides user management functionality.//// This package implements user CRUD operations, authentication,// and profile management for the application.packageuser// UserService handles user-related operations.//// It provides methods for creating, updating, and querying users.// All methods are safe for concurrent use.typeUserServicestruct{db*sql.DB}// FindByID retrieves a user by their unique identifier.//// Returns ErrNotFound if no user exists with the given ID.func(s*UserService)FindByID(idstring)(*User,error){// 实现...}

注释原则

1. 简洁明了：用最少的文字说明功能
2. 准确完整：描述必须与代码行为一致
3. 提供示例：复杂函数提供使用示例
4. 说明边界：说明异常情况和边界条件
5. 避免冗余：不要注释显而易见的内容

工作流程

1. 读取用户指定的代码文件
2. 分析代码结构和逻辑
3. 识别需要注释的元素（函数、类、复杂逻辑）
4. 按照指定风格生成注释
5. 使用Edit工具将注释插入代码
6. 展示修改后的代码并解释添加的注释

输出格式

完成后，输出以下内容：

✅ 注释生成完成 📊 统计： - 文件数：X - 函数注释：X 条 - 类注释：X 条 - 行内注释：X 条 📝 修改的文件： - path/to/file1.ts - path/to/file2.ts 💡 建议： - [可选的改进建议]

### 2.4 创建示例文件 ```markdown <!-- examples/basic.md --> # 基本使用示例 ## 输入

/openclaw> /gen-comments src/utils/format.ts

## 输出

正在分析 src/utils/format.ts…

✅ 注释生成完成

📊 统计：

• 文件数：1
• 函数注释：3 条
• 类注释：0 条
• 行内注释：2 条

📝 添加的注释：

1. formatDate 函数
   /**

   • 格式化日期为指定格式
   • @param date - 日期对象或日期字符串
   • @param format - 格式模板，支持 YYYY、MM、DD、HH、mm、ss
   • @returns 格式化后的日期字符串
     */

2. formatCurrency 函数
   /**

   • 格式化金额，添加货币符号和千分位
   • @param amount - 金额数值
   • @param currency - 货币符号，默认 ‘¥’
   • @returns 格式化后的金额字符串
     */

3. formatPhone 函数
   /**

   • 格式化电话号码为 xxx-xxxx-xxxx 格式
   • @param phone - 原始电话号码字符串
   • @returns 格式化后的电话号码
     */

<!-- examples/advanced.md --> # 高级使用示例 ## 批量处理

/openclaw> /gen-comments src/ --style jsdoc --language zh-CN

扫描 src 目录…
找到 15 个代码文件

处理进度：
[████████████████████] 100% (15/15)

✅ 批量注释生成完成

📊 汇总统计：

• 文件数：15
• 函数注释：47 条
• 类注释：8 条
• 接口注释：12 条
• 行内注释：23 条

📁 每个文件的详情：
├── src/api/user.ts: 5 函数, 1 类
├── src/utils/format.ts: 3 函数
├── src/components/Button.tsx: 2 函数, 1 接口
└── …

## 配置选项 ```bash # 指定注释风格 /openclaw> /gen-comments src/ --style python # 指定注释语言 /openclaw> /gen-comments src/ --language en-US # 不包含示例 /openclaw> /gen-comments src/ --no-examples

### 2.5 创建 README.md ```markdown # Comment Generator Skill 自动为代码生成专业的注释文档。 ## 功能特点 - 🚀 支持多种编程语言 - 📝 多种注释风格可选（JSDoc、TSDoc、Python、Go） - 🌍 支持中英文注释 - 📚 自动生成使用示例 - 🔍 智能识别需要注释的代码元素 ## 安装 ```bash openclaw skills install comment-generator

使用方法

基本用法

# 为单个文件生成注释openclaw>/gen-comments path/to/file.ts# 为整个目录生成注释openclaw>/gen-comments src/

配置选项

示例

# Python风格注释openclaw>/gen-comments src/--stylepython# 英文注释openclaw>/gen-comments src/--languageen-US

注释风格对比

JSDoc

适合JavaScript项目，广泛应用于npm生态。

TSDoc

适合TypeScript项目，支持类型链接和更丰富的格式。

Python

适合Python项目，符合PEP 257规范。

Go

适合Go项目，符合Go官方代码规范。

最佳实践

1. 在代码编写完成后立即生成注释
2. 生成后人工检查注释的准确性
3. 对于复杂业务逻辑，补充更多说明
4. 定期更新过时的注释

版本历史

• 1.0.0: 初始版本

## 三、高级特性 ### 3.1 添加自定义工具 如果需要更复杂的逻辑，可以添加自定义工具： ```typescript // tools/analyzer.ts interface CodeElement { type: 'function' | 'class' | 'interface' | 'variable'; name: string; line: number; params?: string[]; returnType?: string; complexity: number; } /** * 分析代码结构 */ export async function analyzeCode(filePath: string): Promise<CodeElement[]> { // 实现代码分析逻辑 // 可以使用AST解析器等工具 return []; } /** * 计算代码复杂度 */ export function calculateComplexity(code: string): number { // 实现复杂度计算 return 0; } // 导出工具定义 export default { name: 'code-analyzer', description: '分析代码结构，识别需要注释的元素', parameters: { type: 'object', properties: { filePath: { type: 'string', description: '要分析的文件路径' } }, required: ['filePath'] }, execute: analyzeCode };

在 skill.yaml 中声明工具：

dependencies:tools:-Read-Edit-code-analyzer# 自定义工具

3.2 使用模板引擎

创建输出模板：

<!-- templates/report.md --> # 代码注释报告 生成时间：{{timestamp}} 文件范围：{{scope}} ## 统计信息 | 指标 | 数量 | |------|------| | 处理文件数 | {{stats.files}} | | 函数注释 | {{stats.functions}} | | 类注释 | {{stats.classes}} | | 行内注释 | {{stats.inline}} | ## 详细变更 {{#each files}} ### {{this.path}} {{#each this.comments}} - **{{this.target}}** (行 {{this.line}}) - 类型：{{this.type}} - 内容：{{this.preview}} {{/each}} {{/each}} ## 建议 {{#each suggestions}} - {{this}} {{/each}}

3.3 添加钩子

在特定事件时自动触发：

# skill.yamlhooks:post-file-save:condition:extensions:[.ts,.tsx,.js,.jsx]action:check-commentsprompt:|检查刚保存的文件是否有足够的注释， 如果缺少关键注释，提醒用户。

四、测试与发布

4.1 本地测试

# 链接到本地OpenClawopenclaw skillslink./comment-generator# 测试技能openclaw>/gen-comments test-file.ts# 验证技能包openclaw skills validate ./comment-generator

4.2 发布到社区

# 发布到官方仓库openclaw skills publish ./comment-generator# 或推送到GitHubgitinitgitadd.gitcommit-m"Initial commit"gitremoteaddorigin https://github.com/username/openclaw-skill-comment-generator.gitgitpush-uorigin main

五、最佳实践总结

5.1 提示词编写技巧

1. 角色明确：清晰定义AI的角色和专业领域
2. 流程结构化：将复杂任务拆分为有序步骤
3. 示例丰富：提供多样化的使用示例
4. 约束清晰：说明边界条件和限制
5. 输出规范：定义清晰的输出格式

5.2 技能包设计原则

1. 单一职责：一个技能包专注一个领域
2. 配置灵活：支持用户自定义配置
3. 文档完善：提供详细的使用说明
4. 版本管理：遵循语义化版本规范
5. 向后兼容：升级时考虑兼容性

六、总结

本文通过创建一个代码注释生成技能包，完整展示了：

• 技能包结构：skill.yaml、prompt.md、examples等核心文件
• 配置详解：触发器、依赖、配置选项的定义
• 提示词编写：角色定义、工作流程、输出规范
• 高级特性：自定义工具、模板引擎、钩子
• 测试发布：本地测试、验证、发布流程

掌握技能包开发，你就可以让OpenClaw真正成为你的专属助手。在下一篇文章中，我们将深入OpenClaw的底层机制，理解Agent的决策与工具调用流程。