Agent Skills 最近在开发者社区里出现频率很高尤其是当你用过 Claude Code会发现“技能Skill”这条设计思路很实用它把经常要重复交代给 Agent 的背景知识、操作步骤和输出格式打包成一整套可复用的文件。OpenCode 是很多人拿来学习 Agent Skills 的 Claude Code 开源替代能跑在本地、能切换不同模型也方便把技能目录直接放进项目仓库。我把从零到项目实战的整个流程拆开讲一遍先解释 Skills 到底是什么、与 Prompt 和 Agent 有什么区别然后走一遍 OpenCode 的安装、模型配置和常见报错接着用代码评审 Skill 和一个论文写作辅助 Skill 做两份完整示例最后补上适合你的排查顺序和落地建议。适合两类读者一类是刚接触 Agent Skills、还不清楚怎么组织技能文件的人另一类是你已经有 API 条件想用一个更透明、更容易改配置的开源方案把日常任务流程固化下来。1. Agent Skills 到底解决什么问题和 Agent 有什么区别1.1 从“反复写提示词”到“给 Agent 配岗位说明”最早我们用 Prompt 模板的时候最大的痛点是每次都要重复交代背景。比如做代码评审你可能会写“你是一个资深工程师请从安全、性能、可读性三个角度评审下面这段代码输出顺序是问题列表、风险等级、修改建议”。这句话每次都要写而且不同项目的评审规范还不一样。项目一多Prompt 文件会越来越长复制粘贴很容易漏。Agent 出现以后这个问题得到一部分缓解。Agent 可以调用工具、可以访问仓库文件、可以自主完成多步操作但它仍然需要“知道自己是什么角色、按什么流程干活”。如果你每次都在会话里手工输入Agent 的执行质量就取决于你输入的质量换个人用结果可能完全不一样。Agent Skills 要解决的就是这件事。它把一个岗位需要的“背景知识 操作流程 输出格式 配套脚本或模板”打包成一个独立目录。目录里最关键的文件一般叫 SKILL.md里面写清楚这个技能的名称、描述、触发条件和操作步骤。模型在对话时可以根据描述自行判断“当前任务应不应该加载这个技能”加载后按里面的流程执行。这带来的直接好处是你不用在每次任务里重复解释规则。技能文件可以跟着项目仓库走也可以放在个人配置目录里谁用都能复用同一套标准。更关键的是技能可以做版本管理。你改了某个判断标准Git 历史里能看见团队成员也能知道变化原因。1.2 Skill、Prompt、Agent 的关系很多人把这三者混在一起其实可以这样区分Prompt是一次性指令解决的问题是“这次任务怎么干”。Skill是结构化的知识资产解决的问题是“一类任务长期怎么干”。Agent是运行时主体负责把模型、工具、记忆和技能组合起来完成目标。用表格看更直接维度PromptSkillAgent本质一次性指令文本可复用的技能包执行任务的运行时生命周期会话内有效可以长期保存、版本化随进程启动和结束复用性低通常需要重写高团队可共享中等依赖配置典型产物一段文字目录 SKILL.md 脚本一个可交互的进程一个容易混淆的说法是“AI Skills 和 Agent 的区别”。Skill 是“会做什么”Agent 是“实际去做的系统”。你可以在同一个 Agent 上挂多个 Skill也可以让同一个 Skill 被多个 Agent 复用。实践中Skill 更像标准作业程序Agent 更像是执行这套程序的人。理解了这层关系你就明白为什么 Skill 是值得认真设计的。它不是一段提示词的别名而是一份可以被持续维护的“岗位操作手册”。1.3 哪些任务适合做成 Skill不是所有任务都适合。适合的场景通常有三个特征任务类型重复比如每个迭代都要做代码评审。步骤和规范相对固定比如论文写作里的文献整理、大纲生成、润色检查。输出格式有要求比如必须返回 Markdown 表格、必须带问题等级。如果一个任务每次都不一样或者高度依赖临时灵感那直接写 Prompt 就行不必封装成 Skill。如果你打算把某个 Skill 放进项目仓库还要考虑它是否包含敏感信息特别是指令里不要写死密钥。2. 为什么我推荐先拿 OpenCode 跑 Agent Skills而不是直接上 Claude Code2.1 开源替代解决了什么Claude Code 做得很成熟但它在模型绑定、配置文件和使用环境上都有较强的自身约束。OpenCode 这类开源替代被大家关注主要有几个原因本地配置更透明你能直接看到模型、API 地址和配置文件。模型可以切换既可以用官方接口也可以接第三方 API 或本地模型。技能目录、项目配置都能放进仓库方便团队复用和记录变更。对个人学习和二次开发更友好出了问题能看日志、看代码。这里要说明OpenCode 不是 Claude Code 的完整替身很多功能和生态仍在变化。标题里说“开源替代”我理解指的是同一个使用场景下的可替代方案而不是每一处功能都完全一致。落地前最好先把你最依赖的功能列出来逐项验证。2.2 什么场景用 OpenCode 更合适我建议分场景判断学习 Agent Skills很合适。你不需要在模型和平台绑定上花太多成本可以先在一个开源工具里把技能目录、描述文件、加载逻辑跑通。企业内部做规范流程合适。SKILL.md 可以放在仓库里走代码评审谁改了什么一目了然。需要官方企业级支持要谨慎。开源工具在权限体系、审计、服务保障等方面不一定能满足企业要求。追求一键安装、完整桌面体验要评估。开源工具的桌面端、IDE 插件和成熟商业产品相比完成度有差异。从成本角度看开源方案更适合低频、多模型、需要内网隔离的场景。比如你想让同一个技能分别对接不同模型看看哪个输出更稳定这种试验用 OpenCode 就更方便因为它把 provider 和 model 暴露在了配置里。2.3 先做最小化验证别被功能列表带偏很多读者会问OpenCode 和 Claude Code 到底哪个强我的建议是先别比功能列表。先选一个你觉得安装成本最低的工具用最小任务跑通一遍启动会话、让模型处理一个简单请求、查看日志和输出。功能列表再长不能在你的机器上稳定运行也是白搭。OpenCode 这类项目通常也会公开源码。如果你想知道它到底怎么加载技能、怎么路由模型可以直接读源码。读源码时先看三个方向入口文件、命令路由、技能加载逻辑。比到处搜二手教程更可靠。3. 从零安装 OpenCode环境、命令和 Windows 常见报错3.1 先确认你有没有 Node.jsOpenCode 这类 CLI 工具常见安装方式依赖 Node.js 和 npm。不同发行版对版本要求不同但第一步基本都是先确认 Node 版本。node -v npm -v如果命令不存在需要先安装 Node.js。安装完成后重新打开终端再执行上面的命令。这一步尽量别跳过很多“安装失败”其实是因为 Node 版本太旧或者 npm 源在拉取时超时。我需要提醒一下不要在一台机器上同时装多个大版本 Node除非你用了版本管理工具。否则后续很多依赖冲突会很难查。3.2 安装与验证的通用流程以官方 README 为准通用安装思路如下。这里我把包名用占位符表示因为你下载到的项目版本可能不同命令也可能从全局安装变成 npx 执行。# 示例安装命令具体以官方 README 对应的包名为准 npm install -g opencode-包名 # 验证是否安装成功 opencode --version如果安装成功再启动一次终端界面确认能正常进入会话。如果 npm 安装不奏效可以看官方文档里有没有提供别的方式比如 Homebrew、二进制包、源码构建。源码构建一般需要克隆仓库后安装依赖、编译适合想读代码的人。低配置机器上跑源码构建可能慢但只要能编译成功后续调试会比较自由。3.3 Windows 下最常见的报错“无法将 opencode 项识别为 cmdlet、函数、脚本文件或可运行程序的名”这个报错在 Windows PowerShell 下非常常见。字面意思很直白系统在当前环境下找不到 opencode 这个命令。背后原因通常有三个安装本身没成功npm 报错或者进度中断。安装成功了但 npm 的全局 bin 目录没有加到 PATH 里。PowerShell 执行策略不允许运行脚本。排查顺序1. 重新执行安装命令观察有没有报错。 2. 执行 npm prefix -g看全局安装目录在哪里。 3. 把全局 bin 目录加入 PATH然后重开终端。 4. 如果还不行检查 PowerShell 执行策略并确认是否用了普通命令行窗口。如果只是临时想验证下载的包能不能运行也可以用 npx 方式直接执行包名。但正式项目建议还是把命令固定到 PATH 里否则每次都要带 npx 前缀。注意安装类问题 90% 出在环境而不是工具本身。先确认 Node、npm、PATH 三项再考虑是不是命令写错。4. 模型配置与切换把 OpenCode 接到你已有的 API 服务4.1 配置文件里通常需要确认的三类信息无论你是用官方模型还是接第三方 API核心配置基本绕不开三项provider、model、apiKey。provider请求往哪个服务商发比如 OpenAI、Anthropic、DeepSeek、本地兼容服务。model具体使用的模型标识符比如某个服务的官方模型名。apiKey调用接口需要的密钥通常通过环境变量或者配置文件设置。以 JSON 举例实际字段名和当前工具版本有关这里只示意概念{ provider: your-provider-name, model: your-model-name, apiKeyEnv: MY_API_KEY_ENV }注意不要在配置文件里硬编码密钥也不要提交到 Git 仓库。建议用环境变量方案例如在项目目录的 .env 文件里配置再让工具读取对应的变量名。4.2 切换模型从启动参数到会话内命令切换模型的方式在 OpenCode 这类工具里一般有三条路径启动时通过参数指定模型。在交互界面里使用内置命令切换。修改配置文件后重启会话。实际使用中我建议把“当前项目固定用哪个模型”写进项目配置而不是每次手动切。因为同一个项目里不同模型的输出风格和工具调用能力差异很大换来换去会很难判断问题出在代码还是出在模型。如果你不是为了生产任务只是想低成本试一下 Agent Skills可以考虑本地模型。常见的本地方案是通过 Ollama 这类工具起一个服务然后在 OpenCode 的 provider 里指向 localhost 地址。本地模型对显存、内存要求不低低配置机器跑起来会明显偏慢但作为学习验证是够的。如果你接的是第三方 API比如 DeepSeek那就去对应服务商的文档里复制准确的模型名不要自己猜版本号。很多“模型不存在”的报错都是因为多打了一个后缀。4.3 高频报错xxx is not a model this version of claude code recognizes看到这条报错先不要慌。它常见于 Claude Code 以及相关兼容工具接入第三方模型时本质是模型标识符没有通过校验。常见原因有模型名拼写错了比如把版本号写错。你把第三方模型的名称填到了一个只认官方模型列表的配置里。配置文件里的 provider 字段没有真正生效模型校验仍然走了默认的官方接口。该模型在当前工具版本里根本不存在或者需要升级版本。排查顺序1. 打开配置文件确认 model 字段写的是提供商官方公布的模型名。 2. 确认 provider 和 model 是否匹配一个服务商的模型不能直接套在另一个服务商上。 3. 查看工具版本升级到最新稳定版再试。 4. 如果仍报错降低配置复杂度先用最简单的一条请求验证。这类问题里最容易踩的是“凭记忆写模型名”。模型名通常带版本后缀大小写、连字符都不能错。直接去服务商文档复制比人工核对要稳。5. Agent Skills 实战先写一个最简单的“代码评审”Skill5.1 Skill 的目录结构从一个最简的代码评审技能开始。常见的组织方式是建一个 skills 目录下面每个子目录是一个技能技能目录里放 SKILL.md以及可选的脚本、模板和示例。skills/ code-review/ SKILL.md examples/ example-diff.md注意不同工具对 Skills 的加载目录有不同约定有的按项目目录找有的要放到全局配置目录。动手前先看官方文档里关于 skills 的说明。不过 SKILL.md 这个核心文件的存在感很强大多数实现都靠它来识别技能。我建议把每个技能目录名都做成英文小写加连字符例如 code-review、doc-writer。这样在路径、日志和跨平台使用时都会减少麻烦。5.2 SKILL.md 里写什么SKILL.md 大体分为两块头部描述和正文指令。头部描述一般包含 name 和 description。description 尤其重要因为 agent 要靠它来判断“这个技能适不适合当前任务”。描述写得太宽会误触发写得太窄该触发时不触发。正文部分要写清楚角色、输入、步骤和输出格式。以代码评审为例可以这样组织--- name: code-review description: 当用户要求评审代码、Pull Request 或代码片段时使用。关注安全、性能、可读性。 --- # 代码评审 ## 角色 你是一名资深后端工程师评审时保持客观不吹毛求疵。 ## 输入 - 变更代码用户提供或从指定文件读取。 - 上下文如果缺失先问清楚不要急着输出。 ## 步骤 1. 先确认变更范围和目标。 2. 依次从安全性、性能、可读性、测试覆盖四个维度检查。 3. 给出问题列表标注严重等级。 ## 输出格式 返回 Markdown 表格 | 等级 | 位置 | 问题 | 建议 |这段不是标准格式只是示例。真正落地时请以你的工具文档和实际版本为准。5.3 如何验证 Skill 是否生效写完 SKILL.md 后怎么判断它真的生效了我的办法是准备一条很小的测试用例不要直接用大仓库或者完整 PR先把单文件 diff 丢进去。如果模型能识别出你描述里的触发场景并主动按照 SKILL.md 里的步骤输出说明技能描述匹配。如果模型回答得很混乱先检查 description 是否太长、太笼统。如果始终不加载技能检查目录路径、文件名大小写和加载方式。我第一次测试时最容易犯的错误是把 SKILL.md 放在错误目录还花半天调描述。后来我每次新建技能都先做一个“最小触发测试”输入一句和 description 高度相关的请求看工具日志里有没有出现技能加载记录。这一步能节省大量时间。6. 项目实战把“论文写作辅助”做成一个可复用的 Skill6.1 不要把整篇论文写成一个大 Prompt“Agent Skills 辅助人文社科写作”这类场景最近讨论得不少但很多实现从一开始就走歪了把“帮我写一篇论文”这种请求直接丢给模型。这样做出来的结果往往很空因为论文写作不是一个单步骤任务而是研究、阅读、整理、思考、成文、修改的循环过程。更合理的方式是拆成几个阶段研究问题拆解、文献整理、方法选择、大纲生成、逐节写作、润色和引用检查。每个阶段都可以做成一个独立技能也可以是一个多阶段技能里的子流程。6.2 混合研究方法场景下的流程设计混合研究方法一般指定性和定量结合。对这种场景Skill 的价值在于把“方法怎么选、数据怎么对齐、结论怎么呈现”变成固定流程。在 SKILL.md 里可以定义五个阶段研究问题拆解把宽泛话题变成可回答的问题。文献整理按主题、方法、结论做结构化梳理。方法设计说明定性数据、定量数据分别来自哪里如何交叉验证。草稿生成按引言、文献综述、方法、发现、讨论、结论生成大纲和段落。润色与检查检查逻辑衔接、语气、引用格式、论文要求。每一步都要求输出中间结果而不是直接给最终论文。比如第一步只输出一份研究问题清单第二步只输出文献整理表。这样你能在早期发现方向偏移不需要等全文生成完才后悔。6.3 输出格式与质量判断论文写作 Skill 的输出应该尽量结构化研究问题清单方便你确认范围。文献表格列研究主题、样本、方法、主要发现、可借鉴点。方法设计说明说明为什么用混合方法数据如何互补。大纲和段落保留占位符方便插入真实数据和引用。润色建议分“事实性检查”“逻辑性检查”“语言性检查”。判断一个写作 Skill 好不好不是看它生成的句子多漂亮而是看它能不能帮你把不可控的“一次性灌输”变成可控的“分阶段产出”。更关键的是模型可能编造文献或数据所以 Skill 里要强制写一句所有参考文献、统计结果必须由用户复核