最近一年我把 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 有 SkillsCodex 也在推 Agent SkillsOpenCode 同样支持。说白了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): opencodes 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.texSKILL.md里除了工作流程还会放一个默认模板的简要说明。我在templates/article.tex里放的是支持中文排版的最小可用模板\documentclass[12pt,a4paper]{article} \usepackage[UTF8]{ctex} \usepackage{amsmath, amssymb} \usepackage{booktabs} \usepackage[margin2.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 高频报错速查表我在大量实操里攒了不少奇奇怪怪的问题挑高频的整理成一个速查表方便你直接查。现象根因解决方案error from provider (console): opencodes free tier can only be used from within opencodeconsole 免费额度绑定官方客户端不能对外提供通用接口在 OpenCode 内使用免费档或换正式 API Key、OpenCode Go 套餐模型进入长篇思考但不生成最终代码选了推理型模型输出阶段卡住换非推理模型或要求模型先给结论再给思考过程Skill 装了但从来没被触发description写得太模糊或目录放错检查目录和 frontmatter重写description加入明确触发词Windows 下执行命令超时或乱码shell 选错和脚本语法不兼容切换到 PowerShell 7 或 WSL在配置里显式指定 shell从 Claude Code 搬来的 Skill 不生效frontmatter 里带工具特有字段精简 frontmatter只留name和description有些命令在交互界面里只能看到一堆日志模型在等待输出需要刷新或调整 verbose 模式换模型、降低思考强度或重启会话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 用起来才会越来越顺手。