skill-creator

技能创建器

此技能提供创建高效技能的指导。

关于技能

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

技能提供的内容

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

核心原则

简洁至关重要

上下文窗口是一种公共资源。技能与 OpenCode 所需的其他内容共用上下文窗口，包括系统提示词、对话历史、其他技能的元数据以及用户的实际请求。

默认假设：OpenCode 已经非常智能。 只添加 OpenCode 尚不具备的上下文。审视每条信息：“OpenCode 真的需要这段解释吗？”以及“这段内容值得占用相应的 Token 吗？”

优先使用简洁的示例，而不是冗长的解释。

设置合适的自由度

根据任务的脆弱性和可变性调整具体程度：

高自由度（基于文本的说明）：适用于存在多种有效方法、决策取决于上下文或需要依靠启发式方法的情况。

中等自由度（带参数的伪代码或脚本）：适用于存在首选模式、允许一定变化或配置会影响行为的情况。

低自由度（特定脚本、少量参数）：适用于操作脆弱且容易出错、一致性至关重要或必须遵循特定顺序的情况。

可以把 OpenCode 想象成探索一条路径：狭窄且两侧是悬崖的桥需要明确的护栏（低自由度），而开阔的场地则允许选择多条路线（高自由度）。

技能的组成

每项技能都包含一个必需的 SKILL.md 文件和可选的捆绑资源：

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   ├── description: (required)
│   │   └── compatibility: (optional, rarely needed)
│   └── 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（必需）

每个 SKILL.md 包含：

• Frontmatter（YAML）：包含必需的 name 和 description 字段，以及可选的 license、metadata 和 compatibility 等字段。OpenCode 只会读取 name 和 description 来判断何时触发技能，因此应清楚、全面地说明技能的用途及其适用时机。compatibility 字段用于注明环境要求（目标产品、系统软件包等），但大多数技能不需要此字段。
• 正文（Markdown）：使用技能的说明和指导。只有在技能触发后（如果触发的话）才会加载。

捆绑资源（可选）

脚本（scripts/）

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

• 适用情况：需要反复重写同一段代码，或需要确定性可靠性时
• 示例：用于 PDF 旋转任务的 scripts/rotate_pdf.py
• 优点：节省 Token、结果确定，可在不加载到上下文中的情况下执行
• 注意：OpenCode 仍可能需要读取脚本，以便进行修补或针对特定环境进行调整

参考资料（references/）

文档和参考材料，可按需加载到上下文中，为 OpenCode 的流程和思考提供参考。

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

资源文件（assets/）

这些文件不会加载到上下文中，而是供 OpenCode 在生成输出时使用。

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

技能中不应包含的内容

技能只应包含直接支持其功能的必要文件。不要创建多余的文档或辅助文件，包括：

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md
• 等等。

技能只应包含 AI Agent 完成当前任务所需的信息。不要包含有关创建过程的辅助背景信息、设置和测试流程、面向用户的文档等。创建额外的文档文件只会增加杂乱和困惑。

渐进式披露设计原则

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

1. 元数据（名称 + 描述） - 始终位于上下文中（约 100 个单词）
2. SKILL.md 正文 - 技能触发时加载（<5k 个单词）
3. 捆绑资源 - OpenCode 按需使用（不受限制，因为无需读入上下文窗口即可执行脚本）

渐进式披露模式

SKILL.md 正文应只包含必要内容，并控制在 500 行以内，以尽量减少上下文膨胀。接近此限制时，将内容拆分到单独的文件中。将内容拆分到其他文件时，务必在 SKILL.md 中引用这些文件，并清楚说明何时应阅读它们，确保技能的读者知道这些文件的存在及其用途。

核心原则： 当技能支持多种变体、框架或选项时，只在 SKILL.md 中保留核心工作流和选择指南。将特定变体的详细信息（模式、示例、配置）移至单独的参考文件。

模式 1：高级指南与参考文件

# PDF Processing

## Quick start

Extract text with pdfplumber:
[code example]

## Advanced features

- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

OpenCode 仅会在需要时加载 FORMS.md、REFERENCE.md 或 EXAMPLES.md。

模式 2：按领域组织

对于涉及多个领域的技能，按领域组织内容，避免加载无关上下文：

bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    ├── product.md (API usage, features)
    └── marketing.md (campaigns, attribution)

当用户询问销售指标时，OpenCode 只会读取 sales.md。

同样，对于支持多个框架或变体的技能，也应按变体组织：

cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
    ├── aws.md (AWS deployment patterns)
    ├── gcp.md (GCP deployment patterns)
    └── azure.md (Azure deployment patterns)

当用户选择 AWS 时，OpenCode 只会读取 aws.md。

模式 3：条件式详细信息

展示基础内容，并链接到高级内容：

# DOCX Processing

## Creating documents

Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents

For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

只有当用户需要这些功能时，OpenCode 才会读取 REDLINING.md 或 OOXML.md。

重要指南：

• 避免深层嵌套引用——引用文件与 SKILL.md 的层级应保持为一层。所有引用文件都应由 SKILL.md 直接链接。
• 为较长的参考文件设置结构——对于超过 100 行的文件，应在开头添加目录，以便 OpenCode 在预览时查看完整内容范围。

示例：将较长的技能拆分为参考文件

当技能超过 500 行时，将详细内容拆分到单独的参考文件中：

csharp-coding-standards/
├── SKILL.md (273 lines - overview and principles)
└── reference/
    ├── language-patterns.md (457 lines - detailed language examples)
    ├── performance-patterns.md (261 lines - Span<T>, Memory<T>, async patterns)
    ├── api-design.md (180 lines - API design principles and best practices)
    ├── error-handling.md (114 lines - Result type patterns)
    └── anti-patterns.md (284 lines - anti-patterns and reflection warnings)

在 SKILL.md 中引用这些文件：

## Language Patterns

For detailed examples of records, value objects, pattern matching, and nullable reference types, see [reference/language-patterns.md](reference/language-patterns.md).

## Performance Patterns

For Span<T>, Memory<T>, and async/await best practices, see [reference/performance-patterns.md](reference/performance-patterns.md).

## API Design

For comprehensive API design guidelines, see [reference/api-design.md](reference/api-design.md).

## Error Handling

For Result type patterns and railway-oriented programming, see [reference/error-handling.md](reference/error-handling.md).

## Anti-Patterns

For patterns to avoid and reflection warnings, see [reference/anti-patterns.md](reference/anti-patterns.md).

技能创建流程

创建技能包括以下步骤：

1. 通过具体示例了解技能
2. 规划可复用的技能内容（脚本、参考资料、资源）
3. 初始化技能（运行 init_skill.py）
4. 编辑技能（实现资源并编写 SKILL.md）
5. 打包技能（运行 package_skill.py）
6. 根据实际使用情况迭代

请按顺序执行这些步骤；只有在有明确理由说明某步骤不适用时，才跳过该步骤。

步骤 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 步：初始化技能

现在可以正式创建技能了。

仅当要开发的技能已存在，且需要进行迭代或打包时，才跳过此步骤。这种情况下，请继续下一步。

从头创建新技能时，务必运行 init_skill.py 脚本。该脚本可便捷地生成新的技能模板目录，并自动包含技能所需的一切，使技能创建过程更加高效、可靠。

用法：

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

该脚本会：

• 在指定路径创建技能目录
• 生成带有正确 frontmatter 和 TODO 占位内容的 SKILL.md 模板
• 创建示例资源目录：scripts/、references/ 和 assets/
• 在每个目录中添加可自定义或删除的示例文件

初始化后，可根据需要自定义或删除生成的 SKILL.md 和示例文件。

第 4 步：编辑技能

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

学习经过验证的设计模式

根据技能的需求，参考以下实用指南：

• 多步骤流程：参阅 references/workflows.md，了解顺序工作流和条件逻辑
• 特定输出格式或质量标准：参阅 references/output-patterns.md，了解模板和示例模式

这些文件包含技能设计的成熟最佳实践。

从可复用的技能内容入手

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

添加的脚本必须通过实际运行进行测试，以确保没有错误，且输出符合预期。如果有许多相似脚本，只需测试具有代表性的样本，确保对它们都能正常运行有足够信心，同时兼顾完成所需的时间。

删除技能不需要的示例文件和目录。初始化脚本会在 scripts/、references/ 和 assets/ 中创建示例文件以演示结构，但大多数技能并不需要这些文件。

更新 SKILL.md

写作指南： 始终使用祈使句或不定式形式。

Frontmatter

使用 name 和 description 编写 YAML frontmatter：

• name：技能名称
• description：这是技能的主要触发机制，可帮助 OpenCode 理解何时使用该技能。
  • 同时说明技能的功能，以及适用的具体触发条件或情境。
  • 将所有“何时使用”的信息都写在这里，而不是正文中。正文仅在触发后加载，因此在正文中添加“何时使用此技能”章节对 OpenCode 没有帮助。
  • docx 技能的描述示例：“全面的文档创建、编辑和分析，支持修订跟踪、批注、格式保留和文本提取。当 OpenCode 需要处理专业文档（.docx 文件）时使用，适用于：(1) 创建新文档；(2) 修改或编辑内容；(3) 处理修订跟踪；(4) 添加批注；或其他文档任务。”

不要在 YAML frontmatter 中包含任何其他字段。

正确的 frontmatter 示例：

---
name: csharp-coding-standards
description: Write modern, high-performance C# code using records, pattern matching, value objects, async/await, Span<T>/Memory<T>, and best-practice API design patterns. Use when writing new C# code or refactoring existing code, designing public APIs for libraries or services, optimizing performance-critical code paths, or building async/await-heavy applications.
---

不应包含的字段：

• invocable——无效字段
• version——无效字段
• tags——无效字段
• last-updated——无效字段
• color——无效字段
• model——无效字段

编写优质描述：

描述是技能的主要触发机制。应：

1. 说明技能的功能——明确指出领域或技术
2. 包含触发短语——添加“使用场景：”，后接应触发此技能的具体情境
3. 内容全面——提供足够的细节，让 OpenCode 知道何时应选择此技能，而不是其他技能
4. 少于 200 个字符——保持简洁，以优化大模型上下文窗口的使用

优质描述示例：

# Good: Clear purpose + trigger phrases
description: Configure Akka.NET with .NET Aspire for local development and production deployments. Use when setting up Akka.NET with Aspire orchestration, configuring Akka.Cluster, integrating Akka.Persistence with SQL Server, or deploying to Kubernetes.

# Good: Technology focus + specific triggers
description: IHttpClientFactory patterns with Polly for retries, circuit breakers, timeouts, and resilient HTTP communication. Use when configuring resilient HTTP clients in ASP.NET Core, implementing retry policies with Polly, or setting up circuit breakers for external service calls.

# Good: Domain expertise + when to use
description: Entity Framework Core best practices including NoTracking by default, query splitting for navigation collections, migration management, dedicated migration services, and common pitfalls to avoid. Use when setting up EF Core in a new project, optimizing query performance, managing database migrations, or debugging change tracking issues.

正文

编写使用技能及其捆绑资源的说明。

步骤 5：打包技能

技能开发完成后，必须将其打包为可分发的 .skill 文件，与用户共享。打包过程会先自动验证技能，确保其满足所有要求：

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

可选的输出目录指定方式：

scripts/package_skill.py <path/to/skill-folder> ./dist

打包脚本将：

1. 验证技能，自动检查：

   • YAML frontmatter 格式和必填字段
   • 技能命名规范和目录结构
   • 描述的完整性和质量
   • 文件组织和资源引用

2. 如果验证通过，则打包技能，创建一个以技能命名的 .skill 文件（例如，my-skill.skill），其中包含所有文件，并保留适合分发的目录结构。.skill 文件是扩展名为 .skill 的 zip 文件。

如果验证失败，脚本会报告错误并退出，不会创建软件包。修复所有验证错误后，再次运行打包命令。

第 6 步：迭代

测试技能后，用户可能会提出改进建议。这通常发生在使用技能后不久，此时他们对技能的表现还有清晰的印象。

迭代工作流：

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