本文档介绍如何在 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：
| Skill | 描述 | 来源 |
|---|---|---|
vercel-react-best-practices | React/Next.js 性能优化指南（45 条规则，8 个类别） | Vercel |
web-design-guidelines | 网页界面设计规范审查工具 | Vercel |
frontend-design | 前端设计最佳实践 | Anthropic |
安装 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关键参数说明
| 参数 | 说明 |
|---|---|
-a, --agent <agents...> | 指定安装到的 agent（如opencode） |
-g, --global | 安装到用户目录而非项目目录 |
-s, --skill <skills...> | 指定要安装的 skill 名称 |
-l, --list | 列出可用 skills 而不安装 |
-y, --yes | 跳过所有确认提示 |
安装后修正目录名（重要！）
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/skill2. 不需要修改配置文件
OpenCode 自动从~/.config/opencode/skill/目录加载 Skills，无需修改opencode.json。
3. 安装位置选择
| 安装方式 | 路径 | 适用场景 |
|---|---|---|
全局（-g） | ~/.config/opencode/skill/ | 所有项目共享 |
项目（不加-g） | .opencode/skill/ | 项目特定技能 |
4. 验证安装
# 检查目录存在ls-la ~/.config/opencode/skill/# 查看 skill 文件内容cat~/.config/opencode/skill/vercel-react-best-practices/SKILL.md5. Skills 发现路径
add-skill会在仓库中搜索 Skills 的标准位置：
- 根目录（包含
SKILL.md） skills/skills/.curated/skills/.experimental/.agents/skills/.claude/skills/.opencode/skills/
6. 兼容性
大多数 Skills 在不同 Agent 间通用，但某些功能是 Agent 特定的：
| 功能 | OpenCode | Claude Code | Cursor | Codex |
|---|---|---|---|---|
| Basic skills | ✅ | ✅ | ✅ | ✅ |
allowed-tools | ✅ | ✅ | ✅ | ✅ |
| Hooks | ❌ | ✅ | ❌ | ❌ |
常见问题
Q1: 如何列出已安装的 Skills？
ls-la ~/.config/opencode/skill/Q2: 如何卸载某个 Skill？
# 删除目录或符号链接rm-rf ~/.config/opencode/skill/skill-nameQ3: Skills 没有生效怎么办？
- 检查目录名：确保是
skill/而非skills/ - 检查文件内容：验证
SKILL.md包含有效的 YAML frontmatter - 重启 OpenCode：某些情况下需要重启
- 检查 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
