OpenCode Skills 使用指南

本文档介绍如何在 OpenCode 中使用 Agent Skills 扩展 AI 编程助手的能力。

目录

• 什么是 Skills
• 安装 Skills
• 使用 Skills
• 注意事项
• 常见问题
• 相关资源

什么是 Skills

Skills 是可重用的 AI Agent 能力扩展，通过SKILL.md文件定义，包含 YAML frontmatter（名称和描述）和详细指令。Skills 可以让 Agent 执行专门的复杂任务，例如：

• 生成发布说明（从 Git 历史）
• 按团队约定创建 PR
• 集成外部工具（Linear、Notion 等）
• 应用特定框架的最佳实践

当前可用的 Skills

从 skills.sh 可以浏览热门 Skills：

安装 Skills

前置要求

• 已安装 OpenCode
• 已安装 Node.js 和 npm/npx

安装命令

# 方式 1：查看可用 skillsnpx add-skill vercel-labs/agent-skills --list# 方式 2：安装到 OpenCode（全局）npx add-skill vercel-labs/agent-skills -a opencode -g# 方式 3：安装特定 skillnpx add-skill vercel-labs/agent-skills -s vercel-react-best-practices -a opencode -g# 方式 4：无交互安装所有 skillsnpx add-skill vercel-labs/agent-skills -y -g

关键参数说明

安装后修正目录名（重要！）

add-skill工具安装到~/.config/opencode/skills/（复数），但 OpenCode 期望的路径是~/.config/opencode/skill/（单数），需要手动修正：

# 安装后执行此命令mv~/.config/opencode/skills ~/.config/opencode/skill

支持的源格式

# GitHub 简写npx add-skill vercel-labs/agent-skills# 完整 GitHub URLnpx add-skill https://github.com/vercel-labs/agent-skills# 仓库中特定 skillnpx add-skill https://github.com/vercel-labs/agent-skills/tree/main/skills/frontend-design# GitLab 或其他 git 仓库npx add-skill https://gitlab.com/org/repo npx add-skill git@github.com:owner/repo.git

使用 Skills

自动激活机制

Skills 在任务匹配其description时自动激活，无需手动调用。OpenCode 会分析用户请求并与已安装 Skills 的描述进行匹配。

示例

React/Next.js 相关任务

自动激活vercel-react-best-practices：

• “帮我优化这个 React 组件的性能”
• “重写这段 Next.js 代码”
• “检查我的 React 代码有什么性能问题”
• “如何优化 bundle 大小？”

UI/UX 审查任务

自动激活web-design-guidelines：

• “review my UI”
• “检查这个页面的可访问性”
• “audit design for best practices”
• “review UX of this interface”

Skill 格式说明

每个 Skill 是一个目录，包含SKILL.md文件：

--- name: my-skill description: 简要描述这个 skill 的功能和使用场景 license: MIT metadata: author: your-name version: "1.0.0" --- # Skill 标题 当这个 skill 被激活时，Agent 需要遵循的指令。 ## When to Use 描述何时应该使用这个 skill（触发条件）。 ## Instructions 1. 第一步操作 2. 第二步操作 3. 其他步骤... ## Additional Sections 可以添加更多章节，如： - 注意事项 - 代码示例 - 参考资料

必需字段：

• name：唯一标识符（小写，可使用连字符）
• description：简要说明 skill 功能和触发场景

注意事项

1. 目录名必须修正

⚠️这是最常见的坑：add-skill安装到skills/，但 OpenCode 读取skill/。

# 安装后必须执行mv~/.config/opencode/skills ~/.config/opencode/skill

2. 不需要修改配置文件

OpenCode 自动从~/.config/opencode/skill/目录加载 Skills，无需修改opencode.json。

3. 安装位置选择

4. 验证安装

# 检查目录存在ls-la ~/.config/opencode/skill/# 查看 skill 文件内容cat~/.config/opencode/skill/vercel-react-best-practices/SKILL.md

5. Skills 发现路径

add-skill会在仓库中搜索 Skills 的标准位置：

• 根目录（包含SKILL.md）
• skills/
• skills/.curated/
• skills/.experimental/
• .agents/skills/
• .claude/skills/
• .opencode/skills/

6. 兼容性

大多数 Skills 在不同 Agent 间通用，但某些功能是 Agent 特定的：

常见问题

Q1: 如何列出已安装的 Skills？

ls-la ~/.config/opencode/skill/

Q2: 如何卸载某个 Skill？

# 删除目录或符号链接rm-rf ~/.config/opencode/skill/skill-name

Q3: Skills 没有生效怎么办？

1. 检查目录名：确保是skill/而非skills/
2. 检查文件内容：验证SKILL.md包含有效的 YAML frontmatter
3. 重启 OpenCode：某些情况下需要重启
4. 检查 description：确保你的请求能匹配 skill 的描述

Q4: “No skills found” 错误

• 确保仓库包含有效的SKILL.md文件
• 检查 frontmatter 是否包含name和description
• 尝试直接访问 GitHub 仓库验证

Q5: 安装权限错误

确保对目标目录有写权限：

chmod-R u+w ~/.config/opencode/

Q6: 如何创建自己的 Skill？

# 初始化 skill 模板npx skills init my-skill# 编辑 SKILL.md 定义你的技能vimmy-skill/SKILL.md# 发布到 GitHub 后安装npx add-skill your-username/your-skill-repo -a opencode -g

相关资源

• Skills 目录：https://skills.sh/
• Agent Skills 规范：https://agentskills.io
• OpenCode 文档：https://opencode.ai/docs/skills
• add-skill 仓库：https://github.com/fforres/skills
• Vercel Agent Skills：https://github.com/vercel-labs/agent-skills

快速参考

# 查看可用 skillsnpx add-skill vercel-labs/agent-skills --list# 安装到 OpenCodenpx add-skill vercel-labs/agent-skills -a opencode -g# 修正目录名（必须！）mv~/.config/opencode/skills ~/.config/opencode/skill# 验证安装ls-la ~/.config/opencode/skill/# 安装到其他 agentsnpx add-skill vercel-labs/agent-skills -a claude-code -a cursor -g# CI/CD 友好的安装npx add-skill vercel-labs/agent-skills -s frontend-design -a opencode -g -y