opencode/packages/web/src/content/docs/zh-cn/skills.mdx

---
title: "代理技能"
description: "通过 SKILL.md 定义可复用的行为"
---

代理技能让 OpenCode 能够从你的仓库或主目录中发现可复用的指令。
技能通过原生的 `skill` 工具按需加载——代理可以查看可用技能，并在需要时加载完整内容。

---

## 放置文件

为每个技能名称创建一个文件夹，并在其中放入 `SKILL.md`。
OpenCode 会搜索以下位置：

- 项目配置：`.opencode/skills/<name>/SKILL.md`
- 全局配置：`~/.config/opencode/skills/<name>/SKILL.md`
- 项目 Claude 兼容：`.claude/skills/<name>/SKILL.md`
- 全局 Claude 兼容：`~/.claude/skills/<name>/SKILL.md`
- 项目代理兼容：`.agents/skills/<name>/SKILL.md`
- 全局代理兼容：`~/.agents/skills/<name>/SKILL.md`

---

## 了解发现机制

对于项目本地路径，OpenCode 会从当前工作目录向上遍历，直到到达 git 工作树根目录。
在此过程中，它会加载 `.opencode/` 中所有匹配的 `skills/*/SKILL.md`，以及匹配的 `.claude/skills/*/SKILL.md` 或 `.agents/skills/*/SKILL.md`。

全局定义也会从 `~/.config/opencode/skills/*/SKILL.md`、`~/.claude/skills/*/SKILL.md` 和 `~/.agents/skills/*/SKILL.md` 中加载。

---

## 编写 frontmatter

每个 `SKILL.md` 必须以 YAML frontmatter 开头。
仅识别以下字段：

- `name`（必填）
- `description`（必填）
- `license`（可选）
- `compatibility`（可选）
- `metadata`（可选，字符串到字符串的映射）

未知的 frontmatter 字段会被忽略。

---

## 验证名称

`name` 必须满足：

- 长度为 1–64 个字符
- 仅包含小写字母和数字，可用单个连字符分隔
- 不以 `-` 开头或结尾
- 不包含连续的 `--`
- 与包含 `SKILL.md` 的目录名称一致

等效的正则表达式：

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

---

## 遵循长度规则

`description` 必须为 1-1024 个字符。
请保持描述足够具体，以便代理能够正确选择。

---

## 使用示例

创建 `.opencode/skills/git-release/SKILL.md`，内容如下：

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

---

## 识别工具描述

OpenCode 会在 `skill` 工具描述中列出可用技能。
每个条目包含技能名称和描述：

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

代理通过调用工具来加载技能：

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

---

## 配置权限

在 `opencode.json` 中使用基于模式的权限来控制代理可以访问哪些技能：

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

| 权限    | 行为                     |
| ------- | ------------------------ |
| `allow` | 技能立即加载             |
| `deny`  | 对代理隐藏技能，拒绝访问 |
| `ask`   | 加载前提示用户确认       |

模式支持通配符：`internal-*` 可匹配 `internal-docs`、`internal-tools` 等。

---

## 按代理覆盖权限

为特定代理授予与全局默认值不同的权限。

**自定义代理**（在代理 frontmatter 中）：

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

**内置代理**（在 `opencode.json` 中）：

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

---

## 禁用技能工具

为不需要使用技能的代理完全禁用技能功能：

**自定义代理**：

```yaml
---
tools:
  skill: false
---
```

**内置代理**：

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

禁用后，`<available_skills>` 部分将被完全省略。

---

## 排查加载问题

如果某个技能没有显示：

1. 确认 `SKILL.md` 文件名全部为大写字母
2. 检查 frontmatter 是否包含 `name` 和 `description`
3. 确保技能名称在所有位置中唯一
4. 检查权限设置——设为 `deny` 的技能会对代理隐藏