sync: import skills/, plugins/, memory/ and shared files from origin/main
This commit is contained in:
opencode-sync
@@ -0,0 +1,199 @@
|
||||
# 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: "..." })` 验证内容能加载。
|
||||
Reference in New Issue
Block a user