OpenCode 与 Claude Code Skills 兼容机制

基于 sst/opencode 源码分析，说明 OpenCode 如何原生兼容 Claude Code 的 Skills 系统

核心发现

OpenCode 原生支持读取 Claude Code 的 Skills 目录，这是 OpenCode 内置功能，不依赖任何第三方插件。

源码位置：packages/opencode/src/skill/skill.ts (sst/opencode)

Skill 扫描顺序

OpenCode 按以下顺序扫描 Skill 目录：

优先级	位置	说明
1	~/.claude/skills/	全局 Claude Code Skills
2	<project>/.claude/skills/	项目级 Claude Code Skills
3	~/.config/opencode/{skill,skills}/**/SKILL.md	全局 OpenCode Skills
4	<project>/.opencode/{skill,skills}/**/SKILL.md	项目级 OpenCode Skills
5	config.skills.paths 中配置的路径	自定义 Skills 路径

源码证据

// packages/opencode/src/skill/skill.ts
const OPENCODE_SKILL_GLOB = new Bun.Glob("{skill,skills}/**/SKILL.md")
const CLAUDE_SKILL_GLOB = new Bun.Glob("skills/**/SKILL.md")
 
// 扫描 Claude Code 目录
const claudeDirs = await Array.fromAsync(
  Filesystem.up({
    targets: [".claude"],
    start: Instance.directory,
    stop: Instance.worktree,
  }),
)
const globalClaude = `${Global.Path.home}/.claude`

环境变量控制

可以通过环境变量禁用 Claude Code 兼容：

# 禁用 Claude Code Skills 扫描
export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=true
 
# 完全禁用 Claude Code 兼容（包括其他功能）
export OPENCODE_DISABLE_CLAUDE_CODE=true

源码位置：packages/opencode/src/flag/flag.ts

export const OPENCODE_DISABLE_CLAUDE_CODE = truthy("OPENCODE_DISABLE_CLAUDE_CODE")
export const OPENCODE_DISABLE_CLAUDE_CODE_SKILLS =
  OPENCODE_DISABLE_CLAUDE_CODE || truthy("OPENCODE_DISABLE_CLAUDE_CODE_SKILLS")

添加自定义 Skill

方式一：OpenCode 目录（推荐）

mkdir -p ~/.config/opencode/skills/my-skill
cat > ~/.config/opencode/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: 当用户需要 XXX 时使用此技能
---
 
# Skill 内容
 
详细指令写在这里...
EOF

方式二：Claude Code 目录（两边通用）

mkdir -p ~/.claude/skills/my-skill
cat > ~/.claude/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: 触发描述
---
 
# 内容
EOF

在此目录创建的 Skill 可同时被 Claude Code 和 OpenCode 识别。

方式三：配置额外路径

在 ~/.config/opencode/opencode.json 中添加：

{
  "skills": {
    "paths": ["~/my-custom-skills", "./project-skills"]
  }
}

Skill 文件格式

---
name: skill-name              # Skill 名称
description: 触发描述         # 用于自动匹配的描述
globs:                        # 可选：关联的文件模式
  - "**/*.ts"
alwaysAllow:                  # 可选：预授权的工具
  - Bash(npm run build)
mcp:                          # 可选：关联的 MCP 服务器
  command: npx
  args: ["some-mcp-server"]
---
 
# Skill 内容
 
实际指令内容...

Slash Commands 兼容

除了 Skills，oh-my-opencode 还提供了 Claude Code Commands 加载器，可以读取 ~/.claude/commands/ 目录中的自定义命令。

工作原理

oh-my-opencode 的 claude-code-command-loader 模块会扫描 Claude Code 的 commands 目录，将用户自定义的 slash commands 加载到 OpenCode 中。

示例

在 Claude Code 中创建的 /commit 命令：

~/.claude/commands/commit.md

---
allowed-tools: Bash(git:*)
description: 审阅代码并提交（不带签名）
argument-hint: [可选的commit message]
---
 
## 任务
 
1. 判断是否需要 diff
2. 审阅改动
3. 生成 commit message
4. 执行 `git add -A && git commit -m "message"`

这个命令会被 oh-my-opencode 自动加载，在 OpenCode 中也可以使用 /commit。

Commands 目录

位置	说明
~/.claude/commands/	全局用户自定义命令
<project>/.claude/commands/	项目级自定义命令

与 oh-my-opencode 的关系

oh-my-opencode 是一个 OpenCode 插件，但它不是提供 Claude Code Skills 兼容的来源（那是 OpenCode 原生功能）。

oh-my-opencode 的实际作用：

• 提供自定义 Agent 配置（sisyphus, oracle, explore 等）
• 提供 delegate_task 的 category 系统
• 注入内置 Skills（playwright, git-master 等）
• 加载 Claude Code 的 Slash Commands（~/.claude/commands/）
• 加载 Claude Code 的 Plugins（agents、hooks 等）
• 提供额外的 MCP 服务器和工具

目录结构示例

~/.claude/                          # Claude Code 主目录
├── commands/                       # 用户自定义 Slash Commands
│   └── commit.md                   # 会被 oh-my-opencode 加载到 OpenCode
├── plugins/
│   ├── installed_plugins.json      # 已安装插件列表
│   └── cache/                      # 插件缓存
│       └── claude-plugins-official/
│           └── superpowers/
│               ├── skills/         # 插件提供的 Skills
│               ├── commands/       # 插件提供的 Commands
│               └── agents/         # 插件提供的 Agents
└── skills/                         # 用户自定义 Skills
    ├── frontend-design/SKILL.md
    └── using-git-worktrees/SKILL.md

~/.config/opencode/                 # OpenCode 主目录
├── opencode.json                   # 主配置
├── oh-my-opencode.json             # oh-my-opencode 插件配置
└── skills/                         # OpenCode Skills
    └── my-skill/SKILL.md

注意事项

插件 Skills 不会自动加载

OpenCode 只扫描 ~/.claude/skills/ 目录，不会自动扫描 ~/.claude/plugins/cache/ 中的插件 skills。

如果需要在 OpenCode 中使用 Claude Code 插件的 skills（如 superpowers 的 skills），需要手动配置：

方式一：创建符号链接

ln -s ~/.claude/plugins/cache/superpowers-dev/superpowers/4.1.1/skills/* ~/.claude/skills/

方式二：配置 skills.paths

{
  "skills": {
    "paths": ["~/.claude/plugins/cache/superpowers-dev/superpowers/4.1.1/skills"]
  }
}

cc-switch 工具

如果使用 cc-switch 管理 Claude Code/OpenCode，它会：

• 将 skills 安装到 ~/.cc-switch/skills/
• 在 ~/.claude/skills/ 和 ~/.config/opencode/skills/ 中创建符号链接

相关链接

• OpenCode - OpenCode 产品介绍
• Claude Code - Claude Code 产品介绍
• MCP vs Skills vs Commands - Claude Code 扩展能力对比
• sst/opencode 源码
• oh-my-opencode