使用 Agent Skills

Agent Skill 是一份可以被 OpenCode 按需加载的操作说明。它平时只暴露名称和描述，Agent 认为需要时，才通过原生 skill 工具加载完整 SKILL.md。

先给结论：Skill 是流程包，不是大号规则文件

不要把 Skill 当成另一个 AGENTS.md。两者职责不同：

Skill 最适合承载发布流程、PR 审查流程、文档生成流程、迁移检查清单、排障 SOP 这类可复用任务。临时要求不要做成 Skill，否则库会越来越臃肿。

Skill 是怎么被发现和加载的

OpenCode 会先发现可用 Skill，把名称和描述放进 skill 工具说明里。Agent 先看摘要，判断需要时再加载完整内容。

flowchart LR
  Start[当前工作目录] --> Walk[向上查找到 git worktree]
  Walk --> Project[项目级 skills]
  Home[用户主目录] --> Global[全局 skills]
  Project --> List[可用技能列表<br/>name + description]
  Global --> List
  List --> Decide{Agent 判断是否需要}
  Decide -->|需要| Load[调用 skill 工具加载 SKILL.md]
  Decide -->|不需要| Skip[不占用上下文]

这个机制的关键是：description 写得越具体，Agent 越容易在正确时间加载它。

放在哪里

为每个 Skill 创建一个文件夹，并在里面放 SKILL.md。OpenCode 会搜索这些位置：

选择顺序很简单：

1. 只服务当前仓库，放项目目录。
2. 多个仓库都要用，放全局目录。
3. 已经有 Claude Code Skill 库，优先复用兼容入口，不要复制一份大型目录。

SKILL.md frontmatter 怎么写

每个 SKILL.md 必须以 YAML frontmatter 开头。官方识别这些字段：

未知字段会被忽略，不要把关键约束写在 OpenCode 不识别的 frontmatter 字段里。

名称和描述怎么判断

name 要满足：

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

等效规则可以记成：

^[a-z0-9]+(-[a-z0-9]+)*$

description 长度为 1-1024 个字符。它不是广告语，而是给 Agent 的触发条件。不要写 help with git，要写清楚“什么时候用、产出什么、有哪些边界”。

一个可用的最小 Skill

文件：.opencode/skills/release-check/SKILL.md

---
name: release-check
description: Use when preparing a release; checks diff, changelog, tests, version bump, and publish command
license: MIT
compatibility: opencode
metadata:
  workflow: github-release
---

## When to use

Use this when preparing a tagged release or release candidate.

## Steps

1. Read the current diff and changelog.
2. Confirm tests and version bump.
3. Draft release notes.
4. Produce a publish command for human review.

## Boundaries

Do not publish automatically.
Do not include secrets or private customer names.

这个 Skill 的重点不是写得长，而是触发条件、步骤和边界都清楚。

权限如何控制

在 opencode.json 里可以用模式控制 Agent 能访问哪些 Skill：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "skill": {
      "*": "ask",
      "release-check": "allow",
      "internal-*": "deny"
    }
  }
}

模式支持通配符。比如 internal-* 可以覆盖 internal-docs、internal-tools 等内部技能。

按 Agent 覆盖权限

你也可以让不同 Agent 使用不同 Skill 权限。比如审查 Agent 可以使用 documents-*，但普通聊天 Agent 看不到内部发布 Skill。

自定义 Agent frontmatter 示例：

---
permission:
  skill:
    "documents-*": "allow"
    "internal-*": "ask"
---

内置 Agent 可以在 opencode.json 里覆盖：

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

什么时候禁用 Skill 工具

有些 Agent 不应该加载 Skill：

• 只做规划、不执行流程的 Agent。
• 不应该接触内部资料的 Agent。
• 临时测试 Agent，避免误加载团队 Skill。

可以直接关闭 skill 工具。关闭后，可用技能列表会完全省略。

---
tools:
  skill: false
---

排查加载问题

如果某个 Skill 没显示，按这个顺序查：

1. 文件名是否是全大写 SKILL.md。
2. frontmatter 是否包含 name 和 description。
3. name 是否和目录名完全一致。
4. 当前启动目录是否位于目标 git 工作树内。
5. 不同位置是否有同名 Skill 冲突。
6. 权限是否被设为 deny。

新手常见坑

• 描述太泛，Agent 不知道什么时候加载。
• Skill 太大，把整个团队手册塞进一个文件。
• 目录名和 name 不一致。
• 项目专用 Skill 放到全局，导致其他仓库误触发。
• 把真实密钥、账号、客户资料写进 Skill。
• 只会用一次的 prompt 也做成 Skill。

接下来去哪

官方资料

• OpenCode Agent Skills
• OpenCode configuration