OpenCode + Agent Skills：从零搭建可复用的代码质检助手-北京尧图网络

最近在帮团队做 AI 编码工具的选型和落地时我发现一个普遍现象很多开发者已经在用 OpenCode 这类终端型 AI Agent但实际用法还停留在“把需求粘贴给模型等它返回一大段代码再手动复制到文件里”。这本质上还是聊天式编程只是把搜索引擎换成了大模型效率提升有限也没有真正发挥 Agent 的自主性。真正的 Agent 式编程是让 AI 不只会“说代码”还会“改代码”“跑代码”“查代码”。它应该能自己读取项目目录、理解现有模块之间的依赖关系、修改文件、运行测试、再根据报错信息自我修正。对于长期维护的项目来说这种能力比“一次生成 200 行代码”更有价值。而要把这种能力稳定复用到不同项目、不同团队流程中就需要一个关键的设计把能力沉淀成可复用的 Skills。这就是本文要展开的主题。下文会先讲清楚 Agent Skills 是什么、和 Agent 有什么区别再介绍 OpenCode 这个开源终端 Agent 的安装和使用方式最后用一套完整的项目实战演示如何从零搭建“带 Skills 的代码质检助手”。无论你是刚接触 AI 编程的新手还是已经在团队里推广 AI 编码工具的负责人都能从这套流程里拿到可以直接落地的方案。1. 背景与核心概念1.1 从“聊天式编程”到“Agent 式编程”先做一个通俗类比。如果把 Agent 理解成一个刚入职的程序员它的大模型能力是“聪明的大脑”而 Skills 就是它的“专业技能包”。一个没有 Skills 的 Agent只知道通用知识你让它写测试它会写得很散你让它做代码审查它会从头到尾泛泛而谈。而当你给 Agent 挂上“测试编写”“代码审查”“安全巡检”这些 Skills 之后它就相当于经过了对应岗位的培训知道先做什么、后做什么、按什么标准输出、哪些坑绝对不能踩。专业一点说Agent Skills 是一组可复用的能力定义通常由一个说明文件例如 SKILL.md加上若干辅助脚本、依赖描述组成。说明文件里写清楚技能的用途、触发条件、执行步骤、输出格式和约束条件辅助脚本则承担那些不适合让模型“凭空发挥”的确定性操作比如扫描文件、统计指标、调用静态检查工具等。Skills 解决的核心问题有三个。第一是稳定性同样的任务用 Skill 约束执行流程后输出质量更可控不会每次换一种风格。第二是复用性一个写好的 Skill 可以在多个项目、多个场景中重复使用不需要每次重新描述需求。第三是专业性Skills 可以把团队内部的代码规范、审查清单、发布流程等隐性知识显性化变成 Agent 能遵循的操作手册。1.2 什么是 Agent Skills这里要回一个很多初学者都会问的问题Agent Skills 和 Agent 到底有什么区别为了讲清楚我们需要把几个容易混淆的概念拆开看概念定位职责举例Agent执行主体负责理解目标、拆解任务、决策下一步动作一个运行在终端里的 AI 编程助手Tool / MCP原子能力完成明确、单一的外部操作执行 Shell 命令、读取文件、调用搜索引擎Skill复合能力把“提示词多步流程脚本工具”组合成完整工作方式“代码审查”“单元测试编写”“安全巡检”Agent 是“大脑和调度器”它决定什么时候调用什么能力Tool 是“手脚”负责执行单一动作Skill 则是“套路”它把一系列动作和判断标准编排成一套完整的工作流。Skill 内部可能用到多个 Tool也可能调用本地脚本但这些细节对 Agent 是透明的。Agent 只需要知道“我有一个代码审查 Skill遇到审查需求时使用它”。搞清楚这个区分非常重要。如果你把 Skills 理解成“更智能的提示词”就会忽略脚本和工具的作用如果你把 Skills 理解成“单个函数”又会忽略它作为工作流编排的价值。正确的理解是Skills 是介于提示词和完整 Agent 之间的中间层它让能力沉淀、复用和传播成为可能。从本质上说Skills 回答的是“一个 Agent 应该以什么方式工作”而不是“Agent 应该调用哪个接口”。1.3 OpenCode开源终端生态里的新选择这里再介绍本文实操部分的主角——OpenCode。OpenCode 是一款运行在终端里的开源 AI 编码 Agent社区中常被称为“Claude Code 的开源替代”。它最大的特点是把 Agent 的自主能力直接搬进命令行你可以在项目目录中启动它它会自动读取仓库结构、跟踪文件变更、执行命令并根据执行结果决定下一步操作。相对 IDE 插件或网页工具终端型 Agent 有几个明显优势。第一是环境一致你平时怎么在终端里跑测试、跑构建Agent 也怎么跑不需要额外配置一套图形环境。第二是轻量不依赖某个特定编辑器SSH 到服务器或远程开发机也能使用。第三是便于自动化终端本身就是脚本和 CI 流程的天然组成部分Agent 的输入输出更容易被包装成自动化流水线。需要说明的是OpenCode 本身是通用 Agent它不限制你如何组织 Skills。我们完全可以用一套约定好的目录结构和指令文件让 OpenCode 在每次会话中自动加载并使用项目里的 Skills。这种“通用 Agent 自定义 Skills”的组合方式正是当前 AI 编程落地中最实用、迁移成本最低的玩法。另外Agent Skills 的应用范围也不只在编程领域把它用于文献整理、论文写作等方法研究任务的案例也在增多原理是相通的本文后续会以代码场景为主线展开。2. 环境准备与版本说明2.1 基础环境要求在开始安装之前先确认本机具备以下基础条件。操作系统方面Windows 10/11、macOS 或主流 Linux 发行版均可终端方面Windows 建议使用 PowerShell 或 Windows TerminalmacOS 和 Linux 使用系统默认终端即可。因为 OpenCode 依赖 Node.js 生态如果你计划通过 npm 安装建议提前装好 Node.js 18 及以上版本并用node -v确认版本号。此外OpenCode 需要读取 Git 仓库信息所以 Git 也是必备组件。还需要准备一个可用的模型服务。OpenCode 自身不内置大模型它需要调用 Anthropic Claude、OpenAI 或其他兼容接口来获得推理能力。这里要特别提醒模型服务的接入方式和可用模型列表随时可能调整不要在网上找一篇旧教程就照抄而是以官方文档为准。本文的示例以常见环境为例重点演示配置思路具体版本请根据你的项目实际情况调整。2.2 安装 OpenCodeOpenCode 最常见的安装方式是通过 npm 全局安装。在终端执行# 通过 npm 全局安装 npm install -g opencode-ai如果你使用的是 Bun 这类更快的包管理器也可以换成bun install -g opencode-ai注意不同版本的包名可能调整安装前务必确认官方文档。安装完成后可以先确认命令是否可用opencode --version如果正常输出版本号说明安装成功如果提示“无法将 opencode 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”Windows或者command not foundmacOS/Linux说明 npm 全局安装目录没有加入 PATH第 5 章会专门讲这一类问题的排查方法。2.3 配置模型服务与 API KeyOpenCode 本身只是 Agent 运行框架真正干活的大模型需要你提供接入凭证。常见的做法是通过环境变量注入 API Key以 Anthropic Claude 为例# Linux / macOS export ANTHROPIC_API_KEY你的密钥 # Windows PowerShell $env:ANTHROPIC_API_KEY你的密钥如果你使用的是 OpenAI 兼容接口或本地模型通常还需要配置接口地址和模型名称。不同版本支持的配置字段不一样建议运行opencode后进入交互界面查看自带的帮助信息或者查阅官方文档中的配置说明。这里也要提醒一句API Key 属于敏感信息不要写进项目仓库也不要粘贴到公共聊天窗口。推荐的做法是把密钥放在本地环境变量文件里并确保该文件被.gitignore忽略。2.4 在项目目录中启动安装配置完成后进入一个测试项目目录直接运行cd /path/to/your-project opencode正常情况下会进入一个交互式对话界面Agent 会自动分析当前目录结构。你可以先问它一个简单问题测试连通性例如“请描述一下当前项目的目录结构和主要模块”。如果模型正常回答说明环境已经通了可以进入后续的 Skills 实战环节。3. Agent Skills 核心原理拆解3.1 Skills 的本质提示词工具工作流在设计 Skills 之前要先理解它的三层结构。最底层是提示词它告诉模型“你是谁、要做什么、按什么标准输出”中间层是工具它让模型具备读写文件、执行命令、运行脚本等实际能力最上层是工作流它把多个步骤编排成固定流程避免模型自由发挥。用一个代码审查 Skill 举例提示词部分会写明“你是一名严谨的代码审查员重点关注异常处理、安全漏洞、可读性”工具部分提供“读取目标文件”“运行静态检查脚本”的能力工作流部分则规定“先扫结构再审逻辑最后输出问题清单”。三者缺一不可。只有提示词输出会不稳定只有工具模型不知道何时该用没有工作流步骤顺序可能每次都不一样。在落地时很多团队会踩一个坑只写了一段漂亮的提示词就以为创建了 Skill。实际上真正让 Skill 产生确定性价值的是脚本和工作流。把可程序化判断的部分交给脚本把需要理解和判断的部分交给模型这种“人机分工”才是 Skills 的核心设计思想。尤其是当项目规模变大之后脚本负责的静态扫描能覆盖模型容易遗漏的角落而模型负责的业务理解又是脚本做不到的两者互补才能形成可靠的质检能力。3.2 SKILL.md 的典型结构虽然没有绝对统一的格式但一个书写良好的 Skill 说明文件通常包含以下部分name技能名称例如code-reviewerdescription技能用途说明什么场景下使用它适用场景明确触发条件执行步骤按顺序列出操作流程输出格式规定最终结果的呈现方式约束与红线说明哪些事不能做依赖与脚本说明需要哪些辅助脚本或第三方工具。下面看一个最小示例--- name: code-reviewer description: 对目标代码文件进行结构化审查输出问题清单和修改建议。 --- # 代码审查 Skill ## 适用场景 - 提交 Pull Request 前的自检 - 历史代码质量巡检 - 重构前后的风险确认 ## 执行步骤 1. 确定待审查文件列表 2. 运行 scripts/review.py 进行静态扫描 3. 结合扫描结果逐文件阅读业务逻辑 4. 按严重程度输出问题清单 ## 输出格式 - 严重问题可能导致线上故障或安全风险 - 一般问题影响可维护性或存在边界缺陷 - 建议项风格、命名、注释等优化建议 ## 红线 - 不要在审查报告中编造不存在的风险 - 不要直接修改源码除非用户明确要求这里的重点是把步骤、格式和红线写清楚让模型在每次调用时行为一致。description 字段尤其重要它是 Agent 决定“要不要使用这个 Skill”的依据。如果 description 写得含糊模型就可能在不需要时误用或者真正需要时又漏掉。3.3 给 Skill 配一个辅助脚本很多 Skill 只靠模型“读代码”是不够的需要脚本做确定性扫描。比如下面这个 Python 脚本用于扫描代码中的硬编码敏感信息和其他常见问题# 文件路径skills/code-reviewer/scripts/review.py import sys from pathlib import Path def scan_file(file_path: Path) - list[str]: 扫描单个文件返回发现的问题列表。 issues [] try: lines file_path.read_text(encodingutf-8).splitlines() except UnicodeDecodeError: issues.append(f{file_path}: 文件编码不是 UTF-8建议统一编码) return issues for idx, line in enumerate(lines, 1): stripped line.strip() low stripped.lower() # 检查疑似硬编码密钥 if password in low or secret in low or token in low: if in stripped and not low.startswith(#): issues.append(f{file_path}:{idx} 疑似硬编码敏感信息) # 检查过宽的 print 调试语句 if stripped.startswith(print(): issues.append(f{file_path}:{idx} 疑似遗留调试输出) return issues def main(root: str) - None: target Path(root) files [p for p in target.rglob(*.py) if .venv not in p.parts] all_issues [] for file in files: all_issues.extend(scan_file(file)) if all_issues: print(\n.join(all_issues)) else: print(未发现明显问题) if __name__ __main__: root sys.argv[1] if len(sys.argv) 1 else . main(root)这个脚本的作用不是替代模型而是给模型提供“可信的事实依据”。模型可以运行它拿到扫描结果再结合自己对业务逻辑的理解生成最终的审查报告。这种组合方式比单纯让模型“凭感觉审查”可靠得多因为它把“是否有硬编码密钥”“是否遗留调试输出”这类可以确定性判断的问题从模型的主观猜测中剥离了出来。3.4 从 Skill 到 Agent组合的工作方式理解了单个 Skill 之后再来看它如何融入 Agent。一个完整的 Agent 编码助手通常由四层组成基础模型负责理解和生成Agent 运行框架也就是 OpenCode负责读文件、执行命令、管理多轮对话Skill 定义是项目内可复用的能力包最后是项目指令告诉 Agent 项目背景、代码规范以及需要优先使用哪些 Skill。项目指令文件可以是一个简单的 AGENTS.md例如# 项目级 Agent 指令你是本项目的 AI 开发助手请始终遵循以下约定 1. 修改代码前先阅读相关文件的完整内容。 2. 涉及代码审查时必须使用 code-reviewer Skill。 3. 涉及新增测试时必须使用 test-writer Skill。 4. 输出代码时必须附带简要说明不要只给代码。当用户输入“帮我审查一下 src 目录的代码”时OpenCode 会读取 AGENTS.md发现审查任务应使用code-reviewerSkill然后自动去skills/code-reviewer/读取 SKILL.md按其中定义的流程执行。这样每次审查的风格和质量都是稳定的。“AGENTS.md 约定目录结构 SKILL.md 定义”三者配合就是一套不依赖特定工具、可迁移到任何 Agent 环境的轻量方案。4. 完整实战基于 OpenCode 搭建带 Skills 的代码质检助手4.1 项目结构设计接下来我们用一个完整的示例项目把前面的原理串起来。假设有一个小型 Python 项目里面有一些待审查的业务代码我们要为它搭建一个“代码质检助手”包含两个 Skillscode-reviewer负责代码审查test-writer负责单元测试编写。项目结构如下quality-demo/ ├── src/ │ ├── utils

OpenCode + Agent Skills：从零搭建可复用的代码质检助手

相关推荐

AI智能体预算耗尽困局：优先级调度与熔断自救方案

智能体AI实战指南：从概念原理到工作流搭建

大模型驱动电竞赛评文本结构化抽取实战指南

更多资讯

燕郊电工证费用多少怎么报名学历不高也能行

工地太忙根本没时间复习考试？国家免费电工证培训+电子证书全流程攻略

中牟电工证分类有几种网上查询实操考试心里没底怕挂科怎么破

职业鉴定中心查电工证怎么考

寿县怎么报名考电工证官方报名入口在哪儿怎么考过实操考试

编号s开头的电工证怎么考？学历不高怕报不上名？考前押题能帮你

今日更新

安监局电工证分数查询怎么查才能知道含金量高不高

新疆电工作业干活累吗良心建议助你避开考不过的坑

中牟县电工证怎么报名外省证能转吗

本周精选

安监局电工证分数查询怎么查才能知道含金量高不高

新疆电工作业干活累吗良心建议助你避开考不过的坑

中牟县电工证怎么报名外省证能转吗

本月热门

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

读完文章，想聊聊您的网站？

相关推荐

AI智能体预算耗尽困局：优先级调度与熔断自救方案

智能体AI实战指南：从概念原理到工作流搭建

大模型驱动电竞赛评文本结构化抽取实战指南

更多资讯

燕郊电工证费用多少 怎么报名学历不高也能行

工地太忙根本没时间复习考试？国家免费电工证培训+电子证书全流程攻略

中牟电工证分类有几种网上查询实操考试心里没底怕挂科怎么破

职业鉴定中心查电工证怎么考

寿县怎么报名考电工证官方报名入口在哪儿怎么考过实操考试

编号s开头的电工证怎么考？学历不高怕报不上名？考前押题能帮你

今日更新

安监局电工证分数查询怎么查才能知道含金量高不高

新疆电工作业干活累吗 良心建议助你避开考不过的坑

中牟县电工证怎么报名外省证能转吗

本周精选

安监局电工证分数查询怎么查才能知道含金量高不高

新疆电工作业干活累吗 良心建议助你避开考不过的坑

中牟县电工证怎么报名外省证能转吗

本月热门

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

读完文章，想聊聊您的网站？

燕郊电工证费用多少怎么报名学历不高也能行

新疆电工作业干活累吗良心建议助你避开考不过的坑

新疆电工作业干活累吗良心建议助你避开考不过的坑