OpenCode Agent Skills 是放在 SKILL.md 文件中的可复用指令集。AI 在工具列表中看到可用的 skills，需要时按需加载。Skill 按需加载不占用常驻 context。支持项目级（.opencode/skills/）和全局级（~/.config/opencode/skills/）两种位置，同时兼容 Claude Code 的 .claude/skills/ 路径。

OpenCode Agent Skills

Agent Skills 是通过 SKILL.md 文件定义的可复用指令集。AI 可以在工具列表中看到已有的 skills，并在需要时加载其内容。

Skills 是按需加载的——它们不会一直占用 context，只有当 AI 决定使用某个 skill 时才会读取其内容。

---

创建 Skill

每个 skill 对应一个目录，目录内放 SKILL.md 文件（必须全大写）。

目录位置

OpenCode 从以下位置搜索 skills（优先级从低到高）：

范围	路径
全局（OpenCode）	~/.config/opencode/skills/<name>/SKILL.md
全局（Claude Code 兼容）	~/.claude/skills/<name>/SKILL.md
全局（Agent 兼容）	~/.agents/skills/<name>/SKILL.md
项目（OpenCode）	.opencode/skills/<name>/SKILL.md
项目（Claude Code 兼容）	.claude/skills/<name>/SKILL.md
项目（Agent 兼容）	.agents/skills/<name>/SKILL.md

对于项目级路径，OpenCode 从当前目录向上遍历直到 Git 根目录，沿途加载所有匹配的 skills/*/SKILL.md。

---

SKILL.md 格式

每个 SKILL.md 必须包含 YAML frontmatter：

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

## 我做什么

- 从合并的 PR 草拟 release notes
- 建议版本号递增方案
- 提供可直接粘贴的 `gh release create` 命令

## 何时使用我

准备打 tag 发布时使用。版本管理方式不明确时会主动询问。

frontmatter 字段

字段	必填	说明
name	是	skill 名称（必须与目录名一致）
description	是	用途描述（1~1024 字符），AI 据此判断何时使用
license	否	许可证信息
compatibility	否	兼容性声明
metadata	否	自定义键值对

命名规范

name 字段必须满足：

• 1~64 字符
• 全小写字母和数字，用单个连字符分隔
• 不以 - 开头或结尾，不含连续 --
• 与目录名完全一致

有效示例：git-release、code-review、api-docs

---

Skill 的发现机制

OpenCode 将可用 skills 列在 skill 工具的描述中：

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

AI 通过 skill 工具调用加载具体内容：

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

AI 看到 skill 列表后，会在认为合适时自动加载。也可以在 prompt 中直接提到 skill 名称来触发加载。

---

权限配置

用 permission.skill 控制 AI 能访问哪些 skills：

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

权限	行为
allow	立即加载
deny	对 AI 隐藏，拒绝访问
ask	加载前询问用户

---

按 Agent 配置 Skill 权限

自定义 agent（Markdown frontmatter）：

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

内置 agent（opencode.json）：

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

---

完全禁用 Skill 工具

如果某个 agent 不应使用任何 skills：

自定义 agent：

---
tools:
  skill: false
---

内置 agent：

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

禁用后，<available_skills> 部分完全不会出现在工具列表中。

---

排错指南

Skill 不出现在列表中时，按以下顺序检查：

1. SKILL.md 文件名是否全大写
2. frontmatter 是否包含 name 和 description 字段
3. skill 名称是否与目录名完全一致
4. 是否被 deny 权限隐藏
5. 如果有同名 skill（项目级和全局级），确认没有被后者覆盖

---

常见问题

Q: Skill 和 AGENTS.md 的区别是什么？

A: AGENTS.md 始终加载到 context 中，适合放项目约定、常用命令等所有会话都需要的信息。Skills 是按需加载的，适合放只在特定任务中才需要的详细指令（如发布流程、特定组件的写作规范），这样不会让 context 臃肿。

Q: Claude Code 的 .claude/skills/ 目录可以直接用吗？

A: 可以。OpenCode 会自动识别 ~/.claude/skills/ 和项目级的 .claude/skills/ 目录，与 OpenCode 原生的 skills 路径一样处理。

Q: 如何在 prompt 中明确指定使用某个 skill？

A: 直接在消息中提到 skill 名称即可，例如"请用 git-release skill 帮我准备发布"。AI 看到后会调用 skill 工具加载对应内容。