1. 为什么最近全网都在刷“AI Skills”大概从 Claude 那边推出 Agent Skills 的概念开始整个开发者社区就像被点了一个大爆竹短视频、技术文章、朋友圈到处都在聊“AI Skills”。我一开始也觉得这就是个新词无非是把 prompt 封装得更漂亮一点直到我自己把一个带 300 行文档的“代码审查 Skill”塞进 AI 编程工具里让它按我团队的规范逐条检查 MR才发现这玩意儿是真的能改变日常开发节奏。先简单说清楚一件事AI Skills 并不是某个工具的私有功能它更像是一套“技能包”标准——把一个领域里该怎么做、要规避什么、输出格式长什么样全部写到一个叫SKILL.md的文件里。你把这个文件挂到支持它的 AI 工具里AI 遇到对应任务时就会自动按你定义的工作流来运行。你可以理解成普通 prompt 是口头交代一句“帮我写个接口”AI Skills 则是一本员工手册把“接口设计规范”“错误码怎么定”“注释怎么写”“测试怎么补”全部写清楚AI 直接照着手册干活。这套机制解决了一个特别现实的问题AI 在通用任务上很强但一遇到你团队特有的规范、你项目里的约定俗成、你行业里的标准流程它就抓瞎。Skills 的核心价值是把你脑子里的“隐性经验”变成 AI 能稳定执行的“显性流程”。但问题来了——现在全网教程十篇有八篇都在教怎么用 Claude Code 跑 Skills。Claude Code 确实是个好东西可它有几个非常现实的卡点订阅资格、账户额度、Token 消耗、模型绑定。尤其是你只是想先试水、或者想在国内的网络和支付环境下低成本跑通光是在安装和账户环节就能劝退一波人。我自己的结论很明确如果你本来就重度依赖 Claude 的模型生态Claude Code 值得留但如果你想低门槛、可定制、甚至免费跑通 SkillsOpenCode 才是更顺手的选择。这篇文章我就把我从安装 OpenCode、配置模型、到把 AI Skills 真正跑起来的完整过程以及过程中踩过的一堆坑原原本本写给你。2. 为什么我劝你先放下 Claude Code认真看看 OpenCode2.1 Claude Code 的“隐性门槛”到底在哪我不是说 Claude Code 不行它的编程能力确实在第一梯队。但“能力”和“能舒服地用起来”是两码事。先说账户层面Claude Code 需要你有对应订阅服务或者 Anthropic API 的 key登录时还会校验你账户的区域和资格。很多人好不容易装好一运行就收到类似Your organization has disabled Claude subscription access for Claude Code或者Your limits are temporarily boosted. Your weekly Claude Code limit is 50% higher的提示。这类报错跟你的代码没关系纯粹是你账户和订阅状态不满足它的策略要求——这在社区里已经是高频问题了。再说成本。Claude Code 在长对话、大项目里的 Token 消耗非常快我自己跑一个中小型项目重构一轮下来几百上千个请求很正常。如果你是走 API 按量计费费用涨起来很肉疼如果是订阅制又有周限额、并发限制这些策略。本质原因就是你被绑定在它的模型生态和计费体系里了没有太多选择空间。最后是工程化层面Claude Code 的配置项虽然丰富但如果你只是想本地 LLM 试试水或者公司内部有统一的大模型网关你很难把它掰成你想要的样子。它更像一台“整机”——开箱体验好但你想拆开换零件麻烦。2.2 OpenCode 的优势模型自由 配置透明 兼容 SkillsOpenCode 是个开源项目社区很活跃。我第一次碰它是因为刷到一条帖子说“OpenCode 能直接读 Claude Code 的 Skills 目录”我琢磨着这不就是标准化的好处吗后来我深度用了两周它的三个特点确实戳中我模型自由你可以在同一个工具里同时配置 OpenAI、Anthropic、Google、Ollama、DeepSeek、通义等多种 provider。这意味着什么意味着你不用被任何一个厂商锁死哪个模型便宜、哪个模型当前表现好你就切到哪个。甚至完全可以在本地起一个 Ollama跑 Llama 或 Qwen完全不花钱。Token 可控因为你可以自由切换模型小任务用便宜模型复杂任务再上大模型成本能压得非常低。对经常做原型验证、长期挂在 IDE 里的人来说这一点比什么都实在。Skills 标准兼容它支持读取标准的SKILL.md形式技能包。也就是说Claude 官方文档里教的 Skills 写法OpenCode 基本都能认社区里别人分享的技能包你下载下来改改路径就能用。我当时看完就想这玩意儿才更适合作为国内开发者的“第一台 AI 编程工具”。因为你不用先解决账户、订阅、区域这些破事先把环境跑起来把模型接上真的能让 AI 帮你写代码了再考虑要不要升级别的。2.3 什么情况下你仍然可以选 Claude Code讨论不能一边倒。如果你满足这几个条件Claude Code 用着也没毛病你本身已经有 Claude 订阅或 API并且试过调节配额之后体验良好你的核心场景是复杂 Agent 任务且你对 Claude 模型的输出质量有明显依赖你不想折腾模型切换能接受“一招鲜”。但如果你还在犹豫、还在纠结成本、还在被各种账户报错折磨我的建议很直接先用 OpenCode 跑起来把 Skills 机制摸透再回头判断 Claude Code 对你有没有额外价值。工具是拿来解决问题的不是拿来供着的。3. 从安装到配置OpenCode 快速上手实录3.1 安装一条命令的事但 Windows 用户要额外注意OpenCode 的安装方式很现代macOS 和 Linux 直接一行脚本搞定Windows 官方也支持。我这里给你整理一份我实测可用的安装路径。macOS 用户有 Homebrewbrew install opencodemacOS / Linux 通用脚本安装curl -fsSL https://opencode.ai/install | bashWindows 用户我最推荐用 Scoop 或者直接下载二进制先打开 PowerShellscoop install opencode装完之后先别急着用在终端里执行opencode --version如果能输出版本号说明安装成功。如果报错——注意热词里那个高频报错opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名我太熟了十个人里有三个栽在这具体解法我放到第 5 节详细讲。这里先给个纲领装完后务必重启终端或者手动刷新 PATH 环境变量。3.2 初始化配置把模型先接上安装完成后第一次运行opencode它会让你初始化配置。OpenCode 的配置默认放在~/.config/opencode/opencode.json这个配置文件长什么样我给你一个最小可用版里面同时配了远程模型和本地模型两条路{ $schema: https://opencode.ai/config.json, provider: { ollama: { npm: ai-sdk/ollama, name: Ollama, options: { baseURL: http://localhost:11434/api }, models: { qwen2.5-coder:7b: { name: Qwen2.5 Coder 7B } } } }, model: ollama/qwen2.5-coder:7b }这里我把默认模型指向了本地 Ollama 跑的 Qwen2.5-Coder 7B目的是先跑通流程。你如果机器上有 Ollama先拉模型ollama pull qwen2.5-coder:7b然后启动ollama serve再运行opencode你会发现它直接能对话了。这个配置不需要任何 API Key不花钱断网都能用本地推理非常适合刚上手时测试。你要是想接在线模型比如 DeepSeek、通义千问或者 OpenAI 兼容接口只需要再加一个 provider 块指定 API Key 环境变量和模型 ID 就行。OpenCode 底层把模型接口做得非常统一切换模型时你在对话里直接敲/models就能切换非常顺手。3.3 在 VSCode 和 JetBrains IDEA 里接入很多人喜欢在编辑器里用 AI 编程工具OpenCode 两个主流 IDE 都有插件。VSCode 里的插件直接搜“opencode”装上后左侧边栏会出现一个 OpenCode 面板你在里面登录、选模型、发起对话跟在终端里用完全一致。JetBrains IDEA 用户也省心同款插件在插件市场里搜“opencode”即可。我日常工作流是终端里跑长任务、处理小改动时用 VSCode 面板、重构时直接在 IDEA 里选一段代码发给它。这里有个小坑你如果在 IDE 插件里发现看不到模型多半是因为插件的配置目录跟 CLI 不是同一个。解决办法很简单——在 IDE 的插件设置里手动指定同一个opencode.json路径或者直接把环境变量设置到系统层面。3.4 OpenCode 的核心操作逻辑OpenCode 的交互方式跟 Claude Code 类似但更轻。你进入对话后它默认会给你一个带上下文的 shell你可以直接提问帮我看看当前项目的 package.json 有什么问题让它干活给 src/utils/date.ts 补单元测试用/调出命令面板里面包括切换模型、打开配置、管理 Skills 等常用操作尤其要记住一个快捷操作直接让 OpenCode 扫描项目目录它能读懂 Git 状态、项目结构并在需要时自动执行命令。比如你说“帮我跑一下测试看哪里挂了”它会自己去执行npm test或者pytest把失败信息抓回来分析。这一点跟 Claude Code 的核心体验是一致的。4. 把 AI Skills 真正跑起来实战一个可复用的 Skill4.1 Skills 到底是什么结构为什么这么设计讲真如果你只看教程里的截图会觉得 Skills 很玄。其实就是一叠 Markdown 文件核心是一个SKILL.md里面用结构化字段描述这个技能什么时候用、怎么用。比如我团队里用的“Python API 代码审查”技能包目录结构如下skills/ python-api-review/ SKILL.md rules/ api-design.md examples/ bad_example.py good_example.pySKILL.md的内容大概长这样--- name: python-api-review description: 按团队规范审查 Python API 代码检查路由、序列化、错误码、日志等要素。 when_to_use: 当用户要求 review Python API 代码或者代码涉及 Flask/FastAPI 路由时。 --- # Python API 审查指南 1. 检查路由命名是否符合 RESTful 风格。 2. 检查序列化字段是否正确是否缺少类型注解。 3. 错误处理必须返回统一错误结构。 ...你发现没有SKILL.md本身就是给 AI 看的一份“方法论文档”。模型读到when_to_use字段之后会在合适的场景自动调用这份技能你也能手动通过/skills命令强制指定。Skills 和普通 prompt 最大的区别是结构化、可版本管理、可复用。你一个技能包写好了团队里所有人共享AI 的输出质量瞬间拉到同一个水平线。4.2 在 OpenCode 里挂载 SkillsOpenCode 读取 Skills 的路径默认是在你的配置目录下。官方推荐的做法是把技能包放在~/.config/opencode/skills/或者项目级目录./opencode/skills/把刚才那份python-api-review技能包整体丢进去重启 OpenCode然后在对话里输入/ skills你会看到列表里出现了python-api-review。这就说明挂载成功了。接下来验证一下能不能触发我给了一个用 FastAPI 写的下单接口故意把路由命名、异常处理都写得稀烂然后问 OpenCode“帮我 review 一下这段 API 代码。”它立刻自动匹配到python-api-review技能输出了一份符合我们团队风格的审查报告甚至连“日志必须包含 request_id”这种我们写在rules/api-design.md里的细节都抓出来了。那一刻我是真的有点感慨之前我用 prompt 跟 AI 一对一交代上下文效果不稳定现在把所有规矩写进技能包它就是稳定的校规AI 只是换了个人去执行而已。确实同一个技能包在 Claude Code 里也能读。因为我根本没写过任何 OpenCode 私有的代码全部是纯 Markdown。这就是标准的好处——你要学的其实不是某个工具而是一套可迁移的工作方法。4.3 实战手写一个“项目脚手架生成” Skill为了让更多没有接触过 Skills 的读者上手我再给你拆一个更底层的例子让 OpenCode 根据一段需求描述自动生成一个 Python 项目的最小脚手架。技能包目录如下skills/ py-scaffold/ SKILL.mdSKILL.md这么写--- name: py-scaffold description: 生成 Python 项目脚手架包含源码目录、测试目录、pyproject.toml、README。 when_to_use: 当用户要求初始化一个新的 Python 项目或生成项目结构时。 --- # Python 项目脚手架生成规则 1. 创建 src/ 和 tests/ 目录。 2. pyproject.toml 中必须声明项目名、依赖和 pytest 配置。 3. README.md 必须包含安装、运行、测试三段说明。 4. 如果用户指定包名请用包名替换默认名称否则统一使用 project_name。然后我在 OpenCode 里输入帮我初始化一个 Python 项目名字叫 demo-cli需要支持命令行参数解析。OpenCode 读完技能直接生成了完整目录结构和文件内容然后用我当前终端的默认 shell 执行了创建命令。几分钟后我拿到一个可安装、可测试、可跑的 Python 包。注意它最后一步是调用真实的 shell 去执行的不是给我贴一段代码让我自己复制这点非常省事。实操下来我觉得“写 Skills”最重要的不是格式而是你想清楚两件事触发条件要明确when_to_use写得好不好直接决定 AI 会不会“误触发”或“漏触发”。指令要可执行每一条规则都必须是 AI 能直接对照执行的不能有“风格尽量统一”这种模糊表达要写成“注释必须用中文并在函数上方空一行”这种粒度。4.4 Skills 和普通对话的边界什么时候该写技能包我也见过有人什么任务都往技能包里塞最后维护成本比收益还高。我的判断标准是如果一个任务你一周要交给 AI 做两次以上且每次都要重复交代同样的规范那它就该做成技能包如果只是一次性提问写 prompt 就行。比如“帮我写正则表达式”这种不需要技能包“按我们团队的 Git commit 规范生成 commit message”“按公司安全要求扫描代码里的敏感信息”这种必须做成技能包。前者是随机需求后者是稳定流程。5. 高频问题排查与避坑清单我收集了社区里最近被刷屏的问题再结合我自己的经历整理成一张速查表。下面的问题如果你恰好碰上直接按方案处理。问题现象常见原因解决方案opencode不是 cmdlet 或内部命令安装后 PATH 未刷新重启终端或用$env:Path ;$env:USERPROFILE\AppData\Local\opencode临时刷新连接 Ollama 失败Ollama 服务没启动或端口不对执行ollama serve检查baseURL是否为http://localhost:11434/apiSkills 列表为空技能包路径不对或目录层级错误确认技能包目录下直接是SKILL.md不是多套了一层文件夹模型输出不稳定模型切错了小模型在扛复杂任务在对话中用/models切换到能力更强的模型生成代码没有按项目风格写没有写SKILL.md里的风格规则把所有规范写清楚不要指望 AI 自动领悟IDEA 插件里看不到配置插件用了独立配置目录在插件设置里手动指向 CLI 的opencode.json长任务执行到一半断开终端会话超时或网络波动先处理短问题关键任务拆几步跑mvn相关命令在 OpenCode 里执行报“command not found”OpenCode 启动时没有继承 shell 的完整环境在配置里显式设置PATH环境变量或通过sh -lc方式启动 agent 执行命令5.1 关于“无法将 opencode 识别为 cmdlet”的详细解法这个报错在 Windows 上太经典了。出现的原因就一个安装程序把二进制放进了某个目录但该目录不在你的 PATH 环境变量里。终端去系统 PATH 里找opencode.exe时找不到于是报“不是内部或外部命令”。解决办法分三步第一步找到opencode.exe所在路径。如果你用 Scoop 装的一般在这里%USERPROFILE%\scoop\shims\opencode.exe第二步把该路径加进用户 PATH。按下Win X选择“系统”-“高级系统设置”-“环境变量”找到用户变量里的Path编辑新增上面那段路径。第三步关掉终端重新打开一个新终端再执行opencode --version。大概率就好了。如果你通过脚本安装的 OpenCode它一般会装到%USERPROFILE%\.opencode\bin同样加入 PATH 即可。5.2 Claude Code 报错的正确心态与 OpenCode 兜底现在网上一搜 Claude Code一堆教程下面全是这类报错评论区。你自己折腾的时候要明白Your organization has disabled Claude subscription access这类提示基本取决于你使用的订阅账户是否匹配 Claude Code 的使用条款不是你的终端配置出问题了。很多教程不会告诉你这一层只会让你反复重装——这就是典型的无效操作。我的处理习惯是只要模型能力相差不太大优先用 OpenCode 跑同一份任务。遇到复杂的代码理解任务我可以临时切到注册好的 Claude API Key平时日常开发、Skills 验证、免费模型测试全放在 OpenCode 里面。这样既不会把鸡蛋都放在一个账户篮子里也不会被订阅限制卡死开发节奏。5.3 社区项目 oh-my-claudecode 给我的启发热词里出现的oh-my-claudecode本质上是社区开发者给 Claude Code 做的一套增强配置集合类似 oh-my-zsh 之于 zsh。它把大量 prompt、别名、工具函数封装好了给你一种“开箱即用”的感觉。我用了之后最大的启发不是它那套配置本身而是它的组织方式所有的自定义能力都应该用目录化、文档化的方式沉淀而不是散落在聊天记录里。这个思想用到 OpenCode 上就是我前面反复强调的把规范写成技能包把技能包放进skills目录随取随用。你甚至可以照着 oh-my-claudecode 的结构建一个属于自己的opencode-settings仓库把技能包、配置、常用命令全放进去换新电脑一条命令拉下来就能恢复环境。6. 最后再分享一点我的个人体会折腾了这么久我最大的感触是AI 编程工具赛道现在不缺“模型能力”缺的是“把你的工作方式固化下来”的能力。Claude Code 很强但它是别人的整套方法论OpenCode 的自由度更高你能真正把它捏成自己顺手的样子。刚开始我也有“集邮心态”哪个工具火就装哪个结果电脑里躺了三四个 AI 编程客户端真正每天打开的却只有一个。后来我学会了先定义清楚自己的需求是什么再选工具。你想把 Skills 跑起来先装 OpenCode把模型接到本地或性价比最高的服务上然后从一两个技能包开始维护等你真正体会到“AI 按你的规矩干活”是什么感觉再回头对比 Claude Code你会有自己的答案。我目前的工作流非常固定日常开放直接用 OpenCode 配 Qwen 本地模型或者 DeepSeek 的便宜模型处理技术方案设计和复杂重构时再临时切到能力更强的大模型所有规范性的审查、脚手架、提交信息生成全部走技能包。启动成本低月度成本几乎为零而且整套配置都是文件想迁移、想备份、想分享都很方便。这篇文章写到这里就差不多了。如果你正准备把 AI Skills 引入日常工作别卡在安装那一步也别死磕某一个工具。先从 OpenCode 快速跑通一个小场景比如让 AI 按你的模板生成周报或者按你的代码规范审查一次 MR你马上就能感受到“技能包”这个东西跟单纯给 AI 发 prompt 完全是两个时代的东西。剩下的路边做边探索就行。