skill-creator

Skill Creator

创建 opencode 技能，以专业知识和工作流扩展 Agent 能力。

技能提供的内容

• 专业工作流 —— 针对特定领域的多步骤流程
• 工具集成 —— 文件格式、API、库的说明
• 领域专业知识 —— 公司专属知识、架构、业务逻辑
• 捆绑资源 —— 可复用脚本、参考资料和素材

技能位置

范围	路径
项目	.opencode/skill/<name>/SKILL.md
全局	~/.config/opencode/skill/<name>/SKILL.md

• 项目技能：团队共享、特定于仓库（例如，our-api-patterns、project-deploy）
• 全局技能：适用于所有项目的个人工具（例如，pdf-editor、commit-helper）

对于项目路径，OpenCode 会从当前工作目录向上遍历至 git 工作树根目录。

技能结构

skill-name/
├── SKILL.md              # Required - frontmatter + instructions
├── scripts/              # Optional - executable code (Python/Bash)
├── references/           # Optional - docs loaded on-demand
└── assets/               # Optional - templates, images, fonts

SKILL.md 格式

---
name: skill-name
description: [Self-contained workflow summary — see guidelines below]
---
# Instructions here (markdown body)

名称：简短的连字符格式标识符。应具有描述性且简洁（最多 64 个字符）。

描述：Agent 在加载前会看到此字段和名称。内容必须完整独立，包含：

• 提供的工作流/能力
• “主动用于以下情境”的触发条件
• 3-5 个具体示例

重要：description 字段是主要触发机制。

技能是标准操作流程/工作流，不是 Agent。不要使用“你是……”或“[角色] 专家”之类的角色描述。

加载前，Agent 在 <available_skills> 中只能看到名称和描述：

<available_skills>
  <skill>
    <name>skill-name</name>
    <description>...</description>
  </skill>
</available_skills>

描述必须完整独立——Agent 不会仅仅为了“了解它的用途”而加载技能。

名称和描述应相辅相成：

• 名称：简短的连字符格式标识符（例如，typescript-advanced）
• 描述：包含能力、触发条件和示例的独立工作流摘要

描述模式（针对 LLM 优化）：

---
name: skill-name
description: |-
  [Action verb/capabilities]. Use for [specific cases]. Use proactively when [contexts].
  
  Examples:
  - user: "query" → action
  - user: "query" → action
---

内容应精炼、便于机器解析且具体。避免使用散文式表达。

**重要：YAML 语法：**带示例的多行描述必须使用字面块标量（|-）。连字符会移除末尾换行符。不要使用包含未加引号冒号或列表的普通 YAML：

# ❌ WRONG - breaks YAML parsing
description: Handle plugins. Examples:
- user: "..." → action

# ✅ CORRECT - use |- for multi-line
description: |-
  Handle plugins.
  
  Examples:
  - user: "..." → action

示例：

---
name: typescript-advanced
description: |-
  Handle TypeScript 5.9 advanced typing, generics, strict configs, type errors, migrations,
  erasable syntax compliance, and test writing. Use proactively for complex generics,
  conditional types, utility types, TS compiler config, or test authoring.
  
  Examples:
  - user: "Create a type-safe event emitter" → implement with generics and mapped types
  - user: "Migrate to strict TypeScript" → add discriminated unions, exhaustive checks
  - user: "Build typed API client from OpenAPI" → generate request/response types with inference
  - user: "Write unit tests" → create strict, typed tests with realistic fixtures
---

要求：

• 以动作动词开头（不要使用“你是”或“[角色] 专家”）
• 列出具体能力（含糊的“帮助处理 X”会被忽略）
• 包含“主动用于以下情境”的触发条件
• 提供 3-5 个具体的 user: "..." → ... 示例
• 多行描述使用 |- 字面块标量（包含列表/冒号的普通 YAML 会导致解析失败）
• 内容精炼且便于 LLM 解析——仅凭描述就必须足以说明加载该技能的必要性

**减少冗余：**不要在 SKILL.md 正文中重复描述内容。

捆绑资源

目录	用途	使用时机
scripts/	可复用的 Python/Bash 代码	反复重写相同代码时
references/	文档、架构、API 规范	Agent 工作时需要相关信息
assets/	模板、图像、字体	输出中使用的文件（不会加载）

不得包含：README.md、CHANGELOG.md、INSTALLATION_GUIDE.md 或其他辅助文档。技能中只包含 Agent 完成工作所需的内容。

核心原则

简洁明了

上下文窗口由多个部分共享。只添加 Agent 尚不了解的信息。

• 审视每个段落：“它值得占用这些 token 吗？”
• 优先使用示例，而非解释
• SKILL.md 应保持在 500 行以内

让自由度与易出错程度相匹配

自由度	格式	适用情形
高	文本说明	存在多种有效方法时
中	伪代码/参数化脚本	存在首选模式时
低	特定脚本	操作易出错或一致性至关重要时

### 渐进式披露

1. 元数据（名称 + 描述）- 始终加载（约 100 个词）

   • description 是主要的发现机制
   • Agent 会看到它，并决定是否加载该技能
   • 如果描述含糊不清，该技能就永远不会被使用

2. SKILL.md 正文 - 在技能触发时加载

   • 核心工作流和详细说明
   • 聚焦于 Agent 完成工作所需的内容

3. 捆绑资源 - 由 Agent 按需加载

   • 将特定变体的详细信息移至 references/

将核心工作流保留在 SKILL.md 中。将特定变体的详细信息移至 references/。

结构示例：

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

Agent 只加载相关的提供方文件。

创建流程

1. 了解 → 收集具体的使用示例
2. 规划 → 找出可复用的脚本／参考资料／资源
3. 初始化 → 手动创建目录和 SKILL.md
4. 编辑 → 编写 SKILL.md 的 frontmatter 和正文，并添加资源
5. 验证 → 确认技能能正确加载和触发
6. 迭代 → 测试、改进、重复

步骤 1：了解

收集技能使用方式的具体示例。询问：

• “这个技能应该做什么？”
• “哪些请求应该触发它？”
• “能给出一些用户查询示例吗？”

只有在使用模式已经明确时才跳过此步骤。

步骤 2：规划

针对每个用例，找出可复用的资源：

如果你发现自己在……	添加到……
重写相同的代码	scripts/
反复查找架构／文档	references/
复制相同的模板	assets/

示例：

• pdf-editor：“旋转这个 PDF” → scripts/rotate_pdf.py
• bigquery：“今天有多少用户？” → references/schema.md
• frontend-builder：“帮我构建一个待办事项应用” → assets/react-template/

步骤 3：初始化

手动创建技能目录和 SKILL.md：

# Global skill (personal tools)
mkdir -p ~/.config/opencode/skill/my-skill

# Project skill (team-specific)
mkdir -p .opencode/skill/my-skill

使用 frontmatter 创建 SKILL.md：

---
name: my-skill
description: |-
  [Workflow/capabilities]. Use for [specific cases]. Use proactively when [contexts].
  
  Examples:
  - user: "query" → action
  - user: "query" → action
---
# [Skill Name]

[Instructions start here]

描述模板示例：

---
name: typescript-advanced
description: |-
  Handle TypeScript 5.9 advanced typing, generics, strict configs, type errors, migrations,
  and test writing. Use proactively for complex generics, conditional types, utility types, TS compiler
config, or test authoring.

Examples:
- user: "Create a type-safe event emitter" → implement with generics and mapped types
- user: "Migrate to strict TypeScript" → add discriminated unions, exhaustive checks
- user: "Build typed API client from OpenAPI" → generate request/response types with inference
- user: "Write unit tests" → create strict, typed tests with realistic fixtures
---

根据需要添加可选目录：

cd my-skill
mkdir scripts references assets  # only create what you'll actually use

步骤 4：编辑

编写指南：

• 必须使用祈使句（“运行脚本”，而不是“你应该运行”）
• 应优先使用项目符号，而非散文
• 应链接到参考资料，以提供详细信息
• 必须在加入所有脚本前进行测试

Frontmatter 要求：

• name：使用小写字母和连字符格式，且必须与目录名称完全一致
• description：至关重要——请遵循上文 中指定的格式。这是 Agent 发现你的技能的方式。

步骤 5：验证

确认技能可被发现：

1. 检查结构：

   • 技能目录中存在 SKILL.md
   • 目录名称与 frontmatter 中的 name: 完全一致
   • YAML frontmatter 有效

2. 测试发现情况：

   • 技能应出现在 Agent 的 <available_skills> 部分
   • 描述应足够具体，能匹配相关查询

3. 验证触发条件：

   • 阅读你的描述——仅凭描述，你是否能判断何时使用此技能？
   • 示例是否覆盖了主要用例？

注意： 技能直接从其目录中使用。无需打包或安装。

步骤 6：迭代

实际使用后：

1. 留意技能未能触发或提供的指导不清晰之处
2. 更新 description，补充缺失的触发场景
3. 在描述或 SKILL.md 正文中添加更多示例
4. 重新验证发现和触发情况

Agent 权限

在 Agent 配置中按 Agent 控制技能访问权限：

{
  "permission": {
    "skill": { "*": "deny", "my-skill": "allow" }
  }
}

可用值："allow"、"deny"、"ask"。使用 "*" 作为通配符默认值。

<question_tool>

批量提问： 对于 2 个或更多相关问题，请使用 question 工具。单个问题 → 使用纯文本。

语法： header 不超过 12 个字符，label 为 1–5 个词，并在默认选项后添加“(Recommended)”。

适用提问的情况：请求含糊不清、适用多种技能模式，或范围不明确。

</question_tool>

<bundled_references>

可用参考资料

此技能包含有关高级模式的参考文档，可按需加载：

参考资料	加载时机
references/output-patterns.md	设计模板输出、提供基于示例的指导
references/workflows.md	设计顺序或条件工作流结构

**用法：**当你需要了解核心工作流之外的详细模式时，请阅读相关参考文件。

</bundled_references>