oc/skills/opencode-config/references/02-skills.md

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..." 收窄误触

正面:

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.

反面 (太泛):

description: Helps with development

工具描述 (模型看到什么)

<available_skills> 列出每个 skill 的 name + description:

<available_skills>
  <skill>
    <name>git-release</name>
    <description>Create consistent releases and changelogs</description>
  </skill>
</available_skills>

模型用 skill({ name: "git-release" }) 加载。

权限配置

全局 (opencode.json):

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}

行为	效果
allow	立即加载
deny	对代理隐藏,拒绝访问 (模型看不到)
ask	加载前弹确认

按代理覆盖:

# 自定义代理 frontmatter
---
permission:
  skill:
    "documents-*": allow
---

// 内置代理 opencode.json
{
  "agent": {
    "plan": {
      "permission": { "skill": { "internal-*": "allow" } }
    }
  }
}

禁用 skill 工具 (代理完全用不了):

# 自定义代理
---
tools:
  skill: false
---

// 内置代理
{ "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:

---
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: "..." }) 验证内容能加载。