mirror of
https://github.com/anomalyco/opencode.git
synced 2026-04-30 13:39:52 +00:00
222 lines
4.4 KiB
Text
222 lines
4.4 KiB
Text
---
|
||
title: 《代理技巧》
|
||
description: “通過 SKILL.md 定義定義可重用行為”
|
||
---
|
||
|
||
代理技能讓 opencode 從您的存儲庫或主目錄中發現可重用的指令。
|
||
技能通過本機 `skill` 工具按需加載 - 代理可以查看可用技能並可以在需要時加載完整內容。
|
||
|
||
---
|
||
|
||
## 放置文件
|
||
|
||
每個技能名稱創建一個文件夾，並在其中放入`SKILL.md`。
|
||
opencode 搜索這些位置：
|
||
|
||
- 項目配置：`.opencode/skills/<name>/SKILL.md`
|
||
- 全局配置：`~/.config/opencode/skills/<name>/SKILL.md`
|
||
- 克勞德項目兼容：`.claude/skills/<name>/SKILL.md`
|
||
- 全球克勞德兼容：`~/.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` 加載。
|
||
|
||
---
|
||
|
||
## 寫前言
|
||
|
||
每個`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` 等。
|
||
|
||
---
|
||
|
||
## 覆蓋每個代理
|
||
|
||
為特定代理授予與全局默認權限不同的權限。
|
||
|
||
**對於自定義代理**（在代理前言中）：
|
||
|
||
```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` 的技能對代理隱藏
|