OpenCode 添加 Skills 完全指南：安装、编写与实战排查

最近一年我把 Cursor、Windsurf、VS Code Copilot、Trae、Claude Code、Codex 这些 AI 编程助手轮着用了个遍，最后留在终端里的反而是 OpenCode。原因很简单：它不搞花里胡哨的界面，直接在命令行里干活，多模型自由切换，git 集成和 Agent 调度又足够硬，日常写代码、改 bug、重构成套流程都能压在一个终端会话里完成。后来我把 Claude Code 时代就攒下的一堆 Skills 也迁移了过来，才真正体会到“AI 编程助手 + Skills”这个组合的厉害。

这篇文章就讲一件事：怎么给 OpenCode 添加 Skills，以及怎么把 Skills 用好。包括 Skills 到底放在哪里、从 GitHub 和技能库怎么装、如何写一个属于自己的 Skill、装完怎么验证，再有就是我在实战中撞过的坑和一个一个排查出来的解决方案。无论是刚接触 OpenCode 的新手，还是从 Claude Code、Codex 转过来的老手，照着这篇文章操作基本够用。

1. OpenCode 到底是个什么干活的东西

1.1 终端里的 Agent，不是又一个编辑器插件

OpenCode 本质上是一个跑在终端里的 AI 编程智能体，和 Claude Code、Codex CLI 是同一类东西。它不绑定某个 IDE，也不强求你用某个图形界面，你只需要在项目目录里执行opencode，它就会读取当前仓库的结构、git 状态、文件内容，然后基于你给的指令去规划任务、调用工具、编辑代码、执行命令。你看到的是一块黑底白字的交互界面，背后其实是模型在驱动一整套“读代码—写代码—跑命令—看结果”的循环。

它和 Cursor、Windsurf、Trae 的区别在于：后者把 AI 能力塞进编辑器里，适合鼠标点一点、测一测代码补全；OpenCode 则更像一个“线上的同事”，你跟它用自然语言说“帮我修复这个问题”“给这个模块补测试”“重构这段逻辑”，它会自己规划步骤，而不是只给你一段回填的补全代码。Copilot 负责“写一段”，OpenCode 负责“办成一件事”，两者在动作层级上有本质差别。

OpenCode 的配置也特别适合折腾：所有配置集中在~/.config/opencode/opencode.json，模型供应商、默认模型、shell、MCP 服务器、Skills 都可以在这里配置。换一台机器，把这套配置和 Skills 目录拷过去，之前积累的“工作方式”就完整带过去了，长期用下来非常省心。

1.2 Skills 在 OpenCode 里到底扮演什么角色

Skills 这个名字最近在 AI 编程助手里被炒得很热，Claude Code 有 Skills，Codex 也在推 Agent Skills，OpenCode 同样支持。说白了，Skills 就是一组“带说明文档的能力包”：一个文件夹里放一份SKILL.md说明文档，里面写清楚这个技能在什么场景下使用、执行步骤是什么、有什么规则和模板，文件夹里还可以附带脚本、参考文档、示例代码。

你可以把 Skills 理解成给新入职员工准备的“部门工作手册 + 操作 SOP”。平时这些手册不会天天背给员工听，但当任务匹配到手册描述的场景时，员工就会翻出对应的那本手册，照着里面的流程做。OpenCode 的模型也是一样，它会扫描所有 Skills 的description，一旦发现当前任务和某个 Skill 的描述匹配，就会把那个 Skill 文件夹里的内容加载进上下文，然后按里面的步骤走。

所以 Skills 和普通 Prompt 的最大区别是“可路由、可复用”。你不用在每次对话里重复一大段提示词，也不用担心上下文被无关的规则撑爆。模型在真正需要时才加载对应的 Skill，知识是分模块存放的。在实际项目中，我见过有人专门做前端开发 Skills、数学建模 Skills、LaTeX 排版 Skills，甚至还有人把 AI 漫剧的整套制作流程写成了 Skills，本质都是把高频出现的复杂工作流程固化下来。

这里顺便说清楚 Skills 和 MCP、Plugins 的区别。Skills 解决的是“怎么做”的问题，它是一套指令和流程，未必需要程序接口；MCP 解决的是“拿什么做”的问题，它把外部数据源、数据库、文件系统以工具的形式暴露给模型；Plugins 则是在 OpenCode 主程序层面做扩展，比如改状态栏、拦截某类事件、自定义命令。三者能配合，但不能互相替代。

2. 装 OpenCode 与第一次跑起来

2.1 安装方式：官方脚本、npm、桌面版

OpenCode 的安装方式很传统，你可以在官网找到安装脚本，我这边用curl -fsSL https://opencode.ai/install | bash装过，体验很顺。npm 党注意一下：npm 包名是opencode-ai，不是opencode，因为opencode这个名字已经被别的包占了。执行：

npm install -g opencode-ai

如果你日常用 bun，也可以bun install -g opencode-ai。装完检查一下版本：

opencode --version

看到版本号就说明基础环境已经 ready 了。需要说明的是，这些命令以你手头版本的官方文档为准，安装方式隔一段时间就会优化，但核心字符串基本不变。

除了终端版，OpenCode 官方还出了桌面版，适合不太想在黑窗口里折腾的人。桌面版本质上还是同一个引擎，只是外壳变成了图形界面，Skills 的目录和配置路径和命令行版本是通用的，所以这篇文章讲的内容在桌面版里同样适用。

2.2 Windows 用户怎么选 Shell 才不容易翻车

经常有人问“OpenCode 在 Windows 环境下什么 shell 工具好用”，这个问题的实质是 OpenCode 需要调用 shell 去执行命令，Windows 默认的 cmd 和 PowerShell 5 在某些场景下姿势不够舒服，尤其碰到包含 UTF-8 中文路径、shell 脚本、管道符拼接的时候，容易出各种幺蛾子。

我实测过几套方案，比较推荐的是：Windows Terminal + PowerShell 7 + OpenCode。PowerShell 7 的语法更现代，对 UTF-8 的支持比 5 好不少，配合 Windows Terminal 的多标签页，体验已经接近 mac 上的终端。如果你主力是用 WSL 做开发，那更省心：直接在 WSL 里装 OpenCode，让它跑在 Linux 环境里，这样bash、grep、find、git这些工具链都统一了，Skills 里的脚本也基本不用改就能跑。

如果你用的是 Git Bash，也不是不能用，但会遇到一些小毛病，比如某些命令的输出格式会被 Git Bash 的层转换搞乱。我的建议是，在opencode.json里显式指定 shell：

{ "shell": "pwsh" }

这样 OpenCode 在执行命令时就会走 PowerShell 7，而不是系统默认的 cmd。Windows 上折腾 OpenCode，最关键的一步就是把 shell 处理干净，很多看似“模型不听话”“命令执行不了”的问题，最后都栽在 shell 环境上。

2.3 模型配置、免费额度以及那个出镜率极高的报错

OpenCode 第一次启动时会让你选择模型供应商。选项一般分为三类：一是走“console”这个自带的免费档，二是绑定你自己的 Anthropic、OpenAI、DeepSeek 等 API Key，三是使用 OpenCode Go 这类官方订阅。如果你只是想快速体验，用 console 免费档就够了；真要拿它当日常生产力工具，我建议至少有一个自己的 API Key，或者开通 OpenCode Go。

配置文件里大致是这样：

{ "provider": "console", "model": "free", "autoupdate": true }

很多人在这个环节会遇到一个经典报错：error from provider (console): opencode's free tier can only be used from within opencode。

这个报错的意思非常直白：console 供应商的免费额度，只能在 OpenCode 官方客户端里用，不能把免费额度当成一个通用接口拿出去给别的工具刷任务。也就是说，你想用 console 免费模型去喂 Claude Code、Codex CLI 或者其他第三方客户端，基本都会撞上这个错。解决办法也简单：要么老老实实把 console 免费档放在 OpenCode 里用，要么去你自己的模型供应商那边申请正式 API Key，要么升级到 OpenCode Go 的付费套餐换取更完整的接口权限。免费的东西看着香，但边界很明确，我踩过一次之后就长记性了。

还有一个和模型行为相关的常见疑惑：opencode 只思考不回答。这通常不是因为模型坏了，而是因为你选的模型是推理型模型，思考过程写了很多，最终输出部分反而迟迟不落笔。处理方法我从实践看有两条：一是把模型切换成普通快模型，比如非 reasoning 版本的模型；二是在 prompt 里明确要求“先给出结论和可行方案，再补充思考过程”，让模型把输出顺序反过来。

3. 给 OpenCode 加 Skills 的四条路径

3.1 先搞懂 Skills 到底该放在哪

OpenCode 的 Skills 目录分成两种：全局和项目级。全局目录通常是：

~/.config/opencode/skills/<技能名>/SKILL.md

项目级目录是：

<你的项目>/.opencode/skills/<技能名>/SKILL.md

两个目录的优先级和处理逻辑不太一样。全局目录适合放那些“不管在哪个项目里都可能用到”的技能，比如通用代码审查、Git 提交信息生成、文档写作规范；项目级目录适合放“只对这个仓库有意义”的技能，比如这个项目特有的架构规范、测试命令、部署流程。模型扫描 Skills 时，两个目录都会看，但项目级内容离当前任务更近，命中后对上下文的污染也更可控。

每个 Skill 的标准形态是一个文件夹，里面开头是SKILL.md，后面可以跟reference/、scripts/、templates/等子目录。SKILL.md的头部有一段 YAML frontmatter，里面最重要的是name和description。name是技能的唯一标识，description则决定了模型什么时候会想起这个技能。想加新 Skill，本质就是在这些目录里新增一个文件夹并写对SKILL.md。

3.2 用内置命令安装

新版本的 OpenCode 提供opencode skills这个子命令，用来管理 Skills。你可以先跑一下看看：

opencode skills list opencode skills --help

如果版本较新，通常支持从本地目录、Github 仓库或者压缩包安装，常见形态是：

opencode skills add /path/to/skill-folder opencode skills add https://github.com/owner/repo

我把话说在前面：OpenCode 的 CLI 命令迭代比较快，不同版本之间skills子命令的细节可能有差异。如果你敲完发现没有这个子命令，或者参数对不上，别纠结，直接用 3.3 节的手动复制法，效果一模一样。手动复制永远不会过时，因为 Skills 的本质就是文件夹。

3.3 从 GitHub 手动安装：Claude Code 的 Skills 也能直接搬

现在社区里的 Skills，一半以上被挂在 Claude Code 名下，比如 Anthropic 官方维护的anthropics/skills，还有大神 obra 整理的obra/superpowers，后者几乎成了社区里的一个“技能集散地”。这些仓库里的 Skills 拿到 OpenCode 里能不能用？绝大多数能，只要它内部是“文件夹 + SKILL.md + YAML frontmatter”的结构，OpenCode 就能读。

手动安装的步骤非常简单，以anthropics/skills为例：

git clone --depth 1 https://github.com/anthropics/skills.git mkdir -p ~/.config/opencode/skills cp -r skills/某技能 ~/.config/opencode/skills/

复制完成后，检查一下这个技能的SKILL.md头部格式：

--- name: skill-name description: 当用户需要……时使用。 ---

只要name和description都在，基本就能被 OpenCode 识别。如果某个仓库里的 Skills 是裸的 Markdown 文件，没有文件夹，也没有 frontmatter，那就需要你手动包一层：建一个文件夹，把 Markdown 挪进去改名SKILL.md，然后在文件头补上简单的name和description。

如果你像我一样同时用 Claude Code、Codex 和 OpenCode，还可以用软链接让几个工具共享同一份 Skills 目录，避免重复维护。比如 CodeBuddy 和 Claude Code 公用了一套 skills，我就在 OpenCode 的目录里加了软链接：

ln -s ~/.codex/skills/某技能 ~/.config/opencode/skills/某技能

这样同一个技能更新一处，三处生效。不过要留意不同工具对 frontmatter 字段的兼容性，极个别技能里带了一些工具特有的字段，迁移后模型可能读不懂，处理办法是删掉多余字段，只留name和description，把其余内容写进正文。

3.4 从技能库挑选推荐 Skill

社区里已经有不少“Skills 源网站”性质的项目，你可以把它们理解为 Skills 的聚合站。挂在上面的技能包覆盖的场景很广，常见的有这几类方向：

• 前端开发 Skills：处理 Vue/React 组件、调试 CSS 布局、生成组件测试。
• 文档与排版 Skills：生成 Markdown 结构、LaTeX 论文模板、接口文档。
• 数学建模类 Skills：启发式思路、数据预处理、论文图表规范。
• 图片生成 Skills：多数是用 SVG 或 Canvas 画出可编辑图形，或者调用外部生图 API 的封装流程。

搜索的时候直接敲“Skills 推荐”“superpower skills”“codex skills”“skills 源网站”这类关键词就能找到。我的建议是不要一口气装几十个，先选两三个最贴合自己工作的，用熟了再逐步扩充。一个没经过验证的社区技能，可能会给出错误的工作流，甚至有不安全的脚本，装之前务必要打开SKILL.md和脚本看一遍，别盲目信任下载文件。

3.5 怎么验证 Skill 真的生效了

装完 Skill 最怕的就是“感觉没装上”。验证其实分三步。

第一步，从磁盘层面确认结构存在且可读，直接跑：

find ~/.config/opencode/skills -maxdepth 2 -name SKILL.md

能看到目标 Skill 的SKILL.md路径，说明文件层面上没有丢。

第二步，检查 frontmatter 是否合法。最稳妥的方法是把这个SKILL.md打开，确认 YAML 区域里没有奇怪的制表符，description没有写成空。顺手用opencode skills list看一下 OpenCode 自己能不能枚举出这个技能。

第三步，也是真正意义上的验证：在对话里明确触发它，类似“请先读一下 xxx skill，然后按它的流程处理”。如果模型回复里引用了 Skill 里的规则和步骤，甚至主动提到了技能名称，那就说明它已经成功加载。更硬核一点，可以给 OpenCode 开 verbose 或 debug 模式，观察启动时扫描加载了哪些 Skills，这个方法在排查问题时最直观。

4. 写一个自己的 Skill：从零到能干活

4.1 SKILL.md 的结构与 frontmatter

自己写 Skill 真的不难，关键是结构要规范。一个 Skill 文件夹里最重要的就是SKILL.md，它的形态我直接放出来：

--- name: latex-typesetting description: 当用户要求生成 LaTeX 文档、排版学术论文、处理数学公式、整理表格或参考文献时使用。如果不涉及 LaTeX 相关需求，不要使用。 --- # LaTeX 排版技能 ## 适用场景 - 需要生成 LaTeX 文档骨架 - 需要把 Markdown 内容转为 LaTeX 结构 - 需要排版数学公式、表格、参考文献 ## 工作流程 1. 先询问用户是否已有模板或确定论文类型 2. 生成 main.tex 文件，设置 documentclass、宏包、中文支持 3. 按内容分章节组织 4. 使用 xelatex 编译并反馈报错

name起一个短小精确的英文名，description里写清楚“什么时候用、什么时候不要用”。描述写得好不好，直接决定这个 Skill 会不会被误触发，或者该触发时没触发。

4.2 触发词怎么写才不会被误调用

很多人写description时容易犯一个错：写得太大而全。比如“这段代码可以帮你写任何文字”，模型一看这描述，几乎所有对话都会尝试加载，结果 Skill 里的步骤和当前任务根本不搭，反而拉低了回答质量。

正确写法是把“适用条件”和“否定条件”都写清楚。你可以参考这种句式：

当用户要求生成化学实验报告，包含实验目的、步骤、数据表格和参考资料时使用。当任务只是普通写作或与化学无关时，不要使用。

在SKILL.md正文里也可以增加一个“重要判断”的小节，告诉模型如果用户需求超出边界，应该拒绝执行而不是硬套。写触发词的时间花得值，后期几乎不用手动纠正。

4.3 实操案例：做一个 LaTeX 排版 Skills

我平时要写技术文档，经常需要把草稿排成干净美观的 LaTeX 文档，于是专门写了一个latex-typesetting技能。文件夹结构是这样的：

~/.config/opencode/skills/latex-typesetting/ ├── SKILL.md └── templates/ └── article.tex

SKILL.md里除了工作流程，还会放一个默认模板的简要说明。我在templates/article.tex里放的是支持中文排版的最小可用模板：

\documentclass[12pt,a4paper]{article} \usepackage[UTF8]{ctex} \usepackage{amsmath, amssymb} \usepackage{booktabs} \usepackage[margin=2.5cm]{geometry} \title{标题} \author{作者} \date{\today} \begin{document} \maketitle \section{引言} \end{document}

SKILL.md里明确要求模型：生成main.tex之后，代码块里给出编译命令latexmk -xelatex main.tex，并把常见的 LaTeX 报错搬运到反馈里。这样我只要说一句“把这篇 Markdown 排版成论文格式”，模型就会自动按步骤生成结构、补全宏包、顺手教我怎么编译。这个 Skill 写一次，后面所有文档排版都稳定复用。

4.4 进阶：在 Skill 里内置脚本

Skill 不只是文本说明书，它还可以带脚本。比如我想让模型写完 Markdown 后自动格式化表格对齐，就在 Skill 文件夹里放一个scripts/format.py，然后在SKILL.md里写一句：

- 生成文档后，运行 `python scripts/format.py 目标文件.md` 修正表格对齐

这样模型在执行 Skill 时，会把脚本当作工具箱里的工具直接调用。社区里不少复杂 Skill 都是这么设计的：SKILL.md给流程，scripts/提供具体工具，reference/放参考资料。这种设计把“知识”和“执行能力”合到了一个包里。

但这里必须提醒一句：能跑脚本的 Skill 也是一把双刃剑。从社区下载的 Skill，里面的curl命令、python脚本、wget都有可能被执行，最稳妥的做法是在第一次运行前把所有脚本通读一遍，确认没有奇怪的网络请求和危险命令。我自己的原则是，能不引入脚本就不引入，只有重复劳动确实无法用文本描述清楚时，才把逻辑写进脚本。

5. 常见问题与排查技巧实录

5.1 高频报错速查表

我在大量实操里攒了不少奇奇怪怪的问题，挑高频的整理成一个速查表，方便你直接查。

5.2 排查 Skill 问题的固定路线

排查 Skill 不生效，我个人有一个固定的“二分法”流程，效率很高。先把所有 Skill 暂时移出目录，只留下出问题的那一个，重启会话触发一次；如果还不生效，说明问题出在 Skill 内部，再逐步精简SKILL.md，从只剩一句话开始往上加内容。如果只留下单个 Skill 就生效，说明是多个 Skill 的description互相打架，导致模型选错了技能。

这套排查思路和代码调试很像：先隔离，再最小化复现。另一个自我检查的细节是，不要在一个SKILL.md里堆十几个段落、几十条规则，模型在上下文里看到的信息是有限的，太长的技能说明反而会稀释关键指令。Skill 内容应该克制，能写 10 条绝不写 50 条。

关于清理，社区里“tibo 清理 skills 的方法推荐”其实说的就是定期整理：不用的技能移出目录，过时的删掉，保留一份简短的索引，记录每个技能到底是干什么的。我一般每季度清理一次，把已经用不到的前端调试技能丢进 archive 文件夹，保持 active 目录永远只有最常用的那几个。

6. 个人经验与最后几条建议

6.1 别囤 Skills，先想清楚你的工作流

Skill 的一大诱惑是“看到好的就想装”，我早期也装过几十个，后来发现真正被高频调用的不到十分之一。无用的 Skill 不仅占磁盘空间，更重要的是它们会在模型决策时增加噪声。现在我对新 Skills 的态度是：先连续三次场景化撞上痛点，再去找现成的写一版，最后逐步迭代成自己的。能用自然语言说清楚的简单流程，不值得封装成 Skill；只有那种“步骤复杂、规则固定、重复度高”的活儿，才值得沉淀。

6.2 把项目级 Skills 和全局 Skills 分开管

全局目录里的东西要少而精，留给通用能力；项目目录里的 Skills 可以大胆一点，因为模型在这个项目里看到这些技能是有意义的。比如我在某个文档仓库里放了一个专门规范文章结构的 Skill，它在这个项目里非常好用，但如果把它放到全局目录里，就可能干扰其他项目的普通代码任务。目录隔离在这里不是洁癖，而是为了让模型在正确的时间加载正确的内容。

6.3 后续还能怎么继续折腾

如果你已经能把 Skills 玩明白，下一步就是让 Skills 和其他机制联动。比如把 MCP 服务器里的数据查询能力，和 Skill 里定义的文档模板组合在一起：Skill 负责流程，MCP 负责取数，插件负责收尾。再比如我现在的多个 AI 工具共用一套 Skill 目录，OpenCode、Claude Code、CodeBuddy 通过软链接看到同一份文件，改一处全生效，维护成本降了不少。要是你已经买了 OpenCode Go，也可以研究一下它和 Claude Code 的 switch 桥接，打通之后在终端里来回切换会很顺手。

我个人的体会是：Skills 不是代码库，它是你工作方法的外部化。刚开始写的时候会很费劲，写多了会发现一个 Skill 真正值钱的部分不是模板和脚本，而是里面沉淀下来的那几步“先做什么、再做什么、注意什么”。这些恰恰是 AI 编程助手再强也猜不出来的东西。把自己经常干的活固化成几个 Skills，再慢慢让它们替你跑腿，OpenCode 用起来才会越来越顺手。