skill-creator

技能创建器

此技能提供创建高效技能的指导。 示例中使用的 Unix shell 命令的 Windows PowerShell 等效命令见 references/windows.md。

关于技能

技能是模块化、独立的程序包，可通过提供专业知识、工作流和工具来扩展 OpenHands 的能力。可以将它们视为特定领域或任务的“入门指南”——它们能将 OpenHands 从通用 Agent 转变为具备流程知识的专业 Agent，而这些知识并非任何模型都能完全掌握。

技能提供什么

1. 专业工作流 - 特定领域的多步骤流程
2. 工具集成 - 使用特定文件格式或 API 的说明
3. 领域专业知识 - 公司特定的知识、架构和业务逻辑
4. 随附资源 - 用于复杂且重复性任务的脚本、参考资料和资源

技能的组成

每项技能都包含一个必需的 SKILL.md 文件，以及可选的随附资源：

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md（必需）

元数据质量： YAML frontmatter 中的 name 和 description 决定 OpenHands 何时使用该技能。请具体说明技能的作用及使用时机。请使用第三人称（例如，“应在……时使用此技能”，而不是“在……时使用此技能”）。

斜杠命令与关键词触发器： SKILL.md frontmatter 支持可选的 triggers: 字段，用于基于关键词激活（例如，triggers: [docker, container]）。对于斜杠命令（例如，/codereview、/init），优先在插件的 commands/ 目录中创建 commands/command-name.md 文件，而不是在 SKILL.md 中使用斜杠触发器。为向后兼容，斜杠触发器仍可使用，但已弃用，建议改用 commands/ 方案。详情请参阅 插件指南。

随附资源（可选）

脚本（scripts/）

用于需要确定性可靠性或经常重复编写的任务的可执行代码（Python/Bash 等）。

• 适用情况：需要反复重写相同代码，或需要确定性可靠性时
• 示例：用于 PDF 旋转任务的 scripts/rotate_pdf.py
• 优点：节省令牌、结果确定，可在不加载到上下文中的情况下执行
• 注意：OpenHands 仍可能需要读取脚本，以进行修补或针对特定环境调整
• Python 依赖项：安装所有 Python 依赖项时，请使用 uv，而不是 pip 或 pip3。uv 跨平台、速度更快，并能避免不同环境中 pip/pip3 命名不一致的问题。示例：uv venv .venv --quiet && uv pip install --quiet <package>

参考资料（references/）

根据需要加载到上下文中，为 OpenHands 的流程和思考提供参考的文档与资料。

• 适用情况：OpenHands 工作时需要参考的文档
• 示例：财务架构用的 references/finance.md、公司 NDA 模板用的 references/mnda.md、公司政策用的 references/policies.md、API 规范用的 references/api_docs.md
• 使用场景：数据库架构、API 文档、领域知识、公司政策、详细的工作流指南
• 优点：保持 SKILL.md 精简，仅在 OpenHands 判断有需要时加载
• 最佳实践：如果文件较大（>10k 字），请在 SKILL.md 中加入 grep 搜索模式
• 避免重复：信息应存放在 SKILL.md 或 references 文件中，而不是两者都有。除非内容确实是技能的核心，否则详细信息优先放在 references 文件中；这样既能保持 SKILL.md 精简，也便于查找信息，同时避免占用过多上下文窗口。SKILL.md 中仅保留必要的操作说明和工作流指导；将详细参考资料、架构和示例移至 references 文件。

资源（assets/）

不打算加载到上下文中，而是供 OpenHands 在生成的输出中使用的文件。

• 何时包含：当技能需要在最终输出中使用文件时
• 示例：用于品牌素材的 assets/logo.png、PowerPoint 模板 assets/slides.pptx、HTML/React 样板 assets/frontend-template/、用于排版的 assets/font.ttf
• 使用场景：模板、图像、图标、样板代码、字体、会被复制或修改的示例文档
• 优点：将输出资源与文档分开，让 OpenHands 无需将文件加载到上下文中即可使用

渐进式披露设计原则

技能采用三级加载系统来高效管理上下文：

1. 元数据（名称 + 描述） - 始终位于上下文中（约 100 个词）
2. SKILL.md 正文 - 技能触发时加载（少于 5k 个词）
3. 捆绑资源 - OpenHands 按需加载（无限*）

*之所以称为无限，是因为可以执行脚本，而无需将其读入上下文窗口。

技能创建流程

创建技能时，请按顺序遵循“技能创建流程”，仅在有明确理由认为某些步骤不适用时才跳过。

步骤 1：通过具体示例了解技能

仅当技能的使用模式已经十分明确时，才跳过此步骤。即使是在处理现有技能时，此步骤仍然很有价值。

要创建有效的技能，请清楚了解该技能的具体使用方式。这种了解可以来自用户直接提供的示例，也可以来自经过用户反馈验证的生成示例。

例如，构建图像编辑器技能时，相关问题包括：

• “图像编辑器技能应支持哪些功能？编辑、旋转，还有其他功能吗？”
• “能否举一些这个技能的使用示例？”
• “我能想到用户可能会提出诸如‘去掉这张图片中的红眼’或‘旋转这张图片’之类的请求。你还能想到其他使用方式吗？”
• “用户说什么内容时应该触发这个技能？”

为避免让用户应接不暇，请勿在一条消息中提出太多问题。先问最重要的问题，再根据需要追问，以提高效果。

当明确了解该技能应支持哪些功能后，结束此步骤。

步骤 2：规划可复用的技能内容

要将具体示例转化为有效的技能，请逐一分析每个示例：

1. 思考如何从头开始完成该示例
2. 找出在反复执行这些工作流时，有哪些脚本、参考资料和素材会有帮助

示例：构建 pdf-editor 技能以处理“帮我旋转这个 PDF”之类的请求时，分析表明：

1. 每次旋转 PDF 都需要重新编写相同的代码
2. 将 scripts/rotate_pdf.py 脚本存放在技能中会很有帮助

示例：设计 frontend-webapp-builder 技能以处理“帮我构建一个待办事项应用”或“帮我构建一个用于追踪步数的仪表板”之类的请求时，分析表明：

1. 每次编写前端 Web 应用都需要相同的 HTML/React 样板
2. 将包含样板 HTML/React 项目文件的 assets/hello-world/ 模板存放在技能中会很有帮助

示例：构建 big-query 技能以处理“今天有多少用户登录了？”之类的请求时，分析表明：

1. 每次查询 BigQuery 都需要重新查找表架构及其关联关系
2. 将说明表架构的 references/schema.md 文件存放在技能中会很有帮助

要确定技能的内容，请分析每个具体示例，并列出需要包含的可复用资源：脚本、参考资料和素材。

步骤 3：创建技能结构

创建技能目录结构：

mkdir -p skill-name/{references,scripts,assets}
touch skill-name/SKILL.md

或者，使用 init_skill.py 脚本生成模板：

scripts/init_skill.py <skill-name> --path <output-directory>

该脚本会创建一个技能目录，其中包含 SKILL.md 模板和示例资源目录。

步骤 4：编辑技能

编辑（新创建或现有的）技能时，请记住，该技能是为另一个 OpenHands 实例使用而创建的。重点加入对 OpenHands 有益且不显而易见的信息。考虑哪些流程知识、特定领域的细节或可复用资源可以帮助另一个 OpenHands 实例更有效地执行这些任务。

从可复用的技能内容着手

开始实现时，先处理上文确定的可复用资源：scripts/、references/ 和 assets/ 文件。请注意，此步骤可能需要用户提供输入。例如，实现 brand-guidelines 技能时，用户可能需要提供品牌资源或模板，以存放在 assets/ 中；也可能需要提供文档，以存放在 references/ 中。

此外，删除技能不需要的示例文件和目录。只创建实际需要的目录（references/、scripts/、assets/）。

更新 SKILL.md

写作风格： 整个技能都使用祈使式或不定式形式（以动词开头的指令），而不是第二人称。使用客观、指导性的语言（例如，“若要完成 X，请执行 Y”，而不是“你应该执行 X”或“如果你需要执行 X”）。这样可以使内容对 AI 而言保持一致、清晰。

描述（Frontmatter）： 使用第三人称格式，并包含具体的触发短语：

---
name: skill-name
description: This skill should be used when the user asks to "specific phrase 1", "specific phrase 2", "specific phrase 3". Include exact phrases users would say that should trigger this skill. Be concrete and specific.
---

良好的描述示例：

description: This skill should be used when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use", "implement prompt-based hooks", or mentions hook events (PreToolUse, PostToolUse, Stop).

不好的描述示例：

description: Use this skill when working with hooks.  # Wrong person, vague
description: Load when user needs hook help.  # Not third person
description: Provides hook guidance.  # No trigger phrases

要完成 SKILL.md 正文，请回答以下问题：

1. 该技能的目的是什么？用几句话说明。
2. 应在何时使用该技能？（在 frontmatter 描述中加入具体触发条件）
3. 实际使用时，OpenHands 应如何使用该技能？请引用上文开发的所有可复用技能内容，让 OpenHands 知道如何使用它们。

保持 SKILL.md 精简： 正文目标为 1,500–2,000 个单词。将详细内容移至 references/：

• 详细模式 → references/patterns.md
• 高级技巧 → references/advanced.md
• 迁移指南 → references/migration.md
• API 参考 → references/api-reference.md

在 SKILL.md 中引用资源：

## Additional Resources

### Reference Files

For detailed patterns and techniques, consult:
- **`references/patterns.md`** - Common patterns
- **`references/advanced.md`** - Advanced use cases

### Example Files

Working examples in `examples/`:
- **`example-script.sh`** - Working example

步骤 5：验证和测试

1. 检查结构：技能目录中包含 SKILL.md
2. 验证 SKILL.md：包含带有 name 和 description 的 frontmatter
3. 检查触发短语：描述中包含具体的用户查询
4. 检查写作风格：正文使用祈使式或不定式形式，而不是第二人称
5. 测试渐进式披露：SKILL.md 保持精简（约 1,500–2,000 个单词），详细内容放在 references/ 中
6. 检查引用：所有引用的文件均存在
7. 验证脚本：脚本具有可执行权限且运行正常

使用验证脚本检查基本要求：

scripts/quick_validate.py <path/to/skill-folder>

步骤 6：迭代

测试技能后，用户可能会要求改进。通常，这种情况会在使用技能后立即发生，此时对技能表现的印象还很鲜明。

迭代工作流：

1. 在实际任务中使用技能
2. 留意遇到的困难或效率低下之处
3. 确定应如何更新 SKILL.md 或随附资源
4. 实施更改并再次测试

常见改进：

• 在描述中强化触发短语
• 将 SKILL.md 中较长的章节移至 references/
• 添加缺少的示例或脚本
• 澄清含糊的指令
• 增加边缘情况处理

渐进式披露实践

SKILL.md 中应包含的内容

包含（技能触发时始终加载）：

• 核心概念和概述
• 必要的流程和工作流
• 快速参考表
• 指向 references/examples/scripts 的链接
• 最常见的用例

控制在 3,000 个单词以内，理想情况下为 1,500–2,000 个单词

references/ 中应包含的内容

移至 references/（按需加载）：

• 详细模式和高级技巧
• 完整的 API 文档
• 迁移指南
• 边缘情况和故障排查
• 丰富的示例和操作指南

每个参考文件可以很大（2,000-5,000+ 个词）

scripts/ 中应包含的内容

实用脚本：

• 验证工具
• 测试辅助工具
• 解析工具
• 自动化脚本

应当可执行且附有文档

写作风格要求

使用祈使式/不定式

使用动词开头的指令，而不是第二人称：

正确（祈使式）：

To create a hook, define the event type.
Configure the MCP server with authentication.
Validate settings before use.

错误（第二人称）：

You should create a hook by defining the event type.
You need to configure the MCP server.
You must validate settings before use.

描述中使用第三人称

frontmatter 描述必须使用第三人称：

正确：

description: This skill should be used when the user asks to "create X", "configure Y"...

错误：

description: Use this skill when you want to create X...
description: Load this skill when user asks...

使用客观、指导性的语言

重点说明要做什么，而不是谁来做：

正确：

Parse the frontmatter using sed.
Extract fields with grep.
Validate values before use.

错误：

You can parse the frontmatter...
OpenHands should extract fields...
The user might validate values...

验证清单

定稿前，请检查以下内容：

结构：

• SKILL.md 文件存在，且包含有效的 YAML frontmatter
• Frontmatter 包含 name 和 description 字段
• Markdown 正文内容完整且充实
• 引用的文件确实存在

描述质量：

• 使用第三人称（“应在……时使用此技能”）
• 包含用户可能会说的具体触发短语
• 列出具体场景（“创建 X”“配置 Y”）
• 不含含糊或笼统的表述

内容质量：

• SKILL.md 正文使用祈使式/不定式
• 正文重点明确、简洁（理想长度为 1,500-2,000 个词，最多不超过 5,000 个词）
• 详细内容已移至 references/
• 示例完整且可运行
• 脚本可执行且附有文档

渐进式披露：

• 核心概念位于 SKILL.md 中
• 详细文档位于 references/ 中
• 实用工具位于 scripts/ 中
• SKILL.md 引用了这些资源

测试：

• 技能会在预期的用户查询下触发
• 内容有助于完成预期任务
• 各文件之间没有重复信息
• 参考资料会在需要时加载

应避免的常见错误

错误 1：触发描述过于笼统

❌ 错误：

description: Provides guidance for working with hooks.

错误原因： 表述笼统，没有具体触发短语，也未使用第三人称

✅ 正确：

description: This skill should be used when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use", or mentions hook events. Provides comprehensive hooks API guidance.

正确原因： 使用第三人称，包含具体短语和场景

错误 2：SKILL.md 内容过多

❌ 错误：

skill-name/
└── SKILL.md  (8,000 words - everything in one file)

错误原因： 技能加载时会占用过多上下文，详细内容也会始终加载

✅ 正确：

skill-name/
├── SKILL.md  (1,800 words - core essentials)
└── references/
    ├── patterns.md (2,500 words)
    └── advanced.md (3,700 words)

正确原因： 采用渐进式披露，仅在需要时加载详细内容

错误 3：使用第二人称写作

❌ 错误：

You should start by reading the configuration file.
You need to validate the input.
You can use the grep tool to search.

错误原因： 使用第二人称，而非祈使式

✅ 正确：

Start by reading the configuration file.
Validate the input before processing.
Use the grep tool to search for patterns.

正确原因： 使用祈使式，指令直接明确

错误 4：缺少资源引用

❌ 错误：

# SKILL.md

[Core content]

[No mention of references/ or examples/]

错误原因： OpenHands 不知道参考资料的存在

✅ 正确：

# SKILL.md

[Core content]

## Additional Resources

### Reference Files
- **`references/patterns.md`** - Detailed patterns
- **`references/advanced.md`** - Advanced techniques

### Scripts
- **`scripts/validate.sh`** - Validation utility

正确原因： OpenHands 知道在哪里查找更多信息

快速参考

最简技能

skill-name/
└── SKILL.md

适用于：简单知识，无需复杂资源

标准技能（推荐）

skill-name/
├── SKILL.md
├── references/
│   └── detailed-guide.md
└── scripts/
    └── helper.py

适用于：大多数包含详细文档的技能

完整技能

skill-name/
├── SKILL.md
├── references/
│   ├── patterns.md
│   └── advanced.md
├── scripts/
│   └── validate.sh
└── assets/
    └── template.txt

适用于：包含验证工具的复杂领域

最佳实践摘要

✅ 应该：

• 在描述中使用第三人称（“应在……时使用此技能”）
• 包含具体的触发短语（“创建 X”“配置 Y”）
• 保持 SKILL.md 简洁（1,500–2,000 字）
• 使用渐进式披露（将详细内容移至 references/）
• 使用祈使式或不定式形式撰写
• 清晰地引用支持文件
• 提供可运行的示例
• 为常见操作创建实用脚本
• 在脚本中使用 uv 安装 Python 依赖（uv venv .venv --quiet && uv pip install --quiet <pkg>）

❌ 不应该：

• 在任何地方使用第二人称
• 使用含糊的触发条件
• 将所有内容都放入 SKILL.md（超过 3,000 字且没有 references/）
• 使用第二人称撰写（“你应该……”）
• 留下未引用的资源
• 包含无法运行或不完整的示例
• 跳过验证
• 直接使用 pip 或 pip3——uv 是跨平台标准

其他资源

参考文件

有关详细模式和技巧，请参阅：

• references/workflows.md - 顺序工作流和条件逻辑模式
• references/output-patterns.md - 特定输出格式的模板和示例模式

实施工作流

创建技能的步骤：

1. 了解用例：确定技能使用的具体示例
2. 规划资源：确定所需的脚本、参考文件和资源文件
3. 创建结构：mkdir -p skill-name/{references,scripts,assets}
4. 编写 SKILL.md：
   • 使用第三人称描述和触发短语编写 Frontmatter
   • 使用祈使式撰写精简正文（1,500–2,000 字）
   • 引用支持文件
5. 添加资源：按需创建 references/、scripts/ 和 assets/
6. 验证：检查描述、写作风格和组织结构
7. 测试：确认技能会在预期触发条件下加载
8. 迭代：根据使用情况改进

重点关注清晰有力的触发描述、渐进式披露和祈使式写作风格，从而打造有效的技能，使其在需要时加载并提供有针对性的指导。