OpenCode Skills 技能系统详解：打造可复用的 AI 编程工作流

OpenCode Skills 技能系统详解：打造可复用的 AI 编程工作流

引言

在使用 OpenCode 这类 AI 编程助手时，我们经常会遇到需要重复描述的场景：比如"帮我发布一篇博客""按公司规范创建 React 组件""生成符合项目风格的单元测试"。每次都要重新描述上下文和规则，不仅低效，还容易出现不一致。OpenCode 的 Skills（技能）系统正是为解决这个问题而生的——它允许你将特定的工作流、知识和指令封装为可复用的"技能包"，按需加载，让 AI 助手在不同任务间快速切换上下文。

本文将深入介绍 Skills 系统的核心概念、文件结构、创建方式以及实战用例，帮助你打造专属的 AI 编程工作流。

什么是 Skill

Skill 本质上是一组预定义的指令和上下文，存储为 Markdown 文件。当你触发某个 Skill 时，OpenCode 会将该文件的内容注入到当前的对话上下文中，让 AI 获得针对特定任务的"专业知识"。

一个 Skill 通常包含以下要素：

• 触发条件（description）：一段描述，告诉 OpenCode 在什么场景下应该加载该 Skill
• 工作指令：详细的步骤说明、注意事项、输出格式要求
• 外部资源引用：脚本、配置文件、模板等辅助资源

你可以在两个位置存放 Skill：

项目级：<项目根目录>/.opencode/skills/<skill-name>/SKILL.md —— 随项目版本控制，团队成员共享

用户级：~/.config/opencode/skills/<skill-name>/SKILL.md —— 个人使用，所有项目通用

Skill 的文件结构

一个完整的 Skill 目录结构如下：

.opencode/skills/
└── blog-publish/
    ├── SKILL.md          # 核心指令文件（必需）
    ├── publish.sh        # 辅助脚本（可选）
    └── template.md       # 模板文件（可选）

其中 SKILL.md 是唯一必需的文件。辅助文件可以通过相对路径引用，OpenCode 会在需要时读取它们。

创建你的第一个 Skill

下面我们通过一个实际例子来创建 Skill。假设我们经常需要通过命令行向某个 API 发送请求并处理响应，每次都描述 curl 命令格式太麻烦，不如封装成 Skill。

1. 创建目录和文件

mkdir -p .opencode/skills/api-debug
touch .opencode/skills/api-debug/SKILL.md

2. 编写 SKILL.md

---
name: api-debug
description: 调试 REST API 接口，发送 HTTP 请求并分析响应
---

## API 调试 Skill

你是一名 API 调试助手，帮助用户快速测试和排查 REST API 接口。

### 工作流程

1. 确认目标 URL 和 HTTP 方法（GET/POST/PUT/DELETE）
2. 确认需要携带的 Headers 和 Body
3. 使用 curl 发送请求，始终添加 `-v` 参数以输出详细信息
4. 分析响应状态码、响应体和耗时
5. 如果出错，给出排查建议

### 注意事项

- 默认使用 JSON 格式的 Content-Type
- 敏感信息（Token、密码）不要输出到终端
- 响应体超过 500 行时仅展示摘要

### 输出格式

以表格形式展示：
| 项目 | 值 |
|------|-----|
| 状态码 | 200 |
| 耗时 | 120ms |
| 响应摘要 | { "status": "ok" } |

3. 触发 Skill

当你的对话内容匹配到 Skill 的 description 时，OpenCode 会自动加载对应 Skill。你也可以在对话中直接指定：

请使用 api-debug skill 帮我调试 https://api.example.com/users

实战案例：博客发布 Skill

来看一个更复杂的真实案例。我维护了一个个人博客，每次发布文章的流程是固定的：检查文章格式 → 调用发布 API → 返回文章链接。这个流程非常适合封装为 Skill。

目录结构

.opencode/skills/blog-publish/
└── SKILL.md

SKILL.md 完整内容

---
name: blog-publish
description: 将文章发布到 www.linweiqin.com 博客
---

你是一个博客发布助手。当用户提及"发布文章""发博客""publish article"时，
自动触发此 Skill。

## 发布流程

### 1. 文章校验
- 确认 Markdown 文件存在且可读
- 验证 frontmatter 中的 title 不为空
- 文章内容不少于 300 字
- 代码块语法正确（三个反引号闭合）

### 2. 发布文章
调用内部发布工具，参数说明：
- title: 文章标题（必填）
- file: Markdown 文件路径（必填，相对于工作目录）
- author: 作者名（默认"叶云梦天"）
- site: 站点 ID（默认 7）

### 3. 返回结果
- 成功：返回文章链接
- 失败：输出错误信息并给出修复建议

### 禁止事项
- 不要修改原文内容
- 不要在没有用户确认的情况下发布
- 发布前必须展示预览

### 示例对话
用户：帮我把 .opencode/auto_article.md 发布到博客
助手：[展示文章预览] 确认发布吗？
用户：确认
助手：[调用发布工具] 发布成功！链接：https://www.linweiqin.com/articles/xxx

实际调用

当用户说"帮我把这篇文章发布到博客"时，OpenCode 自动加载 blog-publish Skill，按照预设流程执行校验、预览、确认、发布四个步骤。整个过程不需要用户重复描述发布规则。

Skill 系统的高级用法

1. 依赖外部工具

Skill 可以通过 bash 工具调用同级目录下的脚本。例如，在 Skill 中引用脚本：

## 执行部署

使用以下命令执行同级目录下的部署脚本：

bash .opencode/skills/deploy/deploy.sh --env production

脚本中可以使用项目级的环境变量和配置文件，无缝集成到现有工作流。

2. 跨项目共享 Skill

将常用的 Skill 放在用户级目录 ~/.config/opencode/skills/，即可在所有项目中复用。适合团队规范、代码风格检查、通用工具等不依赖特定项目的场景。

# 用户级 Skill 结构
~/.config/opencode/skills/
├── git-commit/
│   └── SKILL.md           # 规范化 Git 提交信息
├── code-review/
│   └── SKILL.md           # 代码审查检查清单
└── unit-test/
    └── SKILL.md           # 按项目类型生成测试模板

3. Skill 组合使用

多个 Skill 可以在同一次对话中组合使用。例如，先用 code-review Skill 审查代码，再用 git-commit Skill 生成规范的提交信息。

4. 条件触发 vs 手动触发

Skill 支持两种触发方式：

• 自动触发：当用户输入匹配 description 中的描述时，OpenCode 自动加载
• 手动触发：用户在对话中明确指定 Skill 名称

对于影响范围大、可能误触发的 Skill（如部署、数据库操作），建议仅使用手动触发，避免意外执行。

编写优质 Skill 的最佳实践

1. 描述要精确

description 字段是 OpenCode 判断是否加载 Skill 的唯一依据。一个好的 description 应该：

• 明确任务场景（"创建 React 组件" vs "写前端代码"）
• 包含关键词（中文和英文都可以，与用户的表达习惯一致）
• 避免过于宽泛导致误触发

# 好的 description
description: 创建符合公司规范的 React 函数组件，包含 TypeScript 类型定义和单元测试

# 不好的 description
description: 写代码

2. 指令要具体

给 AI 的指令越具体，输出越可控。善用以下元素：

• 步骤编号：让执行过程有条不紊
• 代码示例：展示期望的输入输出格式
• 边界条件：明确什么能做、什么不能做
• 错误处理：预设常见错误场景的应对策略

3. 保持简洁

Skill 文件不宜过长，控制在 200 行以内。Skill 的目的是提供"上下文"而非"百科全书"。如果某个 Skill 确实需要大量背景知识，考虑将其拆分为多个子 Skill，通过组合使用来完成复杂任务。

4. 版本管理

项目级 Skill 随 Git 仓库一起版本控制。建议在 Skill 文件的 frontmatter 中添加版本号和更新日志：

---
name: component-generator
description: 生成 React 组件
version: 1.2.0
changelog:
  - 1.2.0: 新增 Storybook stories 生成
  - 1.1.0: 支持 TypeScript 严格模式
  - 1.0.0: 初始版本
---

总结

OpenCode 的 Skills 系统是一个强大而灵活的上下文管理工具。它让 AI 编程助手从"通用问答"升级为"场景化专家"，在不同任务之间快速切换角色。通过合理设计 Skill，你可以：

• 提升效率：消除重复的上下文描述
• 保证一致性：团队成员共享同一套工作标准
• 降低门槛：新人可以通过 Skill 快速上手项目规范
• 积累经验：将最佳实践固化为可复用的知识资产

从简单的代码生成模板到复杂的部署流水线，Skills 系统都能胜任。建议从日常工作中最频繁的 2-3 个场景入手，逐步建立自己的 Skill 库。一旦形成体系，你会发现 AI 编程助手变得更加"懂你"。