# 02 — Skills (代理技能)

> 源: <https://opencode.ai/docs/zh-cn/skills/>
> 适用: 创建/修改 `SKILL.md` (`.opencode/skill/<name>/SKILL.md`)

## 放置文件 (发现路径)

OpenCode 递归扫描以下位置找 `**/SKILL.md`:

| 范围 | 路径 |
|---|---|
| 项目 opencode | `.opencode/skills/<name>/SKILL.md` |
| 全局 opencode | `~/.config/opencode/skills/<name>/SKILL.md` |
| 项目 Claude 兼容 | `.claude/skills/<name>/SKILL.md` |
| 全局 Claude 兼容 | `~/.claude/skills/<name>/SKILL.md` |
| 项目 agents 兼容 | `.agents/skills/<name>/SKILL.md` |
| 全局 agents 兼容 | `~/.agents/skills/<name>/SKILL.md` |

> 项目本地路径: opencode 从当前工作目录**向上**遍历到 git worktree 根,沿途全加载。

> 本仓库主要用 `.opencode/skill/` (opencode 风格),同时保留 `.qwen/skills/` / `.agents/skills/` (历史) — 三者并存不冲突。

## Frontmatter 字段

**只识别**以下字段,其它一律忽略:

| 字段 | 必填 | 说明 |
|---|---|---|
| `name` | ✅ | 1-64 字符,正则 `^[a-z0-9]+(-[a-z0-9]+)*$`,**必须与目录名一致** |
| `description` | ✅ | 1-1024 字符,**决定何时被加载** |
| `license` | ❌ | 字符串 |
| `compatibility` | ❌ | 字符串 |
| `metadata` | ❌ | string→string 映射 |

> 缺 `description` → **静默过滤掉**,不会报错也不会出现在 `<available_skills>`。

## Name 验证规则 (硬)

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

- 1-64 字符
- 仅小写字母和数字,单个连字符分隔
- 不以 `-` 开头或结尾
- 不含连续 `--`
- **与目录名一致**

## Description 写法 (触发匹配关键)

- 第三人称 "Use when..." / "Use ONLY when..."
- **前置** 关键词/文件名 (用户原话里常出现的字)
- 1-1024 字符,具体到能区分相邻话题
- "Use ONLY when..." 收窄误触

**正面**:

```yaml
description: Configures opencode itself (agents/skills/MCP/custom tools/permissions). Use ONLY when user creates/modifies opencode.json, agent files, SKILL.md, MCP server config, .opencode/tools/, or tool permission policies.
```

**反面** (太泛):

```yaml
description: Helps with development
```

## 工具描述 (模型看到什么)

`<available_skills>` 列出每个 skill 的 `name` + `description`:

```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` | 加载前弹确认 |

**按代理覆盖**:

```yaml
# 自定义代理 frontmatter
---
permission:
  skill:
    "documents-*": allow
---
```

```json
// 内置代理 opencode.json
{
  "agent": {
    "plan": {
      "permission": { "skill": { "internal-*": "allow" } }
    }
  }
}
```

**禁用 skill 工具** (代理完全用不了):

```yaml
# 自定义代理
---
tools:
  skill: false
---
```

```json
// 内置代理
{ "agent": { "plan": { "tools": { "skill": false } } } }
```

## 排查加载问题 (按顺序)

1. 文件名**全大写** `SKILL.md` (不是 `skill.md` / `SKILL.MD`)
2. frontmatter 含 `name` + `description`
3. `name` 在**所有路径里唯一** (项目 + 全局)
4. 权限: 被 `deny` 会静默消失
5. 退出并重启 opencode (配置不热重载)

## 文件组织 (大内容用子文件)

> 本 skill 的约定: 主 SKILL.md 保持导航/速查,详细文档放 `references/`/`scripts/`/`templates/`。

```
.opencode/skill/
└── my-skill/
    ├── SKILL.md              # 必填, 主体 (导航+摘要)
    ├── references/           # 可选, 详细文档
    │   ├── 01-xxx.md
    │   └── 02-xxx.md
    ├── scripts/              # 可选, 工具脚本
    └── templates/            # 可选, 模板
```

> 加载方式: 主 SKILL.md 里用一句话导航,如"详细见 `references/01-xxx.md`",模型用 `read` 工具按需取。

## 官方示例 (照搬)

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

## 验证清单 (改完跑一遍)

1. `name` 与目录名一致,通过正则。
2. `description` 1-1024 字符,前置关键词。
3. 文件名 `SKILL.md` 全大写。
4. 退出重启 opencode。
5. 主代理在 UI 输入与 description 相关的请求,看 `<available_skills>` 是否列出。
6. 主代理调 `skill({ name: "..." })` 验证内容能加载。