223 lines
4.5 KiB
Plaintext
223 lines
4.5 KiB
Plaintext
---
|
||
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` 的技能会对代理隐藏
|