opencode-sync
200 lines
5.0 KiB
Markdown
200 lines
5.0 KiB
Markdown
# 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: "..." })` 验证内容能加载。
|