OpenCode Skills 技能系统完全指南：用可复用技能模块提升 AI 编程助手的专业能力

引言

在 AI 编程助手的日常使用中，我们经常遇到这样的场景：每次处理代码审查时都需要重复描述审查规则；每次发版前都要重新说明发布流程；每次写测试时都要重申代码规范。OpenCode 的 Skills（技能）系统正是为解决这类重复性指令问题而设计的——它将特定任务的指令封装为可复用的技能模块，让 AI 编程助手在需要时自动加载。

Skills 是 OpenCode 提供的一种轻量级机制，用于定义可重用的行为模式。你只需编写一个 SKILL.md 文件，放置在特定目录下，OpenCode 就能自动发现并将其注册到 Agent 可用的工具列表中。当任务匹配时，Agent 会自动加载对应的技能，无需你在每次对话中都重复相同的指令。

本文将从概念、创建、配置到最佳实践，全面讲解 OpenCode Skills 系统的使用方法。

什么是 Agent Skills

Skills 本质上是一组结构化的指令说明文件。与 OpenCode 中的其他配置机制相比，Skills 有以下几个关键特点：

  • 可复用：一个技能只需定义一次，即可在整个项目甚至全局范围内使用
  • 按需加载：技能存放在 Agent 可用的 skill 工具中，Agent 会在任务匹配时主动加载
  • 标准化结构：使用 YAML 前置元数据 + Markdown 正文的格式，清晰易读
  • 权限可控：支持细粒度的权限配置，可精确控制哪些 Agent 能使用哪些技能

每个技能以一个包含 SKILL.md 文件的目录表示，目录名就是技能名称。

创建你的第一个技能

目录结构

Skills 可以存放在项目级目录和全局目录中，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 前置元数据和 Markdown 正文。下面是一个完整的示例：

---
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.

前置元数据中只有 name 和 description 是必填字段，其余均为可选。name 必须符合正则 ^[a-z0-9]+(-[a-z0-9]+)*$，长度为 1–64 个字符，且必须与目录名一致。

技能发现与加载

创建完成后，OpenCode 会在启动时自动发现该技能，并将其注册到 Agent 的 skill 工具描述中。Agent 看到的工具列表会包含可用技能的信息：

<available_skills>
  <skill>
    <name>git-release</name>
    <description>Create consistent releases and changelogs</description>
  </skill>
</available_skills>

当 Agent 判断当前任务匹配某个技能时，它会调用 skill({ name: "git-release" }) 来加载完整内容。这个过程是自动的，不需要用户手动干预。

实战：创建代码审查技能

假设你所在团队有统一的代码审查规范，每个 Pull Request 都需要检查特定的项目。我们可以创建一个专用的代码审查技能：

创建目录 .opencode/skills/pr-review/ 并编写 SKILL.md：

---
name: pr-review
description: Review pull requests against project standards
metadata:
  audience: all-developers
  workflow: code-review
---

## Review Checklist
When reviewing a PR, check the following:

### Security
- Are user inputs properly sanitized?
- Are sensitive data (API keys, tokens) handled via environment variables?
- Is authentication enforced on all protected routes?

### Performance
- Are N+1 queries present in database operations?
- Is pagination applied to list endpoints?
- Are large assets optimized or lazy-loaded?

### Code Quality
- Are TypeScript types properly defined (no `any` unless justified)?
- Are functions kept under 50 lines where reasonable?
- Are error messages descriptive and actionable?

### Testing
- Are there unit tests covering the changed logic?
- Do the tests follow the project's testing conventions?
- Are edge cases (empty state, error state, boundary values) covered?

## Output Format
For each issue found, provide:
1. File path and line number
2. Severity (blocker / warning / suggestion)
3. Explanation of the concern
4. Suggested fix (with code snippet when applicable)

这个技能包含了代码审查的完整检查清单，当 Agent 被要求审查 PR 时，它会自动加载这个技能，从而按照团队规范进行审查。

权限管理

Skills 系统提供了灵活的权限配置机制，你可以在 opencode.json 中按模式匹配来控制哪些技能可以被哪些 Agent 加载：

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

权限有三种级别：

| 权限 | 行为 |
|------|------|
| allow | 技能立即可用 |
| deny | 技能对 Agent 不可见，访问被拒绝 |
| ask | 加载前需要用户确认 |

按 Agent 覆盖权限

对于自定义 Agent，你可以在其前置元数据中覆盖权限：

---
name: senior-dev
permission:
  skill:
    "internal-*": "allow"
---

对于内置 Agent（如 plan），在 opencode.json 中配置：

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

禁用技能功能

如果某个 Agent 完全不需要使用技能，可以直接禁用 skill 工具：

---
name: simple-assistant
tools:
  skill: false
---

或者对内置 Agent：

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

技能设计的最佳实践

1. 明确的职责边界

每个技能应该专注于一个特定的任务领域。不要在一个技能中混合代码审查和数据库迁移的规则。职责单一的技能更容易被 Agent 正确识别和加载。

2. 精确的描述信息

description 字段是 Agent 判断是否加载技能的关键依据。描述要具体且有区分度：

# 好的描述
description: Review Go microservice code for correctness, concurrency safety, and stdlib usage patterns

# 不够好的描述
description: Code review

3. 结构化的正文内容

使用标题和列表组织正文，让 Agent 更容易解析和遵循指令。避免长篇大论的段落，使用清晰的分层结构。

4. 利用 metadata 字段

metadata 是字符串-字符串映射表，可以用来附加技能本身的元信息。虽然 Agent 不会直接使用这些数据，但它们有助于组织和管理技能集合：

metadata:
  audience: backend
  team: platform-engineering
  created: "2026-07"
  version: "2.1"

5. 全局技能与项目级技能的平衡

  • 全局技能（~/.config/opencode/skills/）：适合通用性强的技能，如代码规范审查、通用发布流程等
  • 项目级技能（.opencode/skills/）：适合项目特定的规则，如项目特有的架构约束、特殊的数据处理流程等

全局技能会跟随你的所有项目，而项目级技能应该提交到 Git 仓库中，与团队成员共享。

故障排查

如果技能没有出现在 Agent 的可选列表中，按以下顺序排查：

文件名是否正确：必须是全大写的 SKILL.md，注意大小写

前置元数据是否完整：name 和 description 是必填项

名称是否唯一：相同名称的技能在不同位置存在时，只有优先级最高的会被加载

权限是否屏蔽：检查 opencode.json 中的 permission.skill 配置，被设置 deny 的技能对 Agent 不可见

目录名称是否匹配：目录名必须与 name 字段完全一致

总结

OpenCode Skills 系统提供了一种优雅的方式来封装和复用 AI 编程助手的指令。通过将特定任务的指导说明抽象为独立的技能模块，你不再需要在每次对话中重复相同的要求，Agent 会在识别到匹配任务时自动加载对应的技能。

这种设计不仅提高了工作效率，更重要的是让团队的最佳实践可以标准化和共享。无论是代码审查规范、发布流程、测试策略还是架构约束，都能通过 Skills 系统沉淀为团队的共同资产。

结合 OpenCode 的权限系统和 Agent 配置，你可以精细控制每个 Agent 的能力边界，构建一个既灵活又可控的 AI 编程协作环境。

叶云梦天

叶云梦天，专注微信，小程序，服务器管理，数据分析的信息博客