1. 为什么你的 OpenCode 里 Skills 总是加载不出来很多人第一次在 OpenCode 里折腾 Skills卡住的地方往往不是写 SKILL.md而是环境本身没跑通。我见过太多情况终端里敲了opencode能进界面但一问「我有哪些 skills」模型回答得含糊其辞或者干脆说没有可用技能。这时候你会怀疑是不是模型太笨其实大概率是目录放错了、SKILL.md 的 frontmatter 写歪了或者 OpenCode 根本没扫描到你放技能的那个路径。OpenCode 是一个跑在终端里的 AI 编程智能体它最大的特点是模型无关、开源、项目级理解。你可以把它理解成「终端里的 AI 搭档」它读你的整个项目目录能分析依赖、能改代码、能跑脚本。而 Skills 是它扩展能力的方式本质上是把「一套专业流程 可执行脚本 参考模板」打包成一个可复用的模块。当任务匹配到某个 Skill 的触发条件时OpenCode 才会把对应的 SKILL.md 正文加载进上下文按里面写的步骤去执行。这套机制对想用 AI 智能体完成真实开发任务的工程师特别有用。比如你团队里有一套固定的「生成接口文档」「跑数据清洗脚本」「按规范提交 PR」的流程以前每次都要重新写一大段提示词现在固化成一个 Skill谁都能调用输出还稳定。适合谁适合已经在用 OpenCode 或准备用它做项目实战的人尤其是那些被重复性提示词折磨过、想让 Agent 真正落地干活的开发者。这篇内容我会按「环境搭建 → 配置模型 → 写 Skill → 端到端验证 → 排错」的顺序走一遍每一步都给可复制的命令和配置。你跟着做最后能拿到一个能自动生成文章并写入指定目录的 Skill整个链路是通的。2. OpenCode 环境搭建与模型接入前置准备先把地基打好。OpenCode 依赖 Node.js版本要求 18 以上强烈建议用 20 LTS。Windows 上直接去 Node.js 官网下安装包一路下一步就行。装完打开 CMD 验证node -v npm -v两条命令都能输出版本号说明 Node 环境没问题。接着全局安装 OpenCodenpm i -g opencode-ai opencode --version如果opencode --version能打印出版本安装就成功了。安装完成后本地用户目录下会出现 opencode 的配置目录Windows 一般在C:\Users\你的用户名\.opencode或类似路径后面放 Skills 会用到。新建一个空文件夹作为项目目录切进去直接运行mkdir D:\work\opencode-demo cd /d D:\work\opencode-demo opencode进入终端界面后先打个招呼测试内置模型能不能响应。OpenCode 自带几个免费模型能回话说明基础环境通了。但内置模型效果通常一般做真实项目实战还是得接自己的模型。这里就要说到模型接入。OpenCode 支持 75 种以上的模型你可以接云端也可以接本地。我实测下来用 TaoToken 这类聚合入口会比较省事它把多家模型的调用统一成一个 Base URL 和 KeyOpenCode 里配置一次就能切换不同模型。具体来说你需要准备三样东西Base URL、API Key、Model ID。这三件套在 OpenCode 的模型配置里是核心缺一不可。获取 Key 的入口在 TaoToken 的 API Keys 页面登录后创建一个就行。文档里对 OpenCode 的接入方式有说明照着填即可。注意 Base URL 用https://taotoken.net/api不要带多余路径。Model ID 要写你实际要用的模型标识比如glm-4.7或deepseek-v3这类写错了会报模型不存在的错。配置模型有两种方式一种是在 OpenCode 界面里输入/connect选提供商后粘贴 Key另一种是直接改配置文件。界面方式适合快速试配置文件方式适合团队统一。我建议两种都掌握因为后面排查问题时你会需要看配置文件到底写了什么。3. OpenCode Skills 目录结构与配置文件可复制模板Skills 能不能被识别九成取决于目录结构和 SKILL.md 的写法。先记住一个标准结构my-skill/ ├── SKILL.md # 唯一必需文件全大写 ├── scripts/ # 可执行脚本Python/Bash 都行 │ └── generate.py ├── refs/ # 参考模板、示例 │ └── template.md └── README.md # 人类可读说明非必需SKILL.md 是核心它由 YAML frontmatter 和正文两部分组成。frontmatter 里name和description最关键OpenCode 靠 description 判断要不要调用这个 Skill。下面是一个可直接复制的模板--- name: article-writer description: - 自动生成指定主题的文章并写入本地目录。 触发关键词写文章、生成文章、输出到目录 trigger_keywords: - 写文章 - 生成文章 - 输出到目录 version: 1.0 --- 你现在是一名资深技术编辑请按以下规则生成内容 ## 核心原则 - 开头用一句话点明主题 - 正文分 3 到 5 个小节每节有明确小标题 - 结尾给出可执行的下一步建议 ## 输出格式 1. 标题 2. 正文1000 字以内 3. 写入用户指定的本地目录 ## 执行步骤 1. 解析用户给出的主题和目标目录 2. 生成文章内容 3. 调用 scripts/write_file.py 将内容写入目标目录注意description里的触发关键词要和用户实际会说的话对齐。如果你写的是「生成文章」用户说「写一篇」就可能匹配不上。我踩过的坑就是关键词写太窄结果 Skill 明明在目录里模型却不去调用。目录放哪里OpenCode 会扫描项目目录下的.opencode/skills/或者用户全局目录下的 skills 文件夹。稳妥做法是在项目根目录建.opencode/skills/把每个 Skill 作为一个子目录放进去D:\work\opencode-demo\ └── .opencode\ └── skills\ └── article-writer\ ├── SKILL.md └── scripts\ └── write_file.pywrite_file.py可以很简单接收内容和路径两个参数写文件即可import sys def main(): content sys.argv[1] target sys.argv[2] with open(target, w, encodingutf-8) as f: f.write(content) print(fwritten to {target}) if __name__ __main__: main()如果你用的是 Claude Code 或 Cline 这类工具配置逻辑类似但文件位置不同。Claude Code 的配置在~/.claude/settings.jsonCline 的 MCP 配置在cline_mcp_settings.jsonCodex 的认证在auth.json。不管哪个工具Base URL、Key、Model ID 这三件套都要写全少一个就连不上。OpenCode 这边模型配置和 Skills 配置是分开的别混在一起写。4. 端到端验证让 Skill 自动生成文章并写入目录配置写完必须验证。验证分两步先确认 OpenCode 能识别到 Skill再确认 Skill 能真正执行并产出结果。第一步重启 OpenCode在对话框输入我有哪些 skills如果配置正确模型会列出你放在.opencode/skills/下的所有 Skill 名称和描述。如果它说没有先别急着改 SKILL.md去检查目录层级是不是多了一层或少了一层。常见错误是把 Skill 目录直接放在项目根目录而不是.opencode/skills/下面。第二步发一个真实任务写一篇 2026 年新能源发展趋势的文章1000 字以内最后放到 D:\work\opencode-demo\output注意目标目录要提前建好否则脚本写入会失败。执行过程中OpenCode 会先匹配到article-writer这个 Skill加载 SKILL.md 正文然后按里面写的步骤生成内容最后调用write_file.py写入文件。执行完成后去D:\work\opencode-demo\output看应该有一个.md或.txt文件打开内容就是生成的文章。这一步能跑通说明整条链路是通的环境 → 模型 → Skill 识别 → 脚本执行 → 文件产出。如果中间任何一环断了下一节对照报错排查。再补充一个验证技巧你可以故意把目标目录写成一个不存在的路径看 Skill 会不会报错。如果它静默失败说明脚本里没有做异常处理实际项目里要加上目录存在性检查。这种边界测试能帮你提前发现坑。5. OpenCode Skills 常见报错与排查清单这一节按真实报错来。你在 OpenCode 里折腾 Skills大概率会遇到下面几类问题。报错一401 Unauthorized。这是模型接入层的问题不是 Skills 的问题。说明你的 API Key 无效或过期或者 Base URL 写错了。检查三件套Base URL 是不是https://taotoken.net/apiKey 有没有多余空格Model ID 是不是当前账号有权限的模型。改完配置后重启 OpenCode 再试。报错二local proxy failed。这个通常出现在你配置了本地代理或自定义端点时。OpenCode 尝试连接你写的地址失败。先确认地址能不能在浏览器或 curl 里通再确认端口没被占用。如果你用的是聚合入口Base URL 不要自己加/v1之类的后缀按文档给的写。报错三reading choices 相关错误。这多半是模型返回格式和 OpenCode 预期不一致。常见原因是 Model ID 写成了不兼容的模型或者该模型不支持 OpenCode 需要的调用格式。换一个明确支持的模型 ID 再试比如 GLM 系列或 DeepSeek 系列。报错四OAuth 相关提示。如果你在配置里选了需要 OAuth 的提供商但没完成授权流程就会卡住。这种情况要么走完 OAuth要么改用 API Key 方式接入。OpenCode 里/connect选提供商时看清楚是 Key 还是 OAuth。报错五Skill 不触发。目录对、SKILL.md 也在但模型就是不调用。九成是 description 里的触发关键词和你的提问不匹配。解决办法是把用户可能说的各种说法都列进 trigger_keywords或者直接在提问里带上关键词。另外检查 SKILL.md 的 frontmatter 有没有 YAML 语法错误比如冒号后面没空格、缩进用了 Tab。报错六脚本执行失败。Skill 触发了但write_file.py报错。先确认 Python 在 PATH 里再确认脚本参数顺序和 SKILL.md 里写的一致。Windows 上路径反斜杠要转义或者统一用正斜杠。目标目录不存在也会失败脚本里加os.makedirs(os.path.dirname(target), exist_okTrue)能避免。排查顺序建议先看模型通不通发个普通问题再看 Skill 识不识别问「我有哪些 skills」最后看脚本能不能跑手动执行一次脚本。逐层缩小范围比一上来就改 SKILL.md 高效得多。6. 把 Skills 用进真实项目从单文件到工作流单次生成文章只是演示。真实项目里Skills 的价值在于把多步骤流程固化下来。比如你可以写一个api-doc-writerSkill步骤是读项目里的路由文件 → 提取接口定义 → 生成 Markdown 文档 → 写入docs/目录。整个过程不需要你每次重新描述。再进一步你可以把多个 Skill 组合成工作流。OpenCode 支持在一个会话里连续调用不同 Skill前一个的输出作为后一个的输入。比如先跑code-reviewer找出问题再跑patch-writer生成修复补丁。这种组合在长期编码和 Agent 场景里特别省时间。如果你打算长期用 OpenCode 做开发建议把模型接入和 Skills 管理都固定下来。模型这边用 Coding Plan 这类方案能覆盖日常编码和 Agent 调用不用每次单独配 Key。Skills 这边团队里谁写了好用的 Skill直接提交到项目的.opencode/skills/目录其他人拉下来就能用相当于把个人经验变成了团队资产。最后给一个实用建议每写完一个 Skill先手动跑一遍它依赖的脚本确认脚本本身没问题再放进 OpenCode 里测。脚本层的 bug 和 Skill 配置层的 bug 混在一起时排查会非常痛苦。分开验证能省你很多时间。