如果你最近在终端工具圈子里逛得比较多大概率听过“OpenCode 加 Skills”的说法。我第一次接触时也懵了很久——它和普通插件有什么区别装完之后到底怎么让模型调用甚至一度被“opencode 命令无效”卡住连界面都没打开。这篇内容就是把我从零开始摸索 OpenCode AI 编程助手、并成功添加和编写 Skills 的完整过程记录下来。如果你正在用 Codex 或 Claude Code又对终端型 AI 编程助手的“技能”机制感兴趣或者你已经装了 OpenCode 但不知道 Skills 怎么落地这篇文章应该能帮到你。我会直接给思路、给命令、给目录结构也把最容易踩的坑单独挑出来讲。1. 为什么 OpenCode 突然都在聊 Skills它和插件、提示词模板的区别1.1 Skills 本质上是一份带说明书的可复用经验包先说结论Skills 不是传统意义的插件。它不编译、不运行常驻进程也不像 IDE 扩展那样给界面加按钮。它本质上是“一段经过结构化的指令集 素材文件”放在约定目录之后模型会在对话中按需读取并执行。你可以把它理解为给 AI 编程助手准备的“岗位说明书”。普通提示词模板只解决一次性问题而 Skills 解决的是“以后每次遇到同类任务模型都能自动按同一套专业流程干活”。举例来说你手动让模型做代码审查时可能要在对话里写一大段“请检查安全漏洞、关注边界条件、给出修改建议”之类的话。但如果你安装了一个 code-review 技能模型会在合适时机主动读取这份技能里的完整审查清单然后按清单逐项执行。输出质量会稳定很多因为规则是固定的模型发挥空间变小了。1.2 为什么是 OpenCode 而不是直接复制粘贴提示词这里有个很实际的原因。模型对话的上下文窗口是有限的你总不可能每次任务都粘贴一份五千字的专家提示词。而 Skills 的加载机制是“按需读取”平时只暴露技能名称和描述只有模型判断当前任务匹配时才把完整内容加进上下文。这样一来你的上下文里不会堆满无用指令模型反而能把注意力集中在真正的代码和任务上。这个设计思路是最近几款终端 AI 编程助手共同的方向OpenCode、Codex、Claude Code 都在往这个方向走。OpenCode 的差异化在于它不像 Codex 那样绑定某个固定厂商也不像 Claude Code 那样深度绑定 Anthropic 生态而是通过配置多个 provider 灵活切换模型。你可以在一次会话里用 Claude 处理复杂重构用 GPT 系列做快速问答或者接到走自建推理服务。Skills 相当于成了“模型无关的经验库”换模型不换技能工作流不会因为模型切换而重新适应。1.3 和 Agents 又有什么区别在 OpenCode 里还有 Agents 的概念很多人会把 Skills 和 Agents 搞混。我的理解是Agents 更像一个“有权限执行多步操作的角色”它可以调用工具、执行命令、独立完成任务而 Skills 是“知识/方法论”它本身不具备执行能力只是让模型知道“该按什么标准做事”。它们可以配合——某个 Agent 在执行任务时加载指定 Skills 来约束自己的决策方式。如果非要做个类比Skills 是公司的规章制度和操作手册Agents 是拿着手册去干活的员工。两者不冲突但定位完全不同。想快速上手的思路是先不用管 Agents先把 Skills 玩明白。因为 Skills 的安装和使用成本极低风险也可控——最多就是模型按一套固定逻辑干活不会像 Agents 那样可能误操作文件或执行命令。2. 装 OpenCode 最容易翻车的三件事Windows 环境、命令无效、启动方式2.1 安装路线选择Node 包管理器、Homebrew 还是直接下二进制OpenCode 的安装方式大体分为两类一是通过包管理器全局安装二是直接下载官方发布的可执行文件。我自己的环境是 Windows WSL2 混合使用两种方式都试过。如果你主力终端是 PowerShell 或 CMD且已经装了 Node.js那么用 Node 包管理器全局安装是最顺的路径。包名是opencode-ai命令是这样npm install -g opencode-ai安装完成后理论上在任意目录输入opencode就能进入交互界面。如果这一步报“无法识别”或“命令无效”不是工具本身的问题而是 Node 的全局 bin 目录没有加进系统 PATH后面我会专门讲排查方法。macOS 上我更推荐走 Homebrew 的形式因为后续升级更方便。Linux 服务器上则习惯用官方安装脚本或直接下载二进制包。没必要在这上面纠结核心是你最终能在终端里敲出opencode命令并且有响应。2.2 “cmd 使用 opencode 命令无效”的完整排查链这个报错我印象太深了。明明 npm 显示安装成功结果在 CMD 里输入opencode就是提示“不是内部或外部命令”。当时反复了几次才发现原因不是 OpenCode 装坏了而是 Windows 下 npm 全局目录的 PATH 配置问题。排查步骤建议按这个顺序先执行npm config get prefix确认 npm 全局安装路径在哪里。常见值是C:\Users\你的用户名\AppData\Roaming\npm。打开“系统环境变量”检查 Path 里有没有上面这个目录。如果没有把这个目录追加进去然后重新打开终端。CMD 不会自动更新已打开窗口的环境变量这一步特别容易漏。重新执行opencode --version有版本号就说明命令识别成功了。顺便说一句如果你是在 WSL2 里装的那 Windows 侧 CMD 当然识别不了因为那是两个不同的环境。很多人把 WSL2 和 Windows 原生环境混在一起排查越查越乱。最简单的做法是二选一要么全程在 Windows 终端用原生安装要么全程在 WSL2 里用 Linux 方式安装不要两边互认命令。2.3 Windows 下到底用什么 shell 工具最顺手搜索热词里很多人问“opencode 在 Windows 环境下什么 shell 工具好用”。我的建议是优先用 Windows Terminal别用裸 CMD。原因很现实。OpenCode 的界面是终端 UI需要比较完整的 ANSI 颜色支持和键盘快捷键响应。Windows Terminal 对 ANSI 转义序列的支持比传统 CMD 好得多显示效果和交互流畅度都上一个台阶。如果你平时用 PowerShell 比较多也可以直接在 Windows Terminal 里跑 PowerShell。个人体感PowerShell 7 配合 Windows Terminal 是 Windows 上最稳的组合命令提示符的老毛病最少。如果你有 WSL2也可以在 Windows Terminal 的下拉菜单里直接打开 Ubuntu 终端在 Linux 环境里跑 OpenCode。搜索热词里也有“win10 安装 WSL2 和 opencode”的说法并不是因为 OpenCode 必须在 WSL2 里跑而是因为很多人本来就在 WSL2 里做开发顺带把工具也装在那边了。WSL2 里跑的好处是文件路径和权限模型更贴近生产环境对后续执行 Shell 操作类 Skills 更有利但如果你只是想在 Windows 上体验一下不装 WSL2 也完全可以。2.4 安装后如何启动、首次认证怎么做启动其实就两步进入你的项目目录然后输入opencode。它会扫描当前目录下的上下文文件加载配置然后进入交互式对话界面。如果当前目录不存在配置文件它也能正常启动只是部分项目级 Skills 和 Agent 配置不会生效。第一次启动后通常要配置模型访问。方法有两条一是用交互式命令登录对应平台的账号让密钥存进本机钥匙串二是直接设置环境变量。我的做法偏向环境变量因为脚本化部署方便也不会把密钥写进项目代码里。假如你开通了 opencode go 这类订阅套餐把套餐的 key 配置好之后就能直接调用套餐内模型。注意一点套餐里如果包含免费额度官方错误提示也写得很清楚——opencodes free tier can only be used from within opencode。意思是这种免费额度模型只能在 OpenCode 自己的会话内部调用不能把它当成通用接口拿到其他客户端去用。看到这个报错不用怀疑配置问题换用自己的 key 或者直接在 OpenCode 会话里使用即可。3. Skills 从哪里找官方渠道、社区合集与筛选标准3.1 找技能的典型渠道先说最常见的渠道。一是 OpenCode 官方文档和官方仓库里推荐的技能列表。二是 GitHub 上直接搜“opencode skills”或“SKILL.md”能翻到大量个人和团队开源的技能包。三是社区整理的合集仓库这类通常把几十个常用技能打包方便一次性体验。搜索热词里出现过不少具体名字比如 superpower skills、nature skills、workbuddy skills、cola skills 之类。这些大多来自社区项目有些是某位开发者把自己长期使用的提示词工程化之后分享出来的。本质上它们都是“SKILL.md 文件 资源目录”的组合。下载方式也直接git clone 下来或者下载 zip 解压放到指定目录就行。我不建议一口气装几十个技能。技能不是装得越多越好因为模型每次判断“该不该加载这个技能”时靠的是技能的 name 和 description。如果描述写得含糊模型可能会错误地把不相关技能加载进上下文白白占用 token。所以最好只保留与自己工作流强相关的 5 到 10 个。3.2 如何判断一个技能值不值得用对社区技能要做基本背调。我一般看四点目录结构是否完整有没有 SKILL.md还是只丢了一段 prompt。描述是否具体好的技能描述会写清“何时触发、解决什么问题、大概怎么做”而不是空泛地说“帮助写代码”。维护时间看最近一次提交是什么时候。太老且长期不更新的技能往往对当前主流模型的指令遵循能力适配不佳。有无引用外部脚本如果技能目录里带脚本注意看脚本是否安全。Skills 本身是一段文本模型不会执行你电脑上的任何东西但如果技能说明让模型“调用某个脚本”那你下载这个脚本时就要审一眼代码。3.3 技能分类哪些领域最成熟从社区已有积累来看比较成熟的技能领域包括代码审查、提交信息规范、前端组件开发、单元测试生成、日志分析、数据库迁移脚本编写、文档结构整理、安全审计等。前端开发 skills 尤其多因为前端任务的模式和规则非常稳定很适合作成技能——模型只要按规范输出 JSX、Tailwind 类名或 CSS 方案就行。搜索热词里还出现了“安卓脱壳 skills”这类逆向相关技能。这类技能主要面向授权范围内的安全测试和样本分析适用范围比较窄。如果你不是专门做移动安全评估的没必要碰因为对基础能力要求很高翻车概率也大。写作类 skills 也很多但我的态度是用来整理格式、规范目录、改善排版可以不能把学术或正式场合的产出完全交给 AI那是本末倒置。4. 添加 Skill 的完整动作目录规划、刷新机制与生效验证4.1 技能目录的摆放规则OpenCode 加载 Skills 的规则遵循目录约定用一段话总结就是把技能文件夹放到约定目录下文件夹名字就是技能名里面必须有 SKILL.md 作为入口。具体路径上项目级技能通常放在当前项目的.opencode/skills/目录下只对当前项目生效用户级技能通常放在全局配置目录下例如~/.config/opencode/skills/对所有项目生效。我这里用了“通常”因为不同版本对路径的支持可能有细微差别强烈建议你启动 OpenCode 后看一下内置帮助里关于 skills 的说明或者直接看官方文档确认当前版本的目录要求。实际操作时技能目录的结构是这样.opencode/skills/ └── code-review/ ├── SKILL.md ├── checklist.md └── examples/ └── bad_code.pySKILL.md 是核心其他文件都是辅助素材。模型加载技能时SKILL.md 里的内容会被完整读进上下文里面可以写明“要参考checklist.md中的检查项”或“阅读examples下的示例”。4.2 添加技能的标准流程以安装一个从 GitHub 下载的 code-review 技能为例# 进入项目目录 cd my-project # 创建项目级技能目录 mkdir -p .opencode/skills # 将技能文件夹复制进来 cp -r ~/Downloads/code-review .opencode/skills/复制完成之后重启 OpenCode 会话或者用对话界面里的刷新命令重新加载技能列表。有些版本支持热加载但保险起见重启一次最稳妥。重启后我们怎么知道技能有没有被识别打开会话直接输入“请使用 code-review 技能审查当前分支的改动”如果模型能准确说出“正在按 code-review 技能的规则执行”并给出技能里定义的检查项结构说明加载成功。如果模型完全没反应或者压根不承认有技能先回去检查目录层级。很常见的错误是把技能文件夹嵌套错了比如.opencode/skills/code-review/SKILL.md变成了.opencode/skills/code-review/code-review/SKILL.md这时候模型找不到入口文件自然识别不了。4.3 生效机制的原理为什么模型能主动找到技能这个问题很多人问。道理其实简单OpenCode 在构建系统提示时会把所有可用技能的“名称和描述”附加进系统上下文中而技能的完整正文不会全部加载。当你发出请求后模型扫描这些名称和描述发现某个技能与当前任务高度相关才触发加载动作把对应的 SKILL.md 内容完整纳入上下文。所以你在写技能描述时一定不能含糊。描述越准确模型越容易在正确时机触发技能。反过来如果描述乱写模型要么永远不触发要么在无关任务里乱触发两者都很影响效率。另外有个小经验会话中如果明确提到技能名模型触发概率会高很多。比如你说“用 commit-message 技能帮我生成提交信息”这属于显式指令模型基本一定会去读技能内容。如果只说“帮我提交一下”模型需要自行判断是否匹配就存在不触发的可能。4.4 项目级还是用户级如何选择我的建议是通用性强的技能放用户级比如提交信息规范、代码审查、日志排查和特定项目强绑定的技能放项目级比如某个项目的架构规范、数据库表结构说明、特有的命名约定。这样换项目时通用技能仍在项目特有技能也不会污染其他项目的上下文。项目级技能还有个隐藏好处可以随仓库提交团队所有人都能用。如果你们的团队想统一代码审查标准或提交信息规范把对应技能放进项目仓库并写入 README让成员 clone 后直接就能享受一致规则。这比在群里发提示词让每个人自己粘贴高效得多。5. 手写一个 SkillSKILL.md 的结构、规则和最简可运行案例5.1 理解 SKILL.md 的 Frontmatter 与正文自己写技能并不难难的是写好。SKILL.md 本质是 Markdown 文件头部有一段 YAML 格式的元信息正文是给模型看的完整指令。最小的文件大概长这样--- name: commit-message description: 根据当前仓库的 git 改动生成符合 Conventional Commits 规范的提交信息。当用户要求生成提交信息或准备 git commit 时使用。 --- 你是一个 Git 提交信息助手。请按以下步骤工作。 1. 运行 git status 和 git diff --stat了解改动范围。 2. 分析变更类型按 Conventional Commits 规范判断属于 feat、fix、refactor、docs、test、chore 中的哪一类。 3. 输出格式为 type(scope): subject。 4. 如果存在多个不相关的改动拆分多条提交信息。写好之后保存为.opencode/skills/commit-message/SKILL.md重启 OpenCode 就能测试。5.2 描述字段是技能触发的关键name 字段是技能的标识description 字段承担着“触发判断”的重任。我给个对比如果你写的是“帮助生成提交信息”模型可能在任何涉及代码的对话里都犹豫要不要加载如果你写的是“当用户准备提交代码或询问提交信息时使用利用 git 状态与 diff 生成规范格式的提交信息”模型就能更精准地判断。写 description 的原则可以这样记包含触发场景、包含可见任务信号、说明期望输出。触发场景就是“什么时候用”可见信号就是用户请求里的关键词期望输出就是“模型要产出什么东西”。5.3 让技能可以调用外部工具和脚本并不是所有技能都需要“说话”就行。有些任务需要模型执行命令、分析文件这时候你可以在技能正文里明确命令的操作方式。比如一个代码审查技能可以这样写先运行git diff获取当前改动再运行git diff --check检查空白错误最后按检查清单逐项审阅。模型看到这些指令后会自行调用终端工具执行然后把结果用于分析。注意这里有个安全点技能是文本指令模型判断“要不要执行命令”是根据工具权限来的。不要让技能总想着执行高危命令比如删除文件、覆盖配置、强推分支。写技能的人本人也应当克制不要在指令里引导模型做破坏性操作。推荐的技能目录里可以放一些静态资源文件比如examples/文件夹放“好的写法”和“坏的写法”对比模型会更容易理解审查标准。也可以放checklist.md把检查项拆成长列表SKILL.md 正文里写“请严格按 checklist.md 里每一项执行”。这样职责分离正文简洁细节资源可控。5.4 一个带资源目录的最小案例假设我们要做一个小型前端代码审查技能目录结构为.opencode/skills/frontend-review/ ├── SKILL.md └── checklist.mdSKILL.md 内容--- name: frontend-review description: 审查前端项目的 React 组件代码检查组件拆分的合理性、状态管理使用是否得当、样式方案是否一致。当用户要求审查组件代码或前端改动时使用。 --- 请参考 checklist.md 中的审查清单对用户提供的代码进行逐项审查。 审查输出格式 - 问题严重程度分级严重 / 建议 / 可选 - 每个问题给出文件路径与对应代码位置 - 修复建议要具体到改动方向 - 如果无问题明确写出“未发现明显问题”不要强行凑数checklist.md 内容# 前端组件审查清单 1. 组件是否违反了单一职责原则能否进一步拆分 2. 是否使用受控组件处理表单输入 3. 组件内部是否存在不必要的重复渲染memo 使用是否合理 4. 样式是否与项目设计系统保持一致 5. 是否正确处理加载态、空态和错误态 6. props 命名是否清晰默认值是否合理 7. 是否残留 console.log 或调试代码 8. 是否有未使用的依赖和死代码这样写完如果用户把一段 React 组件贴给模型模型就能准确调用这个技能按清单一条条审查。这种“目录 清单”的写法非常推荐用于有一定复杂度的技能。5.5 写技能时的经验教训写了不少技能之后我有几个很深的体会。一是别写“万能技能”一个技能解决一个核心问题就好功能多了反而触发混乱。二是指令要尽量具体避免“请分析代码中的问题”这种模糊说法要写明分析的维度、输出的格式、优先级标记等。三是技巧类描述不要写得过于依赖某个特定模型的能力要假设你的模型可能并不擅长超长代码推理把任务拆小、把步骤写清模型才跟得上。还有一点容易被忽略技能内嵌的 examples 要给出“理想输出”而不是随便给个例子。模型的 few-shot 学习能力很强你给什么样的例子它就倾向于输出什么样的风格。如果例子混乱最终输出会被带偏。6. 把 Skills 用进真实开发流前端、文档、IDE 协同6.1 前端开发场景怎么组合使用搜索热词里“前端开发 skills”热度很高确实前端是 Skills 最适合发挥的场景。因为前端工作通常有明确规范和大量重复模式。比如组件开发的流程是“需求理解 → 组件结构设计 → 样式实现 → 状态管理 → 交互细节 → 测试”每一步其实都可以用技能约束。我自己的习惯是给前端项目配置三个技能。一个是组件生成技能要求模型按团队的目录结构、命名规范、样式方案输出组件一个是代码审查技能用来在 MR 前自查一个是变更说明技能自动把前端改动整理成适合写 release note 的内容。三个技能各管一摊互不干扰配合起来刚好覆盖从编码到上线的核心链路。如果你想让技能特别贴合自家团队规范别用网上的通用技能自己写一个成本并不高。把团队约定搬进 SKILL.md比让模型“猜”规范要可靠得多。团队规范这种东西靠口头传达经常丢失做成技能文件放进项目仓库反而成了长效文档。6.2 写作与文档场景的边界热词里有“codex 写论文的 skills”和“workbuddy skills 写论文”这些都指向文档和写作技能。合理的用法是让技能负责格式规范、目录结构、引用格式、语言修改这类“体力活”。比如论文排版、参考文献格式统一、章节结构检查、会议纪要整理这些都很适合做成技能。要谨慎的是不要把核心的“研究、思考、结论形成”完全交给模型。技能本身只是工具触发它的人还是要对产出负责。在实际落地时我更推荐用技能做 drafting 和 editing 而不是 thinking也就是让模型帮你打草稿、做规范化修改但观点的形成和材料的甄别必须在你自己手里。这样既提高了效率也保持了产出的可信度。6.3 在 IDE 里怎么配合使用搜索热词里也有“opencode ide 怎么添加 api key”和“idea 使用 skills”。使用终端型编程助手和 IDE 并不冲突。最简单的方式是在 IDE 内置终端里直接跑 OpenCode项目目录保持一致这样技能、Agent、上下文都能直接生效。如果你是 VS Code 用户可以在终端面板里开一个 PowerShell 或 WSL 窗口输入 opencode 开启会话。体验上编辑代码在 IDE 窗口对话与批量操作在终端面板两边并排效率很高。如果你希望在 IDE 的 AI 助手面板里使用 OpenCode 的能力很多 IDE 的 AI 插件支持自定义 provider把 endpoint 指向 OpenCode 的服务、填上 key就能在面板里调用。不过我的实际体会是大多数时候直接开终端更省心因为 OpenCode 的 TUI 交互对长任务、多文件上下文处理得更自然IDE 面板更适合短问答和补全两者形态不同没必要硬融合。6.4 多技能协作时的上下文管理当项目里有多个技能同时存在要特别留意上下文占用。模型不会同时加载所有技能但它会在初始系统提示中看到全部技能的 name 和 description这部分有一定 token 开销。技能越多这个开销越大留给实际任务的空间就越小。所以定期清理闲置技能是好习惯。每过一段时间我会审视一下这个技能过去两周用过吗没有就注释掉或挪出目录让系统提示保持精简。有些技能一段时间不用再放回来成本也很低没必要常年堆在目录里。另一个技巧是让技能文档本身“小而精”。SKILL.md 正文控制在几百行以内需要扩展细节时放进 auxiliary 文件。模型只有在触发技能时才会读取完整内容所以正文过长也不会全局拖慢但太长的正文在真正加载时会消耗整段上下文反而挤占对话空间建议控制在合理范围。7. 高频报错处理免费额度限制、命令无效、兼容推理与加载失败7.1 免费额度报错别再怀疑你的网络或配置这应该是这段时间出现频率最高的报错之一。错误信息的核心是opencodes free tier can only be used from within opencode。翻译成人话就是——免费套餐提供的模型只能在 OpenCode 自带的会话环境里调用不允许被外部工具当作通用接口使用。常见触发场景有三种第一种你在 IDE 的 AI 插件里配置了 OpenCode 的 provider然后尝试调用免费套餐模型被拒第二种你用脚本或命令行工具模拟请求调用了包在套餐里的免费模型被拒第三种你在 OpenCode 里配置了多个 provider某次切换不小心把请求发到免费套餐模型的端口上被拒。解决办法很简单如果你想在外部工具里用就配置自己的独立 key别依赖免费套餐额度。如果你想用免费套餐就把任务留在 OpenCode 会话里完成。这不是配置错误也不是网络问题是授权边界决定的功能限制。7.2 命令无效与 SHELL 选择前面已经讲了一部分。这里再补充一个容易误判的情况如果你在 WSL2 里执行opencode正常但回到 Windows PowerShell 再执行同一个命令却无效那是因为两个环境的安装目录和 PATH 互相独立。解决办法是在你真正要用的那个 shell 环境里单独执行一次安装并在对应环境检查opencode --version。此外Windows 下选 Shell 的优先级建议是 Windows Terminal PowerShell 7 优先Windows Terminal WSL2 bash 次之纯 CMD 最不推荐。CMD 对终端 UI 应用的支持确实差一些容易出现界面渲染错乱、快捷键失效之类的“看起来像工具坏了”的问题。7.3 兼容推理配置时遇到模型连接失败热词里有“opencode 设置 兼容推理”多数人是在配置第三方推理服务时遇到问题。OpenCode 支持接入各类兼容接口比如 OpenAI 兼容格式或 Anthropic 兼容格式的服务。配置时需要关注三个点服务地址、模型名、请求格式。如果你的服务商说明自己是 OpenAI 兼容那么 baseURL 应该指向其兼容端点模型名要填服务商提供的模型标识请求的认证信息按服务商要求填。如果服务商只支持 Anthropic 格式那要切换到对应的配置入口不能混用两套请求结构。报 400 错误或返回格式解析失败时首先排查的就是“格式是否与服务商的兼容类型一致”。我见过不少人把 OpenAI 兼容端点填进 Anthropic 兼容配置里报错后完全摸不着头脑其实只是格式串了。还有一种情况是你自建了聚合服务把多个模型转发成统一接口那么在 OpenCode 里配置时同样要注意该聚合服务到底暴露的是哪种兼容协议尽量保持协议单一不要今天用这个明天换那个。7.4 技能加载失败时怎么定位技能添加了但模型“看不见”这是新手最常遇到的问题。定位思路按顺序走确认目录位置正确。项目级技能要放在.opencode/skills/之下用户级技能要放在全局配置目录的skills/子目录下。确认文件名正确。入口文件名必须是SKILL.md大小写不能错。确认 YAML frontmatter 能解析。name 和 description 缺一不可格式错误会导致整份技能不可读。重启会话并刷新技能列表。如果界面里有技能管理入口直接在入口中查看已识别技能。如果还是没有打开日志输出看有没有加载失败的路径提示。日志是最诚实的朋友。一个容易忽略的点是技能文件夹名最好和 name 字段保持一致或者至少完全对应不要出现文件夹叫code-review-v2、name 却写reviewer的情况。模型可以识别但你自己维护时容易混乱。命名一致能减少大量不必要的排查时间。7.5 错误信息的通用处理习惯和 OpenCode 打交道多了会发现它的大多数报错其实都很“直球”。你只需要分清楚是认证问题、配置问题、网络问题还是权限边界问题。认证问题看 key 是否有效配置问题看 baseURL、模型名、兼容格式网络问题看能不能正常访问服务地址权限边界问题就是刚才说的免费额度场景。把报错信息完整读一遍多数时候答案已经在里面了不要急着去问别人。最后再分享一个我自己的使用习惯。技能目录我通常会在 Git 仓库里单独留一份但不是直接全部提交而是拆成“公开通用”和“团队私有”两部分。公开通用技能放仓库供大家 clone团队私有技能写进.gitignore只通过内部渠道分发。这样既保证了新成员能快速获得基础能力又不至于把带内部规范细节的指令集暴露到不必要的地方。你在实际使用 OpenCode 时也可以按这个思路规划自己的技能管理方式能少踩很多麻烦。