Agent Skills实战：从Claude Code到可复用技能开发

Agent Skills 是当前从“会用 AI 问答”走向“会开发 Agent”的关键中间层。很多人已经能把 Claude Code 和 Codex 用得很顺生成代码、改 bug、跑测试、写文档都没问题但一旦想把能力沉淀成团队能复用、项目能扩展的体系就会发现问题不在模型而在组织方式。这篇文章按实际落地顺序拆一遍先分清 Agent、Agent Skills、Claude Code、Codex 的边界然后完成安装和基础验证接着从零开发一个可复用的 Skill再讲技能体系怎么拆分、怎么批量化和多模型接入最后给一份排错清单。适合刚开始接触 AI 编程、想直接进入 Agent 开发的人也适合已经在用 CLI 工具、想把临时用法整理成正式技能库的人。最值得先记住的一点Agent Skills 不复杂但它要求换一种思考方式——从“让 AI 做一件事”变成“把一类事的做法写成规范让 Agent 按规范执行”。1. 先分清四件事Agent、Agent Skills、Claude Code、Codex 各自负责什么1.1 Agent 不只是聊天窗口而是“能执行任务的执行者”Agent 这个词现在用得很多但在实际开发里我们说的 Agent 通常指一个能自主完成任务的执行者。它的组成大致是一个大模型负责理解和决策一组工具负责读写文件、执行命令、调用接口一段上下文记录任务目标和中间结果再配上一套执行规则告诉它遇到什么情况怎么办。Claude Code 和 Codex 都属于这一类落地形态。它们在终端里运行能读项目代码、改文件、执行测试命令还能调用外部 API。它们的区别更多在默认模型、配置方式和生态上而不是“谁能用谁不能用”。实际项目中很多人会两个都装按任务类型选一个跑。理解这一点很重要。因为很多人习惯把 AI 当聊天窗口问一句“怎么优化这段代码”然后复制粘贴结果。这不算 Agent 开发。Agent 开发是让模型在明确规则下自己完成“读代码、分析、改代码、跑测试、汇报结果”这条链路。1.2 Agent Skills在 Prompt 和完整自动化之间加一层“可复用规范”Agent Skills 可以理解为“写给 Agent 看的执行说明书 工具包”。它通常是一个目录里面包含一个说明文件、若干脚本、示例输入和输出。收到任务时Agent 会判断当前任务是否匹配某个技能匹配就读取技能内容按里面的规则执行。它和普通 Prompt 的区别是关键。Prompt 是一次性的你在对话里写“请按 Google 风格审查代码”这次有效下次又得重新写。Skill 是结构化的它把审查规则、运行脚本、输出格式都放在固定位置可以被版本管理可以被多个项目复用还可以单独测试。它和 MCP 也有区别。MCP 提供的是“工具接口”让 Agent 能调用某个外部能力Agent Skills 提供的是“任务执行流程”告诉 Agent 遇到某类任务时应该分几步做、用什么脚本、输出什么结果。两者不冲突甚至经常配合Skill 里定义流程流程中调用 MCP 工具去拿数据。1.3 Claude Code 和 Codex两种载体各有各的脾气Claude Code 是命令行形态的编程 Agent默认使用 Claude 系列模型。它的特点是交互体验完整适合在项目里直接帮你看代码、改代码、跑测试。Codex 同样是命令行形态的编码 Agent默认使用 OpenAI 系列模型适合处理类似的编码任务。实际使用时这两个工具都可以通过环境变量或配置文件切换到其他兼容接口。我一般建议先选一个工具跑通完整流程再装另一个做对比。不要两个环境同时开着一模一样的实验日志混在一起很难排查。1.4 谁适合学这套体系谁可以先放一放这套体系适合三类人已经在用 AI 编程、但每次都要反复写同样指令的人团队里想把优秀做法沉淀下来、让新成员也能用的人需要处理批量重复任务、想让 AI 自动跑完的人。如果只是偶尔用 AI 问答或者手上任务没有稳定边界暂时不需要建技能库。先把手动流程跑熟再考虑封装。技能库是需要维护的没人维护的技能会慢慢变成没人看的文档。2. 环境准备从安装到能跑通第一次调用2.1 装之前先确认四件基础条件先检查环境再装 CLI这是避免“装完跑不起来”最有效的方式。第一Node.js 环境。Claude Code 和 Codex CLI 通常都通过 npm 安装所以先确认 node 和 npm 可用。在终端执行node -v npm -v如果 npm 版本过低或 Node 版本太老很多依赖安装会失败。建议使用 LTS 版本。第二终端工具。Windows 上优先用 PowerShell 或 Windows TerminalmacOS 和 Linux 用系统自带终端就行。后续所有命令都建议在项目目录下执行不要在系统目录里跑避免权限问题。第三账号和密钥。CLI 工具通常需要登录或者配置 API Key。不同工具的配置方式不一样有的通过交互式登录有的读环境变量。安装前先确认手里有可用的账号或密钥。第四磁盘空间和网络。CLI 本身不大但模型能力来自远程服务网络稳定性直接影响超时表现。如果网络波动大先别急着怪工具先看服务是否可达。为什么先检查这些因为很多报错根本不是工具的问题而是 PATH 没生效、Node 版本太低、密钥没配置。越早确认后面排错越少。2.2 Claude Code 安装一条命令装完重点验证 CLI 能被终端找到以常见安装方式为例安装命令类似npm install -g anthropic-ai/claude-code装完先验证版本claude --version能输出版本号说明 CLI 已经被终端找到。接着在项目目录运行 claude进入交互界面让它执行一个简单任务。如果是在 VS Code 里使用直接在编辑器自带终端里运行同样命令即可也可以配置成快捷键。这里不展开扩展配置因为不同版本的入口不一样。第一次使用建议先跑最小任务比如“读取当前目录下的文件列表”。这一步能同时验证登录状态、模型调用和日志输出是否正常。2.3 Codex CLI 安装同样走 npm但更容易遇到“找不到 CLI”的报错Codex 的安装思路类似npm install -g openai/codex codex --version但 Codex 常见的坑是“CLI 装好了其他工具却找不到它”。比如编辑器插件报错unable to locate the codex cli binary. set codex_cli_path or ensure the elec...这类报错的意思是插件在固定位置找不到 codex 可执行文件。处理顺序我建议这样先在终端确认 codex 命令能执行能看到版本号。找到 npm 全局可执行目录执行 npm prefix -g 查看。把这个目录加入系统 PATH或者把 codex 所在目录的完整路径记下来。如果插件支持显式配置把 codex_cli_path 设置成真实路径。注意环境变量名大小写。有的工具用全大写有的用全小写报错信息里写的是哪个就按哪个。这种问题 90% 是路径问题不是程序问题先把路径对齐再往下看。2.4 第一次调用验证不要直接跑大任务两个 CLI 都装好后不要急着跑复杂任务。我一般会先做一次最小链路验证运行工具、发起一个几十字就能完成的任务、查看返回结果和日志。如果卡住先看网络到模型服务的连通性如果报 “the agent execution provider did not respond in time” 这类超时错误说明调用链中某个环节没在预期时间内返回。常见原因有服务端负载高、网络波动、任务上下文太大、当前模型不支持某些请求参数。这里不要急着调并发数。并发是后面批量阶段的事先保证单条调用稳定。单条都不稳定开再大的并发只会得到一堆超时日志。3. 开发第一个 Skill把“会用的 AI”变成“能复制的技能”3.1 Skill 的标准目录结构一个 Skill 本质上是一个目录。目录里通常有三样东西说明文件、脚本、示例。以代码审查技能为例review-code/ ├── SKILL.md ├── scripts/ │ └── check_style.py └── examples/ └── sample_input.pySKILL.md 是核心。它负责告诉 Agent这个技能解决什么问题什么时候该用、什么时候不该用输入是什么执行步骤是什么输出格式是什么。脚本是具体执行逻辑示例则用来测试和展示效果。3.2 写一个“代码审查技能”的完整过程第一步先写 SKILL.md。里面要写清楚审查规则。比如检查未捕获异常、检查硬编码的敏感信息、检查重复代码、检查明显错误然后按严重程度输出问题列表。第二步写一个简单脚本做静态检查。Python 或者 shell 都行关键是脚本本身能独立运行不依赖模型。这样即使 Agent 不介入你也能手动验证脚本对不对。第三步放一个示例文件方便测试。示例不用大几行代码能触发两三个问题就够。示例 SKILL.md 可以这么写--- name: review-code description: 对指定源码文件执行基础代码审查输出按严重程度分级的检查结果。 --- 当用户要求审查代码、检查代码质量或评估代码风险时使用本技能。 输入 - 目标文件路径 执行步骤 1. 读取目标文件 2. 运行 scripts/check_style.py 并传入文件路径 3. 将脚本输出整理为问题列表 输出格式 问题列表按高、中、低三级排列每条包含文件位置和修改建议。注意这只是示例具体字段名要以你使用的工具支持为准。不同的 Agent 工具对 SKILL.md 的解析不完全一样。3.3 为什么 SKILL.md 一定要写“什么时候不要用”这一点很多人会忽略。如果不写边界Agent 可能把不相关的任务也套进这个技能里导致误用。比如你做了一个“代码审查技能”用户只是问一句“这段代码是什么意思”Agent 如果强制走审查流程输出就会很怪。所以在 SKILL.md 里要明确写当用户只寻求解释、不做改动审查时不要使用本技能。边界写得越清楚Agent 的调用越准确。3.4 验证技能是否能被正确加载技能写完后先手动运行脚本确认脚本本身没有问题。然后让 Agent 调用技能比如输入“请审查 examples/sample_input.py”。对比 Agent 的输出和脚本输出看它是否真的按 SKILL.md 的流程执行了。这里有个小技巧你可以直接问 Agent“你准备怎么完成这个任务”。如果它能说出技能的目录结构、脚本位置和输出格式说明技能被正确读取了。如果它还在泛泛回答多半是技能目录路径不在它的搜索范围内或者目录命名不被支持。4. 设计技能体系可复用、可扩展的拆分与组合方法4.1 拆技能的核心原则单一职责 明确输入输出一个技能只做一件事。代码审查就只做代码审查提交信息生成就只做提交信息生成变更日志整理就只做变更日志整理。不要做一个“开发助手大技能”把所有规则塞进去。拆技能的时候明确输入和输出。输入可以是一个文件路径、一段文本或者一个 JSON 参数输出可以是问题列表、生成文档、修改后的文件。边界越清晰Agent 越容易判断该不该用这个技能脚本也越容易单独测试。4.2 让技能可以组合使用单个技能跑通后可以组合成一条链路。比如发布流程可以拆成三个技能生成提交信息、整理变更日志、生成发布说明。Agent 在一个任务里按顺序调用它们中间通过文本文件或标准输出来传递数据。组合的时候注意一件事保持技能之间尽量独立。技能 A 不要直接依赖技能 B 的脚本而是通过标准输出或文件传递结果。这样哪个环节出问题单独重跑那个技能就行。技能调用技能的嵌套链虽然看起来“智能”实际会放大排错难度。新手阶段建议保持一层调用不要做深链。4.3 可扩展性的落地方式命名空间、版本、仓库管理等技能数量超过五个就要开始管理了。我建议用命名空间组织目录skills/ ├── review/code/ ├── repo/changelog/ ├── docs/generator/ └── test/runner/命名空间按场景分不按工具分。这样以后从 Claude Code 切到 Codex或者两个工具混用目录结构都不用大改。每个 SKILL.md 里加版本字段改动后升版本。技能目录单独放一个仓库项目里通过符号链接或配置指向。这样团队更新技能时不用同步复制文件而是拉取固定版本。还有一个容易被忽略的点整个团队统一脚本语言。如果你用 Python 写技能脚本别人也应该能用 Python 维护。混合用 shell、Python、Node 会提高维护成本。4.4 跨工具复用的边界先保证一个工具稳定再谈兼容Claude Code 和 Codex 对技能格式的支持不完全一样。同一个技能目录可能在一个环境里工作得很好在另一个环境里 Agent 根本没读取。解决办法是以你主用的工具为准构建技能在另一个工具里做最小验证比如只验证“技能能不能被发现、能不能执行核心脚本”。不要一开始就追求同时兼容所有 Agent。先让内部团队在一个工具上跑顺再逐步扩展到其他环境。追求过度通用往往会两头都伺候不好。5. 实战进阶批量任务、多模型接入和接口化5.1 批量任务从单条跑通到并发控制单个技能稳定之后才适合做批量。批量处理多个文件、多个项目、多个仓库时按这个顺序推进先跑 1 条再跑 5 条再跑全量。批量任务最常见的问题是输出命名冲突和失败重试。输出文件一定要按输入文件命名比如 input_001.py 对应 report_input_001.md避免重复跑或并发跑时相互覆盖。每处理一条记录就把结果写进日志。失败的任务单独记录到一个失败清单里全部跑完后针对失败清单重跑不要整个