在做 AI 辅助编码工具的选型与验证时我经常遇到一个尴尬场景模型能力很强但每次让它做同类任务都要重新描述需求。更麻烦的是让 AI 帮忙生成单元测试它有时会把整个业务代码一起“优化”掉结果完全不可用。问题其实不在模型本身而在于缺少一套稳定的、可复用的任务执行规范。Agent Skills 就是用来解决这类问题的。本文会结合 OpenCode 这套开源 AI 编程助手从概念、安装、原理一直拆到项目实战手把手带你制造一个真正可用的 Skill。本文适合三类读者一是刚接触 AI 编程工具想了解 Agent 和 Agent Skills 区别的新手二是已经在使用 Claude Code、Cursor 等工具但觉得每次会话都要重复“教模型怎么干活”的开发者三是团队内部希望沉淀统一代码规范、代码审查标准、脚手架生成流程的工程效能负责人。学完之后你应该能自己写 SKILL.md能在 OpenCode 中调用自定义技能也能处理最典型的安装和环境变量报错。1. 背景与核心概念1.1 什么是 Agent Skills用最通俗的话来说Agent Skills 是给 AI Agent 的一本“岗位操作手册”。它把一个特定任务从“要怎么干”到“要注意什么”全部写在文件里AI 看到任务后先读这份手册再按照手册里的步骤、规则、代码示例去执行。这样做的好处是你不需要每次都在聊天框里反复解释需求也不怕模型自由发挥导致风格不一致。从专业角度看Agent Skills 是一套文件化、可复用、面向特定任务的能力封装。它通常由三部分构成元信息技能名称、描述帮助模型判断“这个任务是不是应该用这个技能”。执行步骤明确告诉模型先做什么、再做什么、最后输出什么。参考资源示例代码、正则表达式、脚本路径、数据表结构等让模型在真实环境中调用。这个概念最初是因为 Claude Code 的 Agent Skills 功能而广为人知随后大量开源 AI 编码工具也采用了类似规范OpenCode 就是其中之一。它解决的核心痛点有三个第一避免重复解释任务第二让 AI 输出保持稳定第三把团队里优秀的工作流程沉淀成可分享的文件。1.2 OpenCode 是什么OpenCode 是一个开源 AI 编程助手运行在终端里界面是命令行交互风格。它最常被拿来和 Claude Code 对比也被很多开发者称为“Claude Code 的开源替代”。OpenCode 本身不绑定某一家大模型你可以接入 Anthropic 的 Claude、OpenAI 的模型、Google Gemini也可以接入本地私有化模型灵活性很高。相比直接在网页聊天框里让 AI 改代码OpenCode 最大的特点是能感知项目上下文它能看到你的项目目录结构能读取文件能在你的授权下执行命令还能配合 Git 工作流使用。正因为如此它才需要一个“技能系统”来约束 AI 的行为避免 AI 在项目里随意修改文件。OpenCode 对 Agent Skills 的兼容和实现本质上就是给这种强大的项目级操作能力加了一道“软性约束”。这里要特别说明一点OpenCode 迭代速度很快不同版本对技能目录、配置字段的支持会有差异。所以本文会以“通用规范 常见目录约定”为主线遇到可能变化的细节时会明确提醒大家在实际使用时以官方仓库文档和本地版本的 schema 为准。1.3 Agent 与 Agent Skills 的区别很多刚接触的朋友会把 Agent 和 Agent Skills 混为一谈其实它们不是同一层的东西。一个 Agent 是具备感知、规划、工具调用、多轮决策能力的完整智能体你可以把它理解成一个“员工”。Agent Skills 则是这个员工手里的“岗位 SOP”告诉员工某个具体任务该怎么按步骤完成。用一个比喻来说Agent 是能自主思考、执行命令的“工程师”Skill 是公司里沉淀下来的“研发规范文档”。工程师可以不看文档干活但看了文档会干得更稳定工程师可以换人但文档留下来了。这也是为什么 Skills 往往比 Agent 更容易在团队中复用因为 Skill 本质上是一份可以被 Git 版本管理的文本文件。对比维度AgentAgent Skills本质完整的智能执行体可复用的任务指令包是否包含决策能力是否只提供方法和约束是否可独立运行是否需要由 Agent 调用复用方式配置 Agent 并授予工具复制 SKILL.md 到项目或用户目录典型例子opencode 默认编码助手代码审查技能、Commit Message 生成技能在实际使用中推荐的做法不是把所有逻辑都做成一个超级 Agent而是拆解成多个小而专的 Skills。一个 Skill 只负责一件事Agent 根据用户意图动态选择合适的 Skill 来执行。2. 环境准备与版本说明2.1 运行环境要求OpenCode 本质上是 Node.js 生态下的命令行工具所以安装前需要先准备 Node.js 运行环境。建议安装 Node.js 的 LTS 版本并使用 npm 或 bun 作为包管理器。在终端执行下面两条命令确认环境是否就绪node -v npm -v如果node命令无法识别说明 Node.js 没有安装或没有正确加入系统 PATH。Windows 用户建议通过官方安装包或 nvm-windows 安装macOS 用户可以使用 Homebrew 安装brew install node除了 Node.js还需要一个终端工具。Windows 上推荐 Windows Terminal PowerShellmacOS 上使用系统自带终端或 iTerm2 都可以。OpenCode 的交互界面是终端 UI对终端宽度有一定要求设置终端窗口宽度在 100 字符以上体验更好。编辑器方面OpenCode 本身不依赖 VSCode 或 IDEA但很多使用者会同时安装对应插件来弥补终端编辑的不足。插件生态更新很快建议直接在 VSCode 扩展市场和 JetBrains 插件中心搜索 opencode 查看是否存在官方或社区维护的版本再按说明安装。2.2 安装 OpenCodeOpenCode 的安装方式比较多样常见的有 npm 全局安装、Homebrew 安装和二进制包安装。以最常见的 npm 方式为例npm install -g opencode-ai如果你使用 Homebrew也可以尝试brew install opencode不过要提醒一句官方推荐安装方式会随版本变化建议先去开源仓库的 README 页面确认最新命令再执行安装。安装完成后可以通过版本号验证是否安装成功opencode --version如果能正常输出版本号说明安装成功。如果提示opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称这是 Windows 上非常典型的环境变量问题。具体排查方法会在后面的“常见问题”章节详细说明。2.3 配置模型 API KeyOpenCode 本身没有内置推理能力需要接入大模型 API。不同模型提供商的配置方式略有差异但核心思路都是通过环境变量传递密钥。以 Anthropic Claude 和 OpenAI 为例# 临时设置只对当前终端窗口生效 export ANTHROPIC_API_KEYsk-ant-xxxx # 或 export OPENAI_API_KEYsk-xxxxWindows PowerShell 下可以使用$env:ANTHROPIC_API_KEYsk-ant-xxxx正式使用时不建议直接把密钥写到命令行里更推荐写入一个不提交到 Git 的.env文件或者使用操作系统用户级环境变量。配置完成后在项目目录下直接运行opencode进入交互界面后输入一句自然语言比如“帮我解释一下当前目录的项目结构”如果模型能正常返回说明环境和密钥都配置成功。3. Agent Skills 核心原理与格式3.1 SKILL.md 规范Agent Skills 的核心文件是SKILL.md。OpenCode 基本兼容 Claude Code 的 Agent Skills 格式所以你可以把社区里已有的很多 Skills 直接拿过来使用。这个文件的结构很简单由两部分组成。第一部分是 YAML frontmatter用两行---包裹声明技能的名称和描述--- name: code-review description: 对指定目录中的 Python 代码执行静态审查标记 TODO、FIXME、语法错误等风险点。用于代码合并前的质量检查。 --- # 代码审查技能 在开始审查前你需要先运行脚本扫描目标目录第二部分是 Markdown 正文也就是给模型看的“操作手册”。这里要写清楚目标、执行步骤、注意事项和示例。模型在执行时会根据description判断是否要使用这个技能一旦决定使用就会读取整个 SKILL.md 并按里面的指令行动。description是很容易被忽视但极其重要的字段。它相当于技能的“广告语”必须写清楚两件事这个技能是干什么的在什么场景下应该被调用。描述太宽泛模型会在不该用的时候误用描述太窄真正需要时又不会触发。3.2 Skills 的存放与加载机制Skills 的加载路径通常分成项目级和用户级两种。项目级路径一般放在.opencode/skills/目录下适合给特定项目使用的技能比如项目专属代码规范、提交规范、部署检查清单。用户级路径一般在用户配置目录下例如~/.config/opencode/skills/适合跨项目复用的通用技能。一个完整的项目级 Skill 目录大致如下my-project/ ├── .opencode/ │ └── skills/ │ └── code-review/ │ ├── SKILL.md │ └── scripts/ │ └── scan.py ├── src/ │ └── main.py └── README.mdOpenCode 启动后会扫描这些目录把识别到的 Skill 名称和描述注册到 Agent 的能力列表中。注意扫描的是目录不是单个文件。每个技能必须拥有独立目录目录里至少要有一个SKILL.md其他辅助脚本可以放在同一目录的子文件夹中。实际开发中项目级 Skills 最大的价值是“跟随代码仓库一起提交”。团队成员 clone 项目后不需要额外配置就拥有一套统一的 AI 工作标准。这一点在团队协作时收益非常明显。3.3 Skills、Commands 与 Agent 的关系在 OpenCode 里除了 Agent Skills 之外还有内置命令和执行器Agent的概念很多用户会混淆。简单区分Agent负责理解用户意图、决定调用什么技能、执行什么操作。Skill提供“步骤 规则 脚本引用”的知识包Agent 按需读取。Command通常是用户在界面上可直接触发的快捷指令可以把技能调用固化成一个斜杠命令或快捷入口。整个工作流程可以这样理解用户提出任务Agent 判断任务符合某个 Skill 的description于是读取对应的SKILL.md按里面的指令执行如果 Skill 里写了要运行脚本Agent 在获得授权后调用脚本再结合脚本输出继续分析。这正是 Agent Skills 对 AI 编程工具最重要的意义它让模型从“自由发挥”变成了“按规范执行”。自由发挥适合闲聊和创意但代码审查、单元测试、数据库变更这类工作必须稳准狠技能包就是稳定性的来源。4. 完整实战从零构建一个代码审查 Skill4.1 需求分析与项目结构这一节我们从一个非常常见且收益很高的场景出发团队每次代码合并前希望 AI 能先扫描一遍 Python 代码找出遗留的 TODO、FIXME 标记以及明显的语法错误并根据扫描结果给出修复建议。需求拆解后我们需要做两件事写一个 Python 脚本扫描目标目录输出风险清单。写一个SKILL.md告诉 Agent 什么时候调用脚本、如何解读结果、如何输出报告。最终的项目结构如下my-project/ ├── .opencode/ │ └── skills/ │ └── code-review/ │ ├── SKILL.md │ └── scripts/ │ └── scan.py ├── src/ │ └── main.py └── README.md这个结构里.opencode/目录是给 AI 工具使用的项目配置目录不参与业务运行src/是待审查的业务代码整个目录都可以提交到 Git 仓库方便团队共享。4.2 编写辅助扫描脚本先创建脚本文件scan.py。这个脚本的作用是递归扫描指定目录下的 Python 文件检查三类风险代码里的 TODO/FIXME 标记、语法错误、以及遗留的调试打印语句。#!/usr/bin/env python3 简易 Python 代码静态扫描脚本供 code-review skill 调用。 用法 python scripts/scan.py [目标目录路径] import ast import pathlib import sys import re # 需要重点标记的注释关键字 MARK_PATTERN re.compile(rTODO|FIXME|HACK, re.IGNORECASE) # 常见调试遗留 DEBUG_PATTERN re.compile(rprint\(|breakpoint\(|pdb\., re.IGNORECASE) def scan_file(file_path: pathlib.Path): issues [] try: content file_path.read_text(encodingutf-8, errorsignore) except Exception as exc: issues.append((1, IOError, str(exc))) return issues for line_no, line in enumerate(content.splitlines(), start1): if MARK_PATTERN.search(line): issues.append((line_no, Mark, line.strip()[:100])) if DEBUG_PATTERN.search(line) and scan.py not in str(file_path): issues.append((line_no, Debug, line.strip()[:100])) # Python 文件额外检查语法错误 if file_path.suffix .py: try: ast.parse(content) except SyntaxError as exc: issues.append((exc.lineno or 0, SyntaxError, f{exc.msg})) return issues def main(): if len(sys.argv) 2: print(用法: python scan.py 目录) sys.exit(1) root pathlib.Path(sys.argv[1]) if not root.exists(): print(f[错误] 目录不存在: {root}) sys.exit(1) py_files [ p for p in root.rglob(*.py) if node_modules not in p.parts and .venv not in p.parts and site-packages not in p.parts ] if not py_files: print([扫描结果] 未发现 Python 文件) return total_issues 0 for file_path in sorted(py_files): issues scan_file(file_path) if issues: total_issues len(issues) print(f\n[{file_path}]) for line_no, level, msg in issues: print(f line {line_no}: [{level}] {msg}) print(f\n[扫描完成] 共检查 {len(py_files)} 个文件发现 {total_issues} 处风险点。) if __name__ __main__: main()这段脚本有以下关键设计用pathlib.Path.rglob(*.py)递归查找目标目录下的所有 Python 文件并排除node_modules、.venv等虚拟环境目录避免扫描到无关第三方代码。逐行读取文件内容通过正则表达式匹配TODO/FIXME/HACK关键字和调试语句记录行号和内容。对.py文件额外调用ast.parse做语法解析能直接发现缩进错误、括号不匹配等语法问题。输出格式是固定的“文件名 lineno 等级 信息”方便 Agent 解析后生成报告。4.3 编写 SKILL.md接下来创建技能的核心文件SKILL.md放在.opencode/skills/code-review/目录下。--- name: code-review description: 用于 Python 项目的代码审查。当用户要求审查代码质量、查找 TODO/FIXME、检查语法错误、评估代码风险时使用。适合合并请求前的快速检查。 --- # Python 代码审查技能 你是一名资深 Python 代码审查专家。请按照以下流程完成审查任务。 ## 第一步定位目标目录 优先使用用户指定的目录。如果用户没有指定默认审查当前项目中的 src/ 目录。不要审查 .venv、node_modules、site-packages 等第三方依赖目录。 ## 第二步运行扫描脚本 在项目根目录下执行 bash python .opencode/skills/code-review/scripts/scan.py 目标目录当目标目录是当前项目根目录时也可以简写为python .opencode/skills/code-review/scripts/scan.py .第三步解析脚本输出脚本会输出类似下面的结果[src/main.py] line 7: [Mark] TODO: 后续需要优化数据库连接池 line 12: [Debug] print(debug) [扫描完成] 共检查 3 个文件发现 2 处风险点。你需要结合项目实际情况判断每一行风险的真实危害等级。第四步输出审查报告最终报告使用 Markdown 表格包含以下列文件路径、行号、风险类型、问题说明、修复建议。报告必须以问题严重程度排序先展示会导致程序异常或安全风险的 SyntaxError再展示遗留调试代码、TODO 标记等维护性问题。不要修改任何代码文件只做审查和建议。注意事项如果脚本执行失败先检查 Python 是否安装再判断脚本路径是否正确。不要虚构脚本输出必须以实际执行结果为准。针对每一条问题给出具体修复思路避免“建议优化”这种空话。合并请求场景下要额外关注改动文件优先审查本次变更涉及的代码。这份 SKILL.md 的核心价值在于把“怎么审查”的步骤固化下来。模型看到用户要求后会先判断 description 是否符合符合则按正文流程执行定位目录、运行脚本、解析输出、输出报告。相比直接让模型看代码这个流程减少了幻觉也更稳定。 ### 4.4 在 OpenCode 中调用 Skill 现在进入验证环节。在项目根目录启动 OpenCode bash opencode在交互界面中输入请使用 code-review 技能审查一下 src/ 目录下的代码质量。Agent 在注意到code-review这个技能名称后会主动读取SKILL.md然后按照里面的流程调用scan.py脚本。如果你的模型本身能力较强也可以不显式提技能名只要说“帮我做一次代码审查找出 TODO 和语法错误”模型同样有可能通过description匹配到对应技能。如果你希望在团队中快速调用技能还可以在 OpenCode 中配置自定义命令把一句话扩张成固定指令。不同版本实现略有差异建议先查看当前版本的官方命令说明。4.5 运行与结果说明假设项目里有两个 Python 文件其中src/main.py里有遗留 TODO 和调试输出运行脚本后预期输出如下[src/main.py] line 7: [Mark] TODO: 后续需要优化数据库连接池 line 12: [Debug] print(debug) [扫描完成] 共检查 2 个文件发现 2 处风险点。随后 Agent 会根据这个输出生成报告文件路径行号风险类型问题说明修复建议src/main.py7Mark遗留 TODO 标记数据库连接池待优化使用连接池配置或延迟加载策略src/main.py12Debug遗留 print 调试语句使用 logging 模块删除调试输出到这里一个项目级 Skill 就从零跑通了。后续你可以根据团队规范不断调整SKILL.md里的步骤比如增加“检查异常捕获是否吞掉错误”“检查是否硬编码密钥”等更细的规则让审查越来越贴近业务。5. 常见问题与排查思路问题现象常见原因解决思路安装后opencode命令无法识别提示“无法将 opencode 项识别为 cmdlet”npm 全局安装目录未加入系统 PATH执行npm config get prefix查询目录将对应目录加入 PATH然后重启终端运行opencode后没有进入交互界面终端宽度过小或终端兼容性问题扩大终端窗口宽度切换 Windows Terminal / iTerm2 等现代终端Agent 没有触发自定义 SkillSkill 目录位置不对或description不够清晰确认 SKILL.md 位于.opencode/skills/name/下优化 description 中的场景描述脚本在 Skill 中执行失败路径问题或 Python 环境问题在项目根目录手动执行脚本路径先确认脚本本身可运行模型返回结果中夹带幻觉信息Skill 指令里没有要求“以脚本输出为准”在 SKILL.md 中明确“不要虚构脚本输出必须以实际执行结果为准”API 连接失败或超时API Key 未配置、服务不可用、网络策略限制检查环境变量是否生效确认 API 服务状态重试或切换网络环境这里重点展开 Windows 下最常见的opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称问题。这个报错本质上不是 OpenCode 的问题而是 npm 全局安装的二进制文件目录没有加到系统 PATH 环境变量中。排查步骤按顺序来# 1. 确认 Node.js 已生效 node -v # 2. 查询 npm 全局安装目录 npm config get prefix假设输出是C:\Users\你的用户名\AppData\Roaming\npm那么你在 PowerShell 中检查 PATH 是否包含这个目录# 查看用户级 PATH [Environment]::GetEnvironmentVariable(Path, User)如果没有包含可以手动添加$npmPath $env:APPDATA\npm [Environment]::SetEnvironmentVariable(Path, $env:Path ;$npmPath, User)添加完成后必须重新打开一个终端窗口环境变量才会生效。重新执行opencode --version通常就能正常输出了。如果仍然失败再检查是否使用了 nvm-windows 多版本管理工具确认当前 Node 版本对应的全局目录确实在 PATH 中。6. 最佳实践与工程建议关于 Skill 的命名建议使用全小写加短横线例如code-review、commit-message、python-scaffold。不要使用空格和中文因为技能名会出现在命令行或模型上下文中特殊字符容易引入解析问题。description字段要多花心思。很多人在第一次写 Skill 时会写“用于代码审查”这样过于简单的描述。更合理的问题是模型在什么场景下应该看到这段描述并选择这个技能写description时可以带着“触发条件思维”比如description: 当用户要求审查 Python 代码、查找 TODO/FIXME、检查语法错误或提交合并请求前需要质量评估时使用。不适用于代码重构和功能开发。这样的描述既说明了何时使用又排除了不适用场景模型误触发的概率会大大降低。一个 Skill 只聚焦一个任务。如果代码审查和单元测试生成放在同一个 SKILL.md 里模型执行时容易“串味”一会儿做审查一会儿又去生成测试。拆成两个独立 Skills每个文件短小精悍执行质量更高。Skill 文件不是越长越好几十行能说清楚的事情不要写成几百行。辅助脚本要兼容多平台。上面示例中的scan.py用了 Python天然跨平台如果你使用 Shell 脚本一定要考虑到 Windows 环境没有 bash 的情况。团队即使都在同一个系统上也建议在脚本里处理路径中文、编码等问题避免 Agent 因为编码报错而中断。安全边界必须在 SKILL.md 里明确写出来。比如技能允许调用脚本但不允许执行高风险删除命令技能可以读取文件但不要把密钥写入日志。模型在缺乏约束时可能会做出激进操作所以“哪些不能做”和“应该怎么做”同样重要。技能要纳入版本控制。.opencode/目录应该和业务代码一起提交到 Git这样团队成员 clone 项目后就拥有一致的 AI 工作流。技能更新时建议通过 Git 历史保留每次改动的记录方便回滚。定期回看技能的实际使用效果。Agent Skills 不是写一次就一劳永逸模型版本升级、项目规范调整都可能让旧技能不再适配。建议每个迭代周期结束后把技能效果、模型错误操作、团队成员反馈记录下来持续修订 SKILL.md。这本质上和代码重构一样是持续投入。在权限配置方面遵循最小权限原则。生产环境或敏感项目中不要给 AI 工具过高的文件系统权限更不要把生产密钥写进环境变量后让 AI 自由读取。必要情况下可以先在预发布环境验证技能指令再带到生产项目中使用。7. 总结与下一步这篇文章从 Agent Skills 的概念讲起通过 OpenCode 这套开源工具完成了环境搭建、SKILL.md 格式解析、代码审查技能实战和常见问题排查。如果你跟着流程走完现在应该已经拥有一个属于自己的、可以复用的代码审查技能。下一步可以往这些方向拓展先为高频重复动作编写更多 Skills比如“生成 Conventional Commit 提交信息”“生成单元测试”“整理项目文档”然后研究 OpenCode 的权限模型和自定义命令把常用技能固化成一键触发有条件的话尝试在团队内部统一技能目录模板让新成员 clone 项目后直接用同一套标准与 AI 协作。最后分享一条实际体会第一次做 Agent Skills 时不要一上来就写大型技能。挑一个你每天都会重复的任务比如“给本次改动写 commit message”把之前反复叮嘱 AI 的话整理成 SKILL.md整个过程不超过半小时。这个最小改动带来的体验提升往往比换一个更贵的模型明显得多。先把高频小任务稳定下来再逐步扩大技能覆盖面这条路走起来最顺。
在做 AI 辅助编码工具的选型与验证时我经常遇到一个尴尬场景模型能力很强但每次让它做同类任务都要重新描述需求。更麻烦的是让 AI 帮忙生成单元测试它有时会把整个业务代码一起“优化”掉结果完全不可用。问题其实不在模型本身而在于缺少一套稳定的、可复用的任务执行规范。Agent Skills 就是用来解决这类问题的。本文会结合 OpenCode 这套开源 AI 编程助手从概念、安装、原理一直拆到项目实战手把手带你制造一个真正可用的 Skill。本文适合三类读者一是刚接触 AI 编程工具想了解 Agent 和 Agent Skills 区别的新手二是已经在使用 Claude Code、Cursor 等工具但觉得每次会话都要重复“教模型怎么干活”的开发者三是团队内部希望沉淀统一代码规范、代码审查标准、脚手架生成流程的工程效能负责人。学完之后你应该能自己写 SKILL.md能在 OpenCode 中调用自定义技能也能处理最典型的安装和环境变量报错。1. 背景与核心概念1.1 什么是 Agent Skills用最通俗的话来说Agent Skills 是给 AI Agent 的一本“岗位操作手册”。它把一个特定任务从“要怎么干”到“要注意什么”全部写在文件里AI 看到任务后先读这份手册再按照手册里的步骤、规则、代码示例去执行。这样做的好处是你不需要每次都在聊天框里反复解释需求也不怕模型自由发挥导致风格不一致。从专业角度看Agent Skills 是一套文件化、可复用、面向特定任务的能力封装。它通常由三部分构成元信息技能名称、描述帮助模型判断“这个任务是不是应该用这个技能”。执行步骤明确告诉模型先做什么、再做什么、最后输出什么。参考资源示例代码、正则表达式、脚本路径、数据表结构等让模型在真实环境中调用。这个概念最初是因为 Claude Code 的 Agent Skills 功能而广为人知随后大量开源 AI 编码工具也采用了类似规范OpenCode 就是其中之一。它解决的核心痛点有三个第一避免重复解释任务第二让 AI 输出保持稳定第三把团队里优秀的工作流程沉淀成可分享的文件。1.2 OpenCode 是什么OpenCode 是一个开源 AI 编程助手运行在终端里界面是命令行交互风格。它最常被拿来和 Claude Code 对比也被很多开发者称为“Claude Code 的开源替代”。OpenCode 本身不绑定某一家大模型你可以接入 Anthropic 的 Claude、OpenAI 的模型、Google Gemini也可以接入本地私有化模型灵活性很高。相比直接在网页聊天框里让 AI 改代码OpenCode 最大的特点是能感知项目上下文它能看到你的项目目录结构能读取文件能在你的授权下执行命令还能配合 Git 工作流使用。正因为如此它才需要一个“技能系统”来约束 AI 的行为避免 AI 在项目里随意修改文件。OpenCode 对 Agent Skills 的兼容和实现本质上就是给这种强大的项目级操作能力加了一道“软性约束”。这里要特别说明一点OpenCode 迭代速度很快不同版本对技能目录、配置字段的支持会有差异。所以本文会以“通用规范 常见目录约定”为主线遇到可能变化的细节时会明确提醒大家在实际使用时以官方仓库文档和本地版本的 schema 为准。1.3 Agent 与 Agent Skills 的区别很多刚接触的朋友会把 Agent 和 Agent Skills 混为一谈其实它们不是同一层的东西。一个 Agent 是具备感知、规划、工具调用、多轮决策能力的完整智能体你可以把它理解成一个“员工”。Agent Skills 则是这个员工手里的“岗位 SOP”告诉员工某个具体任务该怎么按步骤完成。用一个比喻来说Agent 是能自主思考、执行命令的“工程师”Skill 是公司里沉淀下来的“研发规范文档”。工程师可以不看文档干活但看了文档会干得更稳定工程师可以换人但文档留下来了。这也是为什么 Skills 往往比 Agent 更容易在团队中复用因为 Skill 本质上是一份可以被 Git 版本管理的文本文件。对比维度AgentAgent Skills本质完整的智能执行体可复用的任务指令包是否包含决策能力是否只提供方法和约束是否可独立运行是否需要由 Agent 调用复用方式配置 Agent 并授予工具复制 SKILL.md 到项目或用户目录典型例子opencode 默认编码助手代码审查技能、Commit Message 生成技能在实际使用中推荐的做法不是把所有逻辑都做成一个超级 Agent而是拆解成多个小而专的 Skills。一个 Skill 只负责一件事Agent 根据用户意图动态选择合适的 Skill 来执行。2. 环境准备与版本说明2.1 运行环境要求OpenCode 本质上是 Node.js 生态下的命令行工具所以安装前需要先准备 Node.js 运行环境。建议安装 Node.js 的 LTS 版本并使用 npm 或 bun 作为包管理器。在终端执行下面两条命令确认环境是否就绪node -v npm -v如果node命令无法识别说明 Node.js 没有安装或没有正确加入系统 PATH。Windows 用户建议通过官方安装包或 nvm-windows 安装macOS 用户可以使用 Homebrew 安装brew install node除了 Node.js还需要一个终端工具。Windows 上推荐 Windows Terminal PowerShellmacOS 上使用系统自带终端或 iTerm2 都可以。OpenCode 的交互界面是终端 UI对终端宽度有一定要求设置终端窗口宽度在 100 字符以上体验更好。编辑器方面OpenCode 本身不依赖 VSCode 或 IDEA但很多使用者会同时安装对应插件来弥补终端编辑的不足。插件生态更新很快建议直接在 VSCode 扩展市场和 JetBrains 插件中心搜索 opencode 查看是否存在官方或社区维护的版本再按说明安装。2.2 安装 OpenCodeOpenCode 的安装方式比较多样常见的有 npm 全局安装、Homebrew 安装和二进制包安装。以最常见的 npm 方式为例npm install -g opencode-ai如果你使用 Homebrew也可以尝试brew install opencode不过要提醒一句官方推荐安装方式会随版本变化建议先去开源仓库的 README 页面确认最新命令再执行安装。安装完成后可以通过版本号验证是否安装成功opencode --version如果能正常输出版本号说明安装成功。如果提示opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称这是 Windows 上非常典型的环境变量问题。具体排查方法会在后面的“常见问题”章节详细说明。2.3 配置模型 API KeyOpenCode 本身没有内置推理能力需要接入大模型 API。不同模型提供商的配置方式略有差异但核心思路都是通过环境变量传递密钥。以 Anthropic Claude 和 OpenAI 为例# 临时设置只对当前终端窗口生效 export ANTHROPIC_API_KEYsk-ant-xxxx # 或 export OPENAI_API_KEYsk-xxxxWindows PowerShell 下可以使用$env:ANTHROPIC_API_KEYsk-ant-xxxx正式使用时不建议直接把密钥写到命令行里更推荐写入一个不提交到 Git 的.env文件或者使用操作系统用户级环境变量。配置完成后在项目目录下直接运行opencode进入交互界面后输入一句自然语言比如“帮我解释一下当前目录的项目结构”如果模型能正常返回说明环境和密钥都配置成功。3. Agent Skills 核心原理与格式3.1 SKILL.md 规范Agent Skills 的核心文件是SKILL.md。OpenCode 基本兼容 Claude Code 的 Agent Skills 格式所以你可以把社区里已有的很多 Skills 直接拿过来使用。这个文件的结构很简单由两部分组成。第一部分是 YAML frontmatter用两行---包裹声明技能的名称和描述--- name: code-review description: 对指定目录中的 Python 代码执行静态审查标记 TODO、FIXME、语法错误等风险点。用于代码合并前的质量检查。 --- # 代码审查技能 在开始审查前你需要先运行脚本扫描目标目录第二部分是 Markdown 正文也就是给模型看的“操作手册”。这里要写清楚目标、执行步骤、注意事项和示例。模型在执行时会根据description判断是否要使用这个技能一旦决定使用就会读取整个 SKILL.md 并按里面的指令行动。description是很容易被忽视但极其重要的字段。它相当于技能的“广告语”必须写清楚两件事这个技能是干什么的在什么场景下应该被调用。描述太宽泛模型会在不该用的时候误用描述太窄真正需要时又不会触发。3.2 Skills 的存放与加载机制Skills 的加载路径通常分成项目级和用户级两种。项目级路径一般放在.opencode/skills/目录下适合给特定项目使用的技能比如项目专属代码规范、提交规范、部署检查清单。用户级路径一般在用户配置目录下例如~/.config/opencode/skills/适合跨项目复用的通用技能。一个完整的项目级 Skill 目录大致如下my-project/ ├── .opencode/ │ └── skills/ │ └── code-review/ │ ├── SKILL.md │ └── scripts/ │ └── scan.py ├── src/ │ └── main.py └── README.mdOpenCode 启动后会扫描这些目录把识别到的 Skill 名称和描述注册到 Agent 的能力列表中。注意扫描的是目录不是单个文件。每个技能必须拥有独立目录目录里至少要有一个SKILL.md其他辅助脚本可以放在同一目录的子文件夹中。实际开发中项目级 Skills 最大的价值是“跟随代码仓库一起提交”。团队成员 clone 项目后不需要额外配置就拥有一套统一的 AI 工作标准。这一点在团队协作时收益非常明显。3.3 Skills、Commands 与 Agent 的关系在 OpenCode 里除了 Agent Skills 之外还有内置命令和执行器Agent的概念很多用户会混淆。简单区分Agent负责理解用户意图、决定调用什么技能、执行什么操作。Skill提供“步骤 规则 脚本引用”的知识包Agent 按需读取。Command通常是用户在界面上可直接触发的快捷指令可以把技能调用固化成一个斜杠命令或快捷入口。整个工作流程可以这样理解用户提出任务Agent 判断任务符合某个 Skill 的description于是读取对应的SKILL.md按里面的指令执行如果 Skill 里写了要运行脚本Agent 在获得授权后调用脚本再结合脚本输出继续分析。这正是 Agent Skills 对 AI 编程工具最重要的意义它让模型从“自由发挥”变成了“按规范执行”。自由发挥适合闲聊和创意但代码审查、单元测试、数据库变更这类工作必须稳准狠技能包就是稳定性的来源。4. 完整实战从零构建一个代码审查 Skill4.1 需求分析与项目结构这一节我们从一个非常常见且收益很高的场景出发团队每次代码合并前希望 AI 能先扫描一遍 Python 代码找出遗留的 TODO、FIXME 标记以及明显的语法错误并根据扫描结果给出修复建议。需求拆解后我们需要做两件事写一个 Python 脚本扫描目标目录输出风险清单。写一个SKILL.md告诉 Agent 什么时候调用脚本、如何解读结果、如何输出报告。最终的项目结构如下my-project/ ├── .opencode/ │ └── skills/ │ └── code-review/ │ ├── SKILL.md │ └── scripts/ │ └── scan.py ├── src/ │ └── main.py └── README.md这个结构里.opencode/目录是给 AI 工具使用的项目配置目录不参与业务运行src/是待审查的业务代码整个目录都可以提交到 Git 仓库方便团队共享。4.2 编写辅助扫描脚本先创建脚本文件scan.py。这个脚本的作用是递归扫描指定目录下的 Python 文件检查三类风险代码里的 TODO/FIXME 标记、语法错误、以及遗留的调试打印语句。#!/usr/bin/env python3 简易 Python 代码静态扫描脚本供 code-review skill 调用。 用法 python scripts/scan.py [目标目录路径] import ast import pathlib import sys import re # 需要重点标记的注释关键字 MARK_PATTERN re.compile(rTODO|FIXME|HACK, re.IGNORECASE) # 常见调试遗留 DEBUG_PATTERN re.compile(rprint\(|breakpoint\(|pdb\., re.IGNORECASE) def scan_file(file_path: pathlib.Path): issues [] try: content file_path.read_text(encodingutf-8, errorsignore) except Exception as exc: issues.append((1, IOError, str(exc))) return issues for line_no, line in enumerate(content.splitlines(), start1): if MARK_PATTERN.search(line): issues.append((line_no, Mark, line.strip()[:100])) if DEBUG_PATTERN.search(line) and scan.py not in str(file_path): issues.append((line_no, Debug, line.strip()[:100])) # Python 文件额外检查语法错误 if file_path.suffix .py: try: ast.parse(content) except SyntaxError as exc: issues.append((exc.lineno or 0, SyntaxError, f{exc.msg})) return issues def main(): if len(sys.argv) 2: print(用法: python scan.py 目录) sys.exit(1) root pathlib.Path(sys.argv[1]) if not root.exists(): print(f[错误] 目录不存在: {root}) sys.exit(1) py_files [ p for p in root.rglob(*.py) if node_modules not in p.parts and .venv not in p.parts and site-packages not in p.parts ] if not py_files: print([扫描结果] 未发现 Python 文件) return total_issues 0 for file_path in sorted(py_files): issues scan_file(file_path) if issues: total_issues len(issues) print(f\n[{file_path}]) for line_no, level, msg in issues: print(f line {line_no}: [{level}] {msg}) print(f\n[扫描完成] 共检查 {len(py_files)} 个文件发现 {total_issues} 处风险点。) if __name__ __main__: main()这段脚本有以下关键设计用pathlib.Path.rglob(*.py)递归查找目标目录下的所有 Python 文件并排除node_modules、.venv等虚拟环境目录避免扫描到无关第三方代码。逐行读取文件内容通过正则表达式匹配TODO/FIXME/HACK关键字和调试语句记录行号和内容。对.py文件额外调用ast.parse做语法解析能直接发现缩进错误、括号不匹配等语法问题。输出格式是固定的“文件名 lineno 等级 信息”方便 Agent 解析后生成报告。4.3 编写 SKILL.md接下来创建技能的核心文件SKILL.md放在.opencode/skills/code-review/目录下。--- name: code-review description: 用于 Python 项目的代码审查。当用户要求审查代码质量、查找 TODO/FIXME、检查语法错误、评估代码风险时使用。适合合并请求前的快速检查。 --- # Python 代码审查技能 你是一名资深 Python 代码审查专家。请按照以下流程完成审查任务。 ## 第一步定位目标目录 优先使用用户指定的目录。如果用户没有指定默认审查当前项目中的 src/ 目录。不要审查 .venv、node_modules、site-packages 等第三方依赖目录。 ## 第二步运行扫描脚本 在项目根目录下执行 bash python .opencode/skills/code-review/scripts/scan.py 目标目录当目标目录是当前项目根目录时也可以简写为python .opencode/skills/code-review/scripts/scan.py .第三步解析脚本输出脚本会输出类似下面的结果[src/main.py] line 7: [Mark] TODO: 后续需要优化数据库连接池 line 12: [Debug] print(debug) [扫描完成] 共检查 3 个文件发现 2 处风险点。你需要结合项目实际情况判断每一行风险的真实危害等级。第四步输出审查报告最终报告使用 Markdown 表格包含以下列文件路径、行号、风险类型、问题说明、修复建议。报告必须以问题严重程度排序先展示会导致程序异常或安全风险的 SyntaxError再展示遗留调试代码、TODO 标记等维护性问题。不要修改任何代码文件只做审查和建议。注意事项如果脚本执行失败先检查 Python 是否安装再判断脚本路径是否正确。不要虚构脚本输出必须以实际执行结果为准。针对每一条问题给出具体修复思路避免“建议优化”这种空话。合并请求场景下要额外关注改动文件优先审查本次变更涉及的代码。这份 SKILL.md 的核心价值在于把“怎么审查”的步骤固化下来。模型看到用户要求后会先判断 description 是否符合符合则按正文流程执行定位目录、运行脚本、解析输出、输出报告。相比直接让模型看代码这个流程减少了幻觉也更稳定。 ### 4.4 在 OpenCode 中调用 Skill 现在进入验证环节。在项目根目录启动 OpenCode bash opencode在交互界面中输入请使用 code-review 技能审查一下 src/ 目录下的代码质量。Agent 在注意到code-review这个技能名称后会主动读取SKILL.md然后按照里面的流程调用scan.py脚本。如果你的模型本身能力较强也可以不显式提技能名只要说“帮我做一次代码审查找出 TODO 和语法错误”模型同样有可能通过description匹配到对应技能。如果你希望在团队中快速调用技能还可以在 OpenCode 中配置自定义命令把一句话扩张成固定指令。不同版本实现略有差异建议先查看当前版本的官方命令说明。4.5 运行与结果说明假设项目里有两个 Python 文件其中src/main.py里有遗留 TODO 和调试输出运行脚本后预期输出如下[src/main.py] line 7: [Mark] TODO: 后续需要优化数据库连接池 line 12: [Debug] print(debug) [扫描完成] 共检查 2 个文件发现 2 处风险点。随后 Agent 会根据这个输出生成报告文件路径行号风险类型问题说明修复建议src/main.py7Mark遗留 TODO 标记数据库连接池待优化使用连接池配置或延迟加载策略src/main.py12Debug遗留 print 调试语句使用 logging 模块删除调试输出到这里一个项目级 Skill 就从零跑通了。后续你可以根据团队规范不断调整SKILL.md里的步骤比如增加“检查异常捕获是否吞掉错误”“检查是否硬编码密钥”等更细的规则让审查越来越贴近业务。5. 常见问题与排查思路问题现象常见原因解决思路安装后opencode命令无法识别提示“无法将 opencode 项识别为 cmdlet”npm 全局安装目录未加入系统 PATH执行npm config get prefix查询目录将对应目录加入 PATH然后重启终端运行opencode后没有进入交互界面终端宽度过小或终端兼容性问题扩大终端窗口宽度切换 Windows Terminal / iTerm2 等现代终端Agent 没有触发自定义 SkillSkill 目录位置不对或description不够清晰确认 SKILL.md 位于.opencode/skills/name/下优化 description 中的场景描述脚本在 Skill 中执行失败路径问题或 Python 环境问题在项目根目录手动执行脚本路径先确认脚本本身可运行模型返回结果中夹带幻觉信息Skill 指令里没有要求“以脚本输出为准”在 SKILL.md 中明确“不要虚构脚本输出必须以实际执行结果为准”API 连接失败或超时API Key 未配置、服务不可用、网络策略限制检查环境变量是否生效确认 API 服务状态重试或切换网络环境这里重点展开 Windows 下最常见的opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称问题。这个报错本质上不是 OpenCode 的问题而是 npm 全局安装的二进制文件目录没有加到系统 PATH 环境变量中。排查步骤按顺序来# 1. 确认 Node.js 已生效 node -v # 2. 查询 npm 全局安装目录 npm config get prefix假设输出是C:\Users\你的用户名\AppData\Roaming\npm那么你在 PowerShell 中检查 PATH 是否包含这个目录# 查看用户级 PATH [Environment]::GetEnvironmentVariable(Path, User)如果没有包含可以手动添加$npmPath $env:APPDATA\npm [Environment]::SetEnvironmentVariable(Path, $env:Path ;$npmPath, User)添加完成后必须重新打开一个终端窗口环境变量才会生效。重新执行opencode --version通常就能正常输出了。如果仍然失败再检查是否使用了 nvm-windows 多版本管理工具确认当前 Node 版本对应的全局目录确实在 PATH 中。6. 最佳实践与工程建议关于 Skill 的命名建议使用全小写加短横线例如code-review、commit-message、python-scaffold。不要使用空格和中文因为技能名会出现在命令行或模型上下文中特殊字符容易引入解析问题。description字段要多花心思。很多人在第一次写 Skill 时会写“用于代码审查”这样过于简单的描述。更合理的问题是模型在什么场景下应该看到这段描述并选择这个技能写description时可以带着“触发条件思维”比如description: 当用户要求审查 Python 代码、查找 TODO/FIXME、检查语法错误或提交合并请求前需要质量评估时使用。不适用于代码重构和功能开发。这样的描述既说明了何时使用又排除了不适用场景模型误触发的概率会大大降低。一个 Skill 只聚焦一个任务。如果代码审查和单元测试生成放在同一个 SKILL.md 里模型执行时容易“串味”一会儿做审查一会儿又去生成测试。拆成两个独立 Skills每个文件短小精悍执行质量更高。Skill 文件不是越长越好几十行能说清楚的事情不要写成几百行。辅助脚本要兼容多平台。上面示例中的scan.py用了 Python天然跨平台如果你使用 Shell 脚本一定要考虑到 Windows 环境没有 bash 的情况。团队即使都在同一个系统上也建议在脚本里处理路径中文、编码等问题避免 Agent 因为编码报错而中断。安全边界必须在 SKILL.md 里明确写出来。比如技能允许调用脚本但不允许执行高风险删除命令技能可以读取文件但不要把密钥写入日志。模型在缺乏约束时可能会做出激进操作所以“哪些不能做”和“应该怎么做”同样重要。技能要纳入版本控制。.opencode/目录应该和业务代码一起提交到 Git这样团队成员 clone 项目后就拥有一致的 AI 工作流。技能更新时建议通过 Git 历史保留每次改动的记录方便回滚。定期回看技能的实际使用效果。Agent Skills 不是写一次就一劳永逸模型版本升级、项目规范调整都可能让旧技能不再适配。建议每个迭代周期结束后把技能效果、模型错误操作、团队成员反馈记录下来持续修订 SKILL.md。这本质上和代码重构一样是持续投入。在权限配置方面遵循最小权限原则。生产环境或敏感项目中不要给 AI 工具过高的文件系统权限更不要把生产密钥写进环境变量后让 AI 自由读取。必要情况下可以先在预发布环境验证技能指令再带到生产项目中使用。7. 总结与下一步这篇文章从 Agent Skills 的概念讲起通过 OpenCode 这套开源工具完成了环境搭建、SKILL.md 格式解析、代码审查技能实战和常见问题排查。如果你跟着流程走完现在应该已经拥有一个属于自己的、可以复用的代码审查技能。下一步可以往这些方向拓展先为高频重复动作编写更多 Skills比如“生成 Conventional Commit 提交信息”“生成单元测试”“整理项目文档”然后研究 OpenCode 的权限模型和自定义命令把常用技能固化成一键触发有条件的话尝试在团队内部统一技能目录模板让新成员 clone 项目后直接用同一套标准与 AI 协作。最后分享一条实际体会第一次做 Agent Skills 时不要一上来就写大型技能。挑一个你每天都会重复的任务比如“给本次改动写 commit message”把之前反复叮嘱 AI 的话整理成 SKILL.md整个过程不超过半小时。这个最小改动带来的体验提升往往比换一个更贵的模型明显得多。先把高频小任务稳定下来再逐步扩大技能覆盖面这条路走起来最顺。
