OpenCode Skill 发现机制与配置经验

问题背景

想要在 OpenCode 中调用 Superpowers 的 skills，但 skills 无法出现在 skill 搜索列表里。

关键发现

OpenCode Skill 搜索机制

核心原理： OpenCode 搜索的是 SKILL.md 文件里 Front-Matter 的 name 字段，不是目录名或文件路径。

---
name: brainstorming-superpowers  ← 这个字段决定搜索结果
description: "Use when ..."
---

# Skill Content

错误假设

我以为的方式	实际机制
symlinks 可以跨目录复用	❌ OpenCode 不识别 symlinks
目录名 = skill 名	❌ 必须看 SKILL.md 里的 name 字段
文件名 = skill 名	❌ 同上

正确配置步骤

1. Skill 文件位置

~/.agents/skills/superpowers-brainstorming/
├── SKILL.md                        ← 必须有
├── scripts/                        ← 可选
├── spec-document-reviewer-prompt.md ← 可选
└── visual-companion.md             ← 可选

2. SKILL.md 结构要求

---
name: <name>-<suffix>    # ← 必须加后缀区分来源
description: "Use when ..." # ← 描述触发条件
---

# Skill Title

## Content...

3. 命名规范

为了在众多 skills 中区分来源，使用特定后缀：

Skill 来源	命名示例
Superpowers	brainstorming-superpowers
Baoyu	baoyu-url-to-markdown
GStack	gstack-qa

4. 同步更新

修改 SKILL.md 后，需要同步到 ~/.agents/skills/：

# 每次修改 skills 目录后
cp -r /path/to/superpowers/skills/* ~/.agents/skills/

排查步骤

Step 1: 确认文件存在

ls ~/.agents/skills/superpowers-*/

Step 2: 确认 name 字段正确

grep "^name:" ~/.agents/skills/superpowers-*/SKILL.md

Step 3: 重启 OpenCode 刷新缓存

Step 4: 在 OpenCode 中搜索

搜索 brainstorming-superpowers（完整 name 字段值）

参考

• Superpowers skills: /Users/taochen/Projects/github/superpowers/skills/
• OpenCode skills 目录: ~/.agents/skills/
• OpenCode 配置: ~/.config/opencode/