mirror of
https://gitea.toothfairyai.com/ToothFairyAI/tf_code.git
synced 2026-04-11 11:18:34 +00:00
223 lines
4.4 KiB
Plaintext
223 lines
4.4 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 工作樹。
|
||
它載入 `skills/*/SKILL.md` 中任何匹配的 `.opencode/` 以及一路上任何匹配的 `.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` 等。
|
||
|
||
---
|
||
|
||
## 覆寫每個代理
|
||
|
||
為特定代理授予與全域預設權限不同的權限。
|
||
|
||
**對於自定義代理**（在代理前言中）：
|
||
|
||
```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` 的技能對代理隱藏
|