OpenCode Skills 技能系统完全指南：用可复用指令库扩展 AI 编程助手的能力边界

OpenCode Skills 技能系统完全指南：用可复用指令库扩展 AI 编程助手的能力边界

引言

在 AI 编程助手的日常使用中，我们经常会遇到这样的场景：需要让 AI 按照特定的流程执行任务，比如代码审查、发布管理、测试编写等。每次都要在对话中重复描述这些流程，既低效又容易遗漏关键步骤。OpenCode 的 Skills（技能）系统正是为了解决这个问题而设计的——它允许你将可复用的指令集封装为独立的技能模块，让 AI 在需要时按需加载并执行。

本文将全面介绍 OpenCode Skills 系统的设计理念、配置方法、权限管理以及最佳实践，帮助你打造属于自己的技能库。

什么是 Skills？

Skills 是基于 SKILL.md 文件定义的指令集合，存储在项目或全局的特定目录中。与传统的手动指令注入不同，Skills 通过 OpenCode 原生的 skill 工具实现按需加载——AI 助手会检测可用的技能列表，并在需要时加载完整内容。

这意味着你不再需要在每个会话中重复粘贴长篇指令。只需定义一次技能，AI 就能在合适的场景下自动识别并调用。

技能文件结构

每个技能对应一个独立的文件夹，文件夹内必须包含一个 SKILL.md 文件。OpenCode 会按照以下路径顺序搜索技能定义：

项目级配置：

• .opencode/skills/<name>/SKILL.md
• .claude/skills/<name>/SKILL.md
• .agents/skills/<name>/SKILL.md

全局配置：

• ~/.config/opencode/skills/<name>/SKILL.md
• ~/.claude/skills/<name>/SKILL.md
• ~/.agents/skills/<name>/SKILL.md

对于项目级路径，OpenCode 会从当前工作目录向上遍历，直到到达 Git 工作树的根目录，收集沿途发现的所有技能。

编写 SKILL.md 文件

每个 SKILL.md 必须以 YAML 格式的 frontmatter 开头，包含必要的元数据字段：

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---

支持的 frontmatter 字段：

| 字段 | 必填 | 说明 |
|------|------|------|
| name | 是 | 技能名称，1-64 个字符 |
| description | 是 | 技能描述，1-1024 个字符 |
| license | 否 | 许可证信息 |
| compatibility | 否 | 兼容性声明 |
| metadata | 否 | 自定义键值对 |

命名规范

技能名称必须符合以下规则：

• 长度 1-64 个字符
• 仅限小写字母、数字和单连字符 -
• 不能以 - 开头或结尾
• 不能包含连续 --
• 必须与包含 SKILL.md 的目录名一致

正则表达式为：^[a-z0-9]+(-[a-z0-9]+)*$

完整示例

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---
## What I do
- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command

## When to use me
Use this when you are preparing a tagged release.
Ask clarifying questions if the target versioning scheme is unclear.

技能的加载机制

当 AI 助手启动时，OpenCode 会收集所有可用的技能，并将其注入到 skill 工具的描述中。工具描述会列出每个技能的名称和描述：

<available_skills>
  <skill>
    <name>git-release</name>
    <description>Create consistent releases and changelogs</description>
  </skill>
  <skill>
    <name>code-review</name>
    <description>Review pull requests against team coding standards</description>
  </skill>
</available_skills>

AI 助手通过调用 skill 工具并在参数中指定技能名称来加载技能内容：

skill({ name: "git-release" })

加载后，技能中的指令就会成为 AI 当前上下文的一部分，指导其行为。

权限管理

Skills 系统提供了精细的权限控制，可以通过模式匹配来管理哪些技能可以被加载。

全局权限配置

在 opencode.json 中配置默认权限：

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}

权限值说明：

| 权限 | 行为 |
|------|------|
| allow | 技能自动加载，无需确认 |
| deny | 技能对 AI 隐藏，无法访问 |
| ask | 在加载前向用户请求批准 |

逐代理覆盖

不同的 Agent 可以使用不同的技能权限策略。

自定义 Agent（在 agent frontmatter 中）：

---
name: reviewer
permission:
  skill:
    "documents-*": "allow"
---

内置 Agent（在 opencode.json 中）：

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "internal-*": "allow"
        }
      }
    }
  }
}

禁用技能工具

如果某些 Agent 不需要技能功能，可以完全禁用：

自定义 Agent：

---
tools:
  skill: false
---

内置 Agent：

{
  "agent": {
    "plan": {
      "tools": {
        "skill": false
      }
    }
  }
}

实战案例：创建一个代码审查技能

让我们通过一个完整的实战示例来演示如何创建一个实用的 Skills。

1. 创建技能目录

mkdir -p .opencode/skills/code-review

2. 编写 SKILL.md

---
name: code-review
description: Review code changes against team coding standards and best practices
license: MIT
compatibility: opencode
metadata:
  audience: developers
  workflow: github
---
## What I do
- Review pull request diffs for code quality, security, and performance issues
- Check adherence to team coding conventions
- Suggest improvements with concrete code examples
- Verify test coverage for new changes

## Review checklist
1. **Functionality**: Does the code do what it's supposed to?
2. **Security**: Are there any SQL injection, XSS, or other security risks?
3. **Performance**: Are there N+1 queries or unnecessary computations?
4. **Testing**: Are edge cases and error paths covered?
5. **Style**: Does it match the project's existing code style?

## When to use me
Use this skill when reviewing a pull request or when asked to analyze code changes.
Always provide actionable feedback with specific code line references.

3. 配置权限

在 opencode.json 中确保该技能可以被 Plan 模式的 Agent 访问：

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "code-review": "allow"
        }
      }
    }
  }
}

现在，当你在 Plan 模式下请求代码审查时，AI 助手会自动加载 code-review 技能的指令，按照规范化的检查清单进行审查。

最佳实践

1. 描述要具体

description 字段是 AI 判断何时使用技能的唯依据。不要写泛泛的描述，而要具体说明技能的适用场景：

# ❌ 不推荐
description: Code analysis

# ✅ 推荐
description: Analyze PHP code for Laravel best practices and common pitfalls

2. 单一职责原则

每个技能应该只负责一个特定的任务。如果一个技能既做代码审查又做发布管理，建议拆分成两个独立的技能。

3. 使用目录命名传递额外语义

技能名称是 AI 识别的重要标识。使用有意义的命名可以帮 AI 更准确地匹配场景：

• laravel-review - Laravel 项目代码审查
• docker-deploy - Docker 部署流程
• api-test - API 测试生成

4. 注意技能长度

虽然 description 允许最多 1024 个字符，但建议保持简洁。过长的描述反而会增加 AI 解析的负担。详细的指令放在正文中即可。

5. 版本控制

将技能文件纳入 Git 管理，团队成员可以共享和迭代技能库。配合权限系统，不同级别的开发者可以使用不同权限的技能。

6. 全局技能 vs 项目技能

• 项目技能（.opencode/skills/）：适合与特定项目相关的流程，如项目特有的代码规范
• 全局技能（~/.config/opencode/skills/）：适合通用的工作流，如通用的 Git 发布流程

故障排查

如果技能没有在 AI 助手中显示，请按以下步骤排查：

文件名检查：确保文件名为全大写的 SKILL.md，而不是 skill.md 或 SKILL.MD

Frontmatter 验证：确保包含 name 和 description 字段

名称唯一性：确保技能名称在所有路径下都是唯一的

权限检查：被设置为 deny 的技能会对 AI 隐藏

总结

OpenCode Skills 系统是一个强大的可复用指令库机制，它将 AI 编程助手的能力扩展提升到了一个新的层次。通过合理设计技能，你可以：

• 将重复的指令工作自动化
• 确保团队协作规范的一致性
• 按需加载，不浪费上下文空间
• 细粒度控制权限，保障安全性

无论是个人效率提升还是团队标准化落地，Skills 都是一个值得深入掌握的利器。建议从一个小而美的技能开始（比如代码审查或发布管理），在实际使用中不断迭代优化，逐步构建属于你自己的技能生态。