之前做 AI 辅助开发时我更多是把 Claude、GPT 当成一个“加强版对话窗口”让它写函数、补注释、解释报错。但真正进入 Agent 开发之后我发现最核心的差距不是模型选哪个而是有没有一套“能让 Agent 稳定复用能力”的机制。这段时间在 Claude Code 和 Codex 之间来回切换踩了不少配置和调用层面的坑也逐步把零散的 Prompt 整理成了可复用的技能包。这篇文章就把我从“会用 AI”到“开发 Agent Skills”的完整经验整理出来包含概念拆解、环境搭建、Skill 目录规范、两个实战案例以及高频报错的排查思路。文章内容较多建议先收藏再慢慢看。1. Agent 与 Agent Skills 核心概念梳理1.1 从 AI 对话助手到 Agent传统使用 AI 的方式是“你问我答”用户给一段 Prompt模型生成一段回复。这种方式适合写文案、改代码片段、做知识问答但无法完成多步骤任务因为模型本身不掌握文件系统、命令行和外部服务。Agent 的出现改变了这个模式。Agent 可以理解为一个具备“感知 - 决策 - 行动”闭环的智能体。它不仅能生成文本还能调用工具、读取文件、执行命令、根据运行结果调整下一步操作。比如让 Agent 完成“拉取代码、跑测试、收集失败用例、给出修复建议”这一整套流程它需要不断与环境交互而不只是输出一段建议。从这个角度看Agent 的关键能力有三个工具调用能调用外部函数或命令。上下文管理能记住任务目标和已执行步骤。自主决策能根据中间结果决定下一步动作。而要让 Agent 真正做到“稳定可用”关键不只是选哪个模型而是如何把某一类任务的执行知识固化下来这就是本文要讲的 Agent Skills。1.2 Agent Skills 是什么Agent Skills 是一套面向 Agent 的“技能封装机制”。它把某个领域的执行步骤、规则、示例、约束整理成标准的目录结构让 Agent 在遇到相关任务时可以自动加载并按照技能定义去执行。举一个容易理解的类比传统 Prompt 相当于在对话里告诉 AI“你应该怎么做”而 Agent Skill 相当于给 AI 安装一个“岗位说明书 操作手册 常用工具包”。前者是一次性的口头交代后者是可复用、可扩展、可版本管理的标准化资产。在 Claude Code 中Skills 通常表现为项目下的.claude/skills目录每个技能是一个子目录里面包含SKILL.md主文件以及其他辅助脚本、模板、资料文件。Agent 读取SKILL.md后会按照里面的指令去完成相关任务。1.3 Agent Skills 与 Tools、MCP 的区别这是最容易混淆的地方。很多开发者分不清 Agent Skills、Tools 和 MCP 有什么区别。Tools 是 Agent 可以调用的具体函数或命令比如“获取当前时间”“执行 Shell 命令”“读取文件”。它偏底层解决的是“Agent 能不能做某件事”。MCPModel Context Protocol是一种标准化协议用来让 Agent 与外部数据源、工具服务进行统一通信。它更多是解决“Agent 怎么连接到外部能力”。Agent Skills 偏高层它解决的不仅是“能不能做”和“怎么连”还包括“怎么做才符合规范和最佳实践”。一个 Skill 可以包含多个工具调用步骤、判断条件和输出格式要求。简单总结层次解决什么问题典型示例ToolsAgent 能执行哪些原子操作执行 Shell 命令、读取文件MCPAgent 如何标准化连接外部服务通过 MCP 连接数据库、GitHubAgent SkillsAgent 如何按规范完成一类任务代码审查技能、日志排查技能实际项目中三者的关系通常是Skill 在内部定义调用流程流程中可能使用 Tools也可能通过 MCP 访问外部系统。1.4 为什么需要 Agent Skills没有 Skills 的情况下也可以让 Agent 干活但存在几个明显问题每次都要重复写很长的任务指令效率低且不同人对同一类任务的描述不一致导致输出质量波动大。Prompt 里的隐性经验无法沉淀团队成员之间无法共享“如何做好代码审查”“如何排查线上故障”这类知识。当任务步骤复杂时模型可能遗漏约束条件比如忘记跑测试、忘记检查文件编码、输出的格式不符合项目规范。将执行经验封装成 Agent Skills 后团队可以把方法论固化到项目仓库中模型在需要时自动加载既能保证一致性又能持续迭代优化。2. 环境准备与版本说明在开始动手之前先把环境准备好。这里的版本信息比较多不同版本之间差异较大需要根据实际环境调整。2.1 基础运行环境我本地的环境如下供参考操作系统macOSWindows/Linux 同样支持Node.js18 及以上版本包管理器npmGit具备基本命令行使用能力终端工具建议使用支持长文本输出的终端Claude Code 和 Codex 的实际版本更新比较频繁因此本文不会写死具体版本号。你在安装时需以官方文档展示的最新版本为准本文重点演示配置思路和技能编写方法。2.2 安装 Claude CodeClaude Code 是 Anthropic 推出的终端编程助手支持在项目目录中直接启动能够读取文件结构、执行命令、调用 Skill。安装方式通常是通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后在终端输入claude即可启动交互界面。首次启动时会要求完成登录认证请根据自己的账号类型选择对应的认证方式。注意不同区域、不同订阅类型支持的模型和功能有差异具体以官方说明为准。启动成功的标志是出现可交互的命令行界面并且能够正常回答项目相关的问题。2.3 安装 CodexCodex 是 OpenAI 推出的编程 Agent 工具同样运行在终端环境中。安装命令通常为npm install -g openai/codex安装完成后在需要使用的项目目录中执行codex即可进入交互模式。Codex 支持通过配置文件指定模型来源、API 地址等参数这也是后续接入不同模型服务的入口。如果你需要使用本地模型或其他兼容接口可以查看配置文件说明将model_providers指向本地服务地址。注意模型能力差异会导致 Agent 表现不同建议使用官方推荐模型以保证技能执行效果。2.4 配置管理工具 cc-switch在实际开发中不少开发者会在 Claude Code 和 Codex 之间来回切换为了管理不同环境的配置会使用 cc-switch 这类配置切换工具。cc-switch 可以理解为一个“配置管理器”它支持维护多套 API 配置并根据需要快速切换。安装和配置的详细步骤以 cc-switch 官方文档为准。常见做法是在图形界面中添加多套配置保存后通过菜单切换。使用这类工具时务必注意不要在生产环境随意切换配置也不要把密钥明文提交到仓库。2.5 验证环境是否可用安装完成后建议先做一个最小化的环境验证。在任意项目目录下执行claude --version codex --version如果两个命令都能正常输出版本号说明基础环境已就绪。接下来可以创建一个测试目录开始编写第一个 Agent Skill。3. 理解 Skill 的组织形式与加载机制3.1 Skill 的推荐目录结构以 Claude Code 为例一个完整的 Skill 通常放在项目的.claude/skills目录下结构如下.claude/ └── skills/ └── code-review/ ├── SKILL.md ├── scripts/ │ └── review.py可选 └── references/ └── checklist.md可选每个技能目录的名称建议使用中划线分隔例如code-review、log-analysis、dependency-check。目录内部必须有SKILL.md这是一切技能定义的核心入口。SKILL.md会被 Agent 读取并解析其他辅助脚本和参考资料则按需调用。3.2 SKILL.md 的元信息格式SKILL.md不仅仅是一份 Markdown 文档它还包含一段 YAML 格式的 frontmatter用于描述技能的元信息包括技能名称、描述、使用场景等。这段元信息非常重要因为 Agent 需要通过“描述”来判断当前任务是否与某个技能匹配。一个最小化的SKILL.md示例--- name: code-review description: 用于执行代码审查任务。当用户要求检查代码质量、发现潜在缺陷、给出优化建议时使用本技能。 --- # 代码审查技能 ## 目标 ... ## 执行步骤 ...需要注意description字段要写清楚技能的能力范围和触发条件尽量使用与用户自然语言重合度高的词汇。如果描述过于模糊Agent 在遇到相关任务时可能无法正确加载该技能。3.3 Skill 的加载机制Agent 并不会一次性把所有 Skill 都读进上下文那样既浪费 token 又影响响应速度。常见的设计是“按需加载”Agent 根据当前任务的内容结合所有 Skill 的描述元信息筛选出最匹配的技能再读取对应的SKILL.md文件。因此编写 Skill 时要特别注意描述要精准便于匹配。SKILL.md 内容要结构化便于 Agent 快速提取关键步骤。大段的示例代码尽量放在 references 或 scripts 中避免主文件过长。3.4 编写 Skill 的基本原则根据实践我认为编写高质量 Skill 需要遵循下面几个原则单一职责一个 Skill 只解决一类问题。不要把“代码审查 日志分析 性能优化”塞到同一个技能里。步骤明确执行步骤要按顺序编号并给出每个步骤的输入、操作、输出。有判断条件遇到什么情况应停止遇到什么情况应切换方案需要在 SKILL.md 中写清楚。提供示例给出一两个正反示例帮助 Agent 理解输出标准。可测试技能写完后要设计一个固定的测试任务验证效果。4. 实战案例一在 Claude Code 中创建第一个 Skill这一节我们实际动手创建一个可复用的“需求拆解技能”。该技能的作用是当用户提出一个模糊的开发需求时Agent 能按照既定模板将需求拆分为背景、目标、功能列表、验收标准、技术选型建议和风险点。4.1 创建项目结构先创建项目目录mkdir -p agent-demo/.claude/skills/requirement-split cd agent-demo然后在requirement-split目录下创建SKILL.md文件。4.2 编写 SKILL.md文件路径agent-demo/.claude/skills/requirement-split/SKILL.md--- name: requirement-split description: 用于将模糊的产品需求拆解为可执行的技术开发任务。当用户提出一个新的功能想法、业务需求或者需要整理开发任务清单时使用本技能。 --- # 需求拆解技能 ## 目标 将模糊的功能描述转化为结构化的开发需求说明降低后续开发与测试的沟通成本。 ## 执行步骤 1. 提取用户原始需求中的核心意图。 2. 按照下面的模板输出需求说明。 ## 输出模板 ### 需求背景 说明该需求要解决的业务问题。 ### 需求目标 用 1-3 句话描述最终达成的效果。 ### 功能清单 - 功能点 1描述 - 功能点 2描述 ### 验收标准 - 标准 1如何验证功能是否正确 ### 技术建议 推荐技术栈和实现方案。 ### 风险点 列出可能的实现风险或依赖项。 ## 注意事项 - 如果用户给出的信息不足先向用户提问补齐关键信息不要凭空编造需求。 - 输出格式严格遵循上述模板使用中文。这个技能的核心是约束 Agent 的输出结构。没有技能时不同对话里 Agent 拆解需求的格式可能完全不同有了技能后输出格式就变得可控了。4.3 编写辅助脚本可选如果希望技能在执行时自动调用脚本可以在技能目录下增加scripts文件夹。例如创建一个简单的模板生成脚本文件路径agent-demo/.claude/skills/requirement-split/scripts/generate_template.py#!/usr/bin/env python3 # -*- coding: utf-8 -*- 根据需求关键词生成需求文档模板。 import sys def main(): keyword sys.argv[1] if len(sys.argv) 1 else 未命名需求 template f# {keyword} 需求说明 ## 需求背景 待补充 ## 需求目标 待补充 ## 功能清单 - 待补充 ## 验收标准 - 待补充 ## 技术建议 待补充 ## 风险点 待补充 print(template) if __name__ __main__: main()在SKILL.md中可以通过类似下面这样的描述来引导 Agent 调用脚本## 工具使用 当需要生成空模板时执行以下命令 python3 .claude/skills/requirement-split/scripts/generate_template.py 需求名称注意脚本路径写法要基于项目根目录并且要确保脚本具备执行权限。4.4 在 Claude Code 中测试 Skill在agent-demo目录下启动 Claude Codeclaude然后在交互界面输入类似这样的任务请帮我把“用户登录增加短信验证码”这个需求进行拆解。如果配置正确Agent 会加载requirement-split技能并按照模板输出需求文档。如果输出结构不符合预期可以检查 SKILL.md 的描述是否与任务语句匹配。4.5 运行验证预期输出应该是包含“需求背景、需求目标、功能清单、验收标准、技术建议、风险点”的结构化文档。可以对比一下有技能和没有技能时输出的差异你会发现有技能时输出内容更加稳定几乎不会漏掉关键模块。5. 实战案例二在 Codex 中复用类似技能5.1 Codex 支持自定义指令的方式Codex 同样支持项目级自定义指令。与 Claude Code 的.claude/skills目录不同Codex 通常通过项目根目录下的AGENTS.md文件来定义项目的规则、约定和任务执行流程。Codex 在启动时会读取该文件将其作为会话的长期上下文。这意味着我们可以把“需求拆解技能”的模板直接写入AGENTS.md让 Codex 在工程中也具备同样的输出规范。5.2 编写 AGENTS.md文件路径agent-demo/AGENTS.md# 项目 Agent 规则 ## 需求拆解 当用户提出新的功能需求时必须按以下模板输出 ### 需求背景 说明该需求要解决的业务问题。 ### 需求目标 用 1-3 句话描述最终达成的效果。 ### 功能清单 - 功能点 1描述 - 功能点 2描述 ### 验收标准 - 标准 1如何验证功能是否正确 ### 技术建议 推荐技术栈和实现方案。 ### 风险点 列出可能的实现风险或依赖项。 如果用户提供的信息不足以编写需求文档必须先继续提问补齐信息后再输出。这个文件的作用和SKILL.md类似但粒度上是“项目级约束”。它适合把整个项目都要遵守的规则放进去例如代码风格、提交规范、测试要求等。5.3 配置 Codex 使用不同模型来源Codex 默认使用的模型可以通过配置文件调整。常见做法是在用户目录下创建配置文件或者在项目目录中配置.codex相关文件。一个常见的场景是接入兼容 OpenAI 接口的本地模型服务。配置文件中的关键项大致如下{ model_providers: { local: { name: Local Model, base_url: http://localhost:11434/v1, env_key: LOCAL_API_KEY } }, model: local/qwen2.5-coder:latest }需要注意的是这里只是演示配置结构实际字段名和接口路径可能会随 Codex 版本变化。接入本地模型前先确认本地模型服务是否已启动以及/v1/chat/completions等接口是否可用。如果模型能力较弱技能执行效果可能不稳定建议在本地模型场景下降低任务复杂度。5.4 运行验证在agent-demo目录下启动 Codexcodex输入相同的需求请拆解“增加用户短信登录功能”的需求。Codex 在读取AGENTS.md后会按照同样的模板输出需求文档。这个案例说明了 Agent Skills 的一种跨工具迁移思路底层逻辑一致只是承载文件不同。6. 技能开发进阶与扩展6.1 多个 Skill 的组合编排在真实项目中一个任务往往需要多个技能配合。例如“开发一个登录接口”这个任务可能同时涉及“需求拆解技能”“代码审查技能”“测试用例生成技能”。组合编排的关键在于每个 Skill 的职责要清晰输入输出要明确。比如需求拆解技能输出需求文档测试用例生成技能读取需求文档生成用例。通过这种“前一个技能的输出是后一个技能的输入”的方式可以构建复杂的自动化流水线。Claude Code 支持在对话中按需加载不同技能你可以通过连续指令让 Agent 依次调用。6.2 技能与外部工具的结合Agent Skills 的能力边界可以进一步扩展。比如在 SKILL.md 中定义“当需要调用某外部服务时使用以下命令”或者通过脚本调用外部 HTTP 接口。这里的安全风险需要注意技能中的命令如果写得不够严谨Agent 可能执行预期之外的命令。建议对技能内的 Shell 命令做白名单控制并强调只能在授权的项目目录中运行。6.3 技能的版本管理与共享由于 SKILL.md 本质上是文本文件完全可以纳入 Git 版本管理。团队协作时可以把技能目录放在一个独立仓库中通过 Git 子模块或复制方式引入各个项目。版本管理的好处是技能变更可追踪。可以回溯到旧版技能进行对比。支持多团队共享一套最佳实践。6.4 与本地模型的结合场景对于一些需要数据隔离或离线开发的场景可以将 Claude Code、Codex 与本地模型结合使用。常见方案是使用 Ollama 这类本地推理工具启动模型服务然后通过配置把 API 指向本机地址。这种方案的优势是数据不外传、可以离线使用缺点是模型能力相比云端模型有一定差距Agent 在复杂任务上的表现可能下降。因此本地模型场景下建议降低单次任务复杂度。在 SKILL.md 中增加更细化的步骤。对输出结果增加校验环节。7. 常见问题与排查思路7.1 Claude Code 安装失败或命令找不到如果执行claude提示找不到命令可能有几种原因Node.js 版本过低建议升级到 18 及以上。npm 全局安装路径不在系统 PATH 中需要配置环境变量。安装过程中网络问题导致包未下载完整。排查顺序先检查 Node 版本再查看 npm 全局目录最后确认环境变量。7.2 Codex 启动时提示本地代理配置异常有网友反馈过类似这样一条报错本地代理配置失败Codex 在调用接口时请求未能正常转发。这类问题的核心通常不是模型本身的问题而是本地代理服务的地址、端口或协议与 Codex 的预期不一致。解决办法检查代理服务是否启动。核对配置文件中的base_url是否完整是否包含http://前缀。确认请求是否可以直达目标接口必要时可以先用curl做一次连通性测试。注意不要在未确认目标服务合法性的情况下随意配置代理也不要将内网地址暴露到公网。7.3 Skill 没有被 Agent 加载如果发现输入的指令符合技能描述但 Agent 仍然没有按 SKILL.md 输出可以从以下几点排查检查技能目录是否放在正确的路径下例如.claude/skills。检查 SKILL.md 的 frontmatter 是否合法YAML 格式是否出错。检查description字段是否与任务语句匹配。查看 Agent 启动日志确认有没有读取技能文件。7.4 Agent 执行过程被中断有时候 Agent 在执行多步任务时提示执行被终止。这类问题通常与以下原因有关单步执行时间过长触发了超时。命令交互等待输入但无法自动处理。脚本异常退出Agent 无法接收下一步指令。建议把长任务拆短在 SKILL.md 中要求 Agent 分阶段执行每个阶段完成后输出结果再决定是否继续。也可以适当调整超时时间但要注意不同工具版本对超时限制的差异。7.5 常见问题汇总问题现象常见原因解决思路安装后命令找不到PATH 未配置或 Node 版本过低升级 Node检查 npm 全局路径Agent 未加载技能目录路径错误或 SKILL.md 格式错误核对路径检查 YAML 格式输出格式混乱技能描述不够清晰细化 SKILL.md 步骤和模板执行中断任务过长或脚本卡住拆分任务增加阶段输出本地代理配置报错地址、协议或端口不匹配核对配置先用 curl 测试连通性不同工具行为不一致Claude Code 与 Codex 加载逻辑不同分别查看各自文档调整配置8. 最佳实践与工程建议8.1 Skill 命名与目录规划技能命名要短且语义明确推荐使用中划线命名法如code-review、db-migration、api-design。目录层级不要太深一般两层即可避免 Agent 搜索和读取文件的开销过大。8.2 保持技能文件的精简SKILL.md 不是文档网站不要把所有知识都堆进去。主文件控制在 50 到 100 行左右复杂的参考资料放到references目录中脚本放到scripts目录中。核心目的是让 Agent 快速理解“要做什么”和“按什么顺序做”而不是把大模型当浏览器用。8.3 明确限制边界在技能描述中一定要写清楚哪些事情不允许做。比如不允许执行数据库删除操作。不允许在没有测试的情况下直接修改生产配置。不允许读取项目外的敏感文件。不允许将密钥写入代码仓库。Agent 虽然不具主观恶意但它会忠实执行指令。技能里缺少安全边界就可能在自动化流程中产生风险。8.4 配置与密钥管理涉及 API Key、Token 等敏感信息时务必使用环境变量或密钥管理服务。不要把它们写进SKILL.md、AGENTS.md或其他会提交到仓库的文件中。在分享技能包时先检查是否包含敏感信息。8.5 持续迭代与效果度量Agent Skills 不是写一次就结束的。建议每次执行后记录输出质量分析哪些步骤不稳定、哪些描述有歧义然后针对性修改。可以建立一个小型测试集每次修改技能后用固定的一组任务回归测试保证效果不退化。8.6 结合项目实际选择合适的载体Claude Code 的 Skills 目录和 Codex 的 AGENTS.md 各有优势。Skills 更灵活适合“多技能按需加载”AGENTS.md 更直接适合“项目级强制规则”。实际项目中可以根据团队分工混合使用项目级通用规则写入 AGENTS.md专业技能打包为 Skills。9. 总结与后续学习建议通过这篇文章我们从概念上梳理了 Agent 与 Agent Skills 的区别搞清楚了 Skills、Tools、MCP 三者的定位在实践层面完成了 Claude Code 与 Codex 的环境搭建并用一个“需求拆解技能”走通了从 SKILL.md 编写到 Agent 加载验证的全流程。对于常见安装失败、技能未加载、执行中断、本地代理配置报错等问题也给出了具体的排查思路。接下来可以继续深入的方向有三块一是学习 MCP 协议把 Agent 连接到真实的数据库、文件服务和第三方 API二是研究多 Agent 协作模式让不同技能由不同 Agent 分工执行三是建立自己的技能库把日常开发中反复出现的工作流逐步沉淀为可复用的 Agent Skills。开发 Agent 的过程很像搭积木模型是底座技能是模块能拼出多强的系统取决于你积累了多少高质量模块以及你愿不愿意持续打磨它们。如果这篇文章对你有帮助可以收藏备用也欢迎在评论区聊聊你在 Agent 开发中踩过的坑。 Agent Skills实战：从Prompt到可复用技能包的进阶指南
之前做 AI 辅助开发时我更多是把 Claude、GPT 当成一个“加强版对话窗口”让它写函数、补注释、解释报错。但真正进入 Agent 开发之后我发现最核心的差距不是模型选哪个而是有没有一套“能让 Agent 稳定复用能力”的机制。这段时间在 Claude Code 和 Codex 之间来回切换踩了不少配置和调用层面的坑也逐步把零散的 Prompt 整理成了可复用的技能包。这篇文章就把我从“会用 AI”到“开发 Agent Skills”的完整经验整理出来包含概念拆解、环境搭建、Skill 目录规范、两个实战案例以及高频报错的排查思路。文章内容较多建议先收藏再慢慢看。1. Agent 与 Agent Skills 核心概念梳理1.1 从 AI 对话助手到 Agent传统使用 AI 的方式是“你问我答”用户给一段 Prompt模型生成一段回复。这种方式适合写文案、改代码片段、做知识问答但无法完成多步骤任务因为模型本身不掌握文件系统、命令行和外部服务。Agent 的出现改变了这个模式。Agent 可以理解为一个具备“感知 - 决策 - 行动”闭环的智能体。它不仅能生成文本还能调用工具、读取文件、执行命令、根据运行结果调整下一步操作。比如让 Agent 完成“拉取代码、跑测试、收集失败用例、给出修复建议”这一整套流程它需要不断与环境交互而不只是输出一段建议。从这个角度看Agent 的关键能力有三个工具调用能调用外部函数或命令。上下文管理能记住任务目标和已执行步骤。自主决策能根据中间结果决定下一步动作。而要让 Agent 真正做到“稳定可用”关键不只是选哪个模型而是如何把某一类任务的执行知识固化下来这就是本文要讲的 Agent Skills。1.2 Agent Skills 是什么Agent Skills 是一套面向 Agent 的“技能封装机制”。它把某个领域的执行步骤、规则、示例、约束整理成标准的目录结构让 Agent 在遇到相关任务时可以自动加载并按照技能定义去执行。举一个容易理解的类比传统 Prompt 相当于在对话里告诉 AI“你应该怎么做”而 Agent Skill 相当于给 AI 安装一个“岗位说明书 操作手册 常用工具包”。前者是一次性的口头交代后者是可复用、可扩展、可版本管理的标准化资产。在 Claude Code 中Skills 通常表现为项目下的.claude/skills目录每个技能是一个子目录里面包含SKILL.md主文件以及其他辅助脚本、模板、资料文件。Agent 读取SKILL.md后会按照里面的指令去完成相关任务。1.3 Agent Skills 与 Tools、MCP 的区别这是最容易混淆的地方。很多开发者分不清 Agent Skills、Tools 和 MCP 有什么区别。Tools 是 Agent 可以调用的具体函数或命令比如“获取当前时间”“执行 Shell 命令”“读取文件”。它偏底层解决的是“Agent 能不能做某件事”。MCPModel Context Protocol是一种标准化协议用来让 Agent 与外部数据源、工具服务进行统一通信。它更多是解决“Agent 怎么连接到外部能力”。Agent Skills 偏高层它解决的不仅是“能不能做”和“怎么连”还包括“怎么做才符合规范和最佳实践”。一个 Skill 可以包含多个工具调用步骤、判断条件和输出格式要求。简单总结层次解决什么问题典型示例ToolsAgent 能执行哪些原子操作执行 Shell 命令、读取文件MCPAgent 如何标准化连接外部服务通过 MCP 连接数据库、GitHubAgent SkillsAgent 如何按规范完成一类任务代码审查技能、日志排查技能实际项目中三者的关系通常是Skill 在内部定义调用流程流程中可能使用 Tools也可能通过 MCP 访问外部系统。1.4 为什么需要 Agent Skills没有 Skills 的情况下也可以让 Agent 干活但存在几个明显问题每次都要重复写很长的任务指令效率低且不同人对同一类任务的描述不一致导致输出质量波动大。Prompt 里的隐性经验无法沉淀团队成员之间无法共享“如何做好代码审查”“如何排查线上故障”这类知识。当任务步骤复杂时模型可能遗漏约束条件比如忘记跑测试、忘记检查文件编码、输出的格式不符合项目规范。将执行经验封装成 Agent Skills 后团队可以把方法论固化到项目仓库中模型在需要时自动加载既能保证一致性又能持续迭代优化。2. 环境准备与版本说明在开始动手之前先把环境准备好。这里的版本信息比较多不同版本之间差异较大需要根据实际环境调整。2.1 基础运行环境我本地的环境如下供参考操作系统macOSWindows/Linux 同样支持Node.js18 及以上版本包管理器npmGit具备基本命令行使用能力终端工具建议使用支持长文本输出的终端Claude Code 和 Codex 的实际版本更新比较频繁因此本文不会写死具体版本号。你在安装时需以官方文档展示的最新版本为准本文重点演示配置思路和技能编写方法。2.2 安装 Claude CodeClaude Code 是 Anthropic 推出的终端编程助手支持在项目目录中直接启动能够读取文件结构、执行命令、调用 Skill。安装方式通常是通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后在终端输入claude即可启动交互界面。首次启动时会要求完成登录认证请根据自己的账号类型选择对应的认证方式。注意不同区域、不同订阅类型支持的模型和功能有差异具体以官方说明为准。启动成功的标志是出现可交互的命令行界面并且能够正常回答项目相关的问题。2.3 安装 CodexCodex 是 OpenAI 推出的编程 Agent 工具同样运行在终端环境中。安装命令通常为npm install -g openai/codex安装完成后在需要使用的项目目录中执行codex即可进入交互模式。Codex 支持通过配置文件指定模型来源、API 地址等参数这也是后续接入不同模型服务的入口。如果你需要使用本地模型或其他兼容接口可以查看配置文件说明将model_providers指向本地服务地址。注意模型能力差异会导致 Agent 表现不同建议使用官方推荐模型以保证技能执行效果。2.4 配置管理工具 cc-switch在实际开发中不少开发者会在 Claude Code 和 Codex 之间来回切换为了管理不同环境的配置会使用 cc-switch 这类配置切换工具。cc-switch 可以理解为一个“配置管理器”它支持维护多套 API 配置并根据需要快速切换。安装和配置的详细步骤以 cc-switch 官方文档为准。常见做法是在图形界面中添加多套配置保存后通过菜单切换。使用这类工具时务必注意不要在生产环境随意切换配置也不要把密钥明文提交到仓库。2.5 验证环境是否可用安装完成后建议先做一个最小化的环境验证。在任意项目目录下执行claude --version codex --version如果两个命令都能正常输出版本号说明基础环境已就绪。接下来可以创建一个测试目录开始编写第一个 Agent Skill。3. 理解 Skill 的组织形式与加载机制3.1 Skill 的推荐目录结构以 Claude Code 为例一个完整的 Skill 通常放在项目的.claude/skills目录下结构如下.claude/ └── skills/ └── code-review/ ├── SKILL.md ├── scripts/ │ └── review.py可选 └── references/ └── checklist.md可选每个技能目录的名称建议使用中划线分隔例如code-review、log-analysis、dependency-check。目录内部必须有SKILL.md这是一切技能定义的核心入口。SKILL.md会被 Agent 读取并解析其他辅助脚本和参考资料则按需调用。3.2 SKILL.md 的元信息格式SKILL.md不仅仅是一份 Markdown 文档它还包含一段 YAML 格式的 frontmatter用于描述技能的元信息包括技能名称、描述、使用场景等。这段元信息非常重要因为 Agent 需要通过“描述”来判断当前任务是否与某个技能匹配。一个最小化的SKILL.md示例--- name: code-review description: 用于执行代码审查任务。当用户要求检查代码质量、发现潜在缺陷、给出优化建议时使用本技能。 --- # 代码审查技能 ## 目标 ... ## 执行步骤 ...需要注意description字段要写清楚技能的能力范围和触发条件尽量使用与用户自然语言重合度高的词汇。如果描述过于模糊Agent 在遇到相关任务时可能无法正确加载该技能。3.3 Skill 的加载机制Agent 并不会一次性把所有 Skill 都读进上下文那样既浪费 token 又影响响应速度。常见的设计是“按需加载”Agent 根据当前任务的内容结合所有 Skill 的描述元信息筛选出最匹配的技能再读取对应的SKILL.md文件。因此编写 Skill 时要特别注意描述要精准便于匹配。SKILL.md 内容要结构化便于 Agent 快速提取关键步骤。大段的示例代码尽量放在 references 或 scripts 中避免主文件过长。3.4 编写 Skill 的基本原则根据实践我认为编写高质量 Skill 需要遵循下面几个原则单一职责一个 Skill 只解决一类问题。不要把“代码审查 日志分析 性能优化”塞到同一个技能里。步骤明确执行步骤要按顺序编号并给出每个步骤的输入、操作、输出。有判断条件遇到什么情况应停止遇到什么情况应切换方案需要在 SKILL.md 中写清楚。提供示例给出一两个正反示例帮助 Agent 理解输出标准。可测试技能写完后要设计一个固定的测试任务验证效果。4. 实战案例一在 Claude Code 中创建第一个 Skill这一节我们实际动手创建一个可复用的“需求拆解技能”。该技能的作用是当用户提出一个模糊的开发需求时Agent 能按照既定模板将需求拆分为背景、目标、功能列表、验收标准、技术选型建议和风险点。4.1 创建项目结构先创建项目目录mkdir -p agent-demo/.claude/skills/requirement-split cd agent-demo然后在requirement-split目录下创建SKILL.md文件。4.2 编写 SKILL.md文件路径agent-demo/.claude/skills/requirement-split/SKILL.md--- name: requirement-split description: 用于将模糊的产品需求拆解为可执行的技术开发任务。当用户提出一个新的功能想法、业务需求或者需要整理开发任务清单时使用本技能。 --- # 需求拆解技能 ## 目标 将模糊的功能描述转化为结构化的开发需求说明降低后续开发与测试的沟通成本。 ## 执行步骤 1. 提取用户原始需求中的核心意图。 2. 按照下面的模板输出需求说明。 ## 输出模板 ### 需求背景 说明该需求要解决的业务问题。 ### 需求目标 用 1-3 句话描述最终达成的效果。 ### 功能清单 - 功能点 1描述 - 功能点 2描述 ### 验收标准 - 标准 1如何验证功能是否正确 ### 技术建议 推荐技术栈和实现方案。 ### 风险点 列出可能的实现风险或依赖项。 ## 注意事项 - 如果用户给出的信息不足先向用户提问补齐关键信息不要凭空编造需求。 - 输出格式严格遵循上述模板使用中文。这个技能的核心是约束 Agent 的输出结构。没有技能时不同对话里 Agent 拆解需求的格式可能完全不同有了技能后输出格式就变得可控了。4.3 编写辅助脚本可选如果希望技能在执行时自动调用脚本可以在技能目录下增加scripts文件夹。例如创建一个简单的模板生成脚本文件路径agent-demo/.claude/skills/requirement-split/scripts/generate_template.py#!/usr/bin/env python3 # -*- coding: utf-8 -*- 根据需求关键词生成需求文档模板。 import sys def main(): keyword sys.argv[1] if len(sys.argv) 1 else 未命名需求 template f# {keyword} 需求说明 ## 需求背景 待补充 ## 需求目标 待补充 ## 功能清单 - 待补充 ## 验收标准 - 待补充 ## 技术建议 待补充 ## 风险点 待补充 print(template) if __name__ __main__: main()在SKILL.md中可以通过类似下面这样的描述来引导 Agent 调用脚本## 工具使用 当需要生成空模板时执行以下命令 python3 .claude/skills/requirement-split/scripts/generate_template.py 需求名称注意脚本路径写法要基于项目根目录并且要确保脚本具备执行权限。4.4 在 Claude Code 中测试 Skill在agent-demo目录下启动 Claude Codeclaude然后在交互界面输入类似这样的任务请帮我把“用户登录增加短信验证码”这个需求进行拆解。如果配置正确Agent 会加载requirement-split技能并按照模板输出需求文档。如果输出结构不符合预期可以检查 SKILL.md 的描述是否与任务语句匹配。4.5 运行验证预期输出应该是包含“需求背景、需求目标、功能清单、验收标准、技术建议、风险点”的结构化文档。可以对比一下有技能和没有技能时输出的差异你会发现有技能时输出内容更加稳定几乎不会漏掉关键模块。5. 实战案例二在 Codex 中复用类似技能5.1 Codex 支持自定义指令的方式Codex 同样支持项目级自定义指令。与 Claude Code 的.claude/skills目录不同Codex 通常通过项目根目录下的AGENTS.md文件来定义项目的规则、约定和任务执行流程。Codex 在启动时会读取该文件将其作为会话的长期上下文。这意味着我们可以把“需求拆解技能”的模板直接写入AGENTS.md让 Codex 在工程中也具备同样的输出规范。5.2 编写 AGENTS.md文件路径agent-demo/AGENTS.md# 项目 Agent 规则 ## 需求拆解 当用户提出新的功能需求时必须按以下模板输出 ### 需求背景 说明该需求要解决的业务问题。 ### 需求目标 用 1-3 句话描述最终达成的效果。 ### 功能清单 - 功能点 1描述 - 功能点 2描述 ### 验收标准 - 标准 1如何验证功能是否正确 ### 技术建议 推荐技术栈和实现方案。 ### 风险点 列出可能的实现风险或依赖项。 如果用户提供的信息不足以编写需求文档必须先继续提问补齐信息后再输出。这个文件的作用和SKILL.md类似但粒度上是“项目级约束”。它适合把整个项目都要遵守的规则放进去例如代码风格、提交规范、测试要求等。5.3 配置 Codex 使用不同模型来源Codex 默认使用的模型可以通过配置文件调整。常见做法是在用户目录下创建配置文件或者在项目目录中配置.codex相关文件。一个常见的场景是接入兼容 OpenAI 接口的本地模型服务。配置文件中的关键项大致如下{ model_providers: { local: { name: Local Model, base_url: http://localhost:11434/v1, env_key: LOCAL_API_KEY } }, model: local/qwen2.5-coder:latest }需要注意的是这里只是演示配置结构实际字段名和接口路径可能会随 Codex 版本变化。接入本地模型前先确认本地模型服务是否已启动以及/v1/chat/completions等接口是否可用。如果模型能力较弱技能执行效果可能不稳定建议在本地模型场景下降低任务复杂度。5.4 运行验证在agent-demo目录下启动 Codexcodex输入相同的需求请拆解“增加用户短信登录功能”的需求。Codex 在读取AGENTS.md后会按照同样的模板输出需求文档。这个案例说明了 Agent Skills 的一种跨工具迁移思路底层逻辑一致只是承载文件不同。6. 技能开发进阶与扩展6.1 多个 Skill 的组合编排在真实项目中一个任务往往需要多个技能配合。例如“开发一个登录接口”这个任务可能同时涉及“需求拆解技能”“代码审查技能”“测试用例生成技能”。组合编排的关键在于每个 Skill 的职责要清晰输入输出要明确。比如需求拆解技能输出需求文档测试用例生成技能读取需求文档生成用例。通过这种“前一个技能的输出是后一个技能的输入”的方式可以构建复杂的自动化流水线。Claude Code 支持在对话中按需加载不同技能你可以通过连续指令让 Agent 依次调用。6.2 技能与外部工具的结合Agent Skills 的能力边界可以进一步扩展。比如在 SKILL.md 中定义“当需要调用某外部服务时使用以下命令”或者通过脚本调用外部 HTTP 接口。这里的安全风险需要注意技能中的命令如果写得不够严谨Agent 可能执行预期之外的命令。建议对技能内的 Shell 命令做白名单控制并强调只能在授权的项目目录中运行。6.3 技能的版本管理与共享由于 SKILL.md 本质上是文本文件完全可以纳入 Git 版本管理。团队协作时可以把技能目录放在一个独立仓库中通过 Git 子模块或复制方式引入各个项目。版本管理的好处是技能变更可追踪。可以回溯到旧版技能进行对比。支持多团队共享一套最佳实践。6.4 与本地模型的结合场景对于一些需要数据隔离或离线开发的场景可以将 Claude Code、Codex 与本地模型结合使用。常见方案是使用 Ollama 这类本地推理工具启动模型服务然后通过配置把 API 指向本机地址。这种方案的优势是数据不外传、可以离线使用缺点是模型能力相比云端模型有一定差距Agent 在复杂任务上的表现可能下降。因此本地模型场景下建议降低单次任务复杂度。在 SKILL.md 中增加更细化的步骤。对输出结果增加校验环节。7. 常见问题与排查思路7.1 Claude Code 安装失败或命令找不到如果执行claude提示找不到命令可能有几种原因Node.js 版本过低建议升级到 18 及以上。npm 全局安装路径不在系统 PATH 中需要配置环境变量。安装过程中网络问题导致包未下载完整。排查顺序先检查 Node 版本再查看 npm 全局目录最后确认环境变量。7.2 Codex 启动时提示本地代理配置异常有网友反馈过类似这样一条报错本地代理配置失败Codex 在调用接口时请求未能正常转发。这类问题的核心通常不是模型本身的问题而是本地代理服务的地址、端口或协议与 Codex 的预期不一致。解决办法检查代理服务是否启动。核对配置文件中的base_url是否完整是否包含http://前缀。确认请求是否可以直达目标接口必要时可以先用curl做一次连通性测试。注意不要在未确认目标服务合法性的情况下随意配置代理也不要将内网地址暴露到公网。7.3 Skill 没有被 Agent 加载如果发现输入的指令符合技能描述但 Agent 仍然没有按 SKILL.md 输出可以从以下几点排查检查技能目录是否放在正确的路径下例如.claude/skills。检查 SKILL.md 的 frontmatter 是否合法YAML 格式是否出错。检查description字段是否与任务语句匹配。查看 Agent 启动日志确认有没有读取技能文件。7.4 Agent 执行过程被中断有时候 Agent 在执行多步任务时提示执行被终止。这类问题通常与以下原因有关单步执行时间过长触发了超时。命令交互等待输入但无法自动处理。脚本异常退出Agent 无法接收下一步指令。建议把长任务拆短在 SKILL.md 中要求 Agent 分阶段执行每个阶段完成后输出结果再决定是否继续。也可以适当调整超时时间但要注意不同工具版本对超时限制的差异。7.5 常见问题汇总问题现象常见原因解决思路安装后命令找不到PATH 未配置或 Node 版本过低升级 Node检查 npm 全局路径Agent 未加载技能目录路径错误或 SKILL.md 格式错误核对路径检查 YAML 格式输出格式混乱技能描述不够清晰细化 SKILL.md 步骤和模板执行中断任务过长或脚本卡住拆分任务增加阶段输出本地代理配置报错地址、协议或端口不匹配核对配置先用 curl 测试连通性不同工具行为不一致Claude Code 与 Codex 加载逻辑不同分别查看各自文档调整配置8. 最佳实践与工程建议8.1 Skill 命名与目录规划技能命名要短且语义明确推荐使用中划线命名法如code-review、db-migration、api-design。目录层级不要太深一般两层即可避免 Agent 搜索和读取文件的开销过大。8.2 保持技能文件的精简SKILL.md 不是文档网站不要把所有知识都堆进去。主文件控制在 50 到 100 行左右复杂的参考资料放到references目录中脚本放到scripts目录中。核心目的是让 Agent 快速理解“要做什么”和“按什么顺序做”而不是把大模型当浏览器用。8.3 明确限制边界在技能描述中一定要写清楚哪些事情不允许做。比如不允许执行数据库删除操作。不允许在没有测试的情况下直接修改生产配置。不允许读取项目外的敏感文件。不允许将密钥写入代码仓库。Agent 虽然不具主观恶意但它会忠实执行指令。技能里缺少安全边界就可能在自动化流程中产生风险。8.4 配置与密钥管理涉及 API Key、Token 等敏感信息时务必使用环境变量或密钥管理服务。不要把它们写进SKILL.md、AGENTS.md或其他会提交到仓库的文件中。在分享技能包时先检查是否包含敏感信息。8.5 持续迭代与效果度量Agent Skills 不是写一次就结束的。建议每次执行后记录输出质量分析哪些步骤不稳定、哪些描述有歧义然后针对性修改。可以建立一个小型测试集每次修改技能后用固定的一组任务回归测试保证效果不退化。8.6 结合项目实际选择合适的载体Claude Code 的 Skills 目录和 Codex 的 AGENTS.md 各有优势。Skills 更灵活适合“多技能按需加载”AGENTS.md 更直接适合“项目级强制规则”。实际项目中可以根据团队分工混合使用项目级通用规则写入 AGENTS.md专业技能打包为 Skills。9. 总结与后续学习建议通过这篇文章我们从概念上梳理了 Agent 与 Agent Skills 的区别搞清楚了 Skills、Tools、MCP 三者的定位在实践层面完成了 Claude Code 与 Codex 的环境搭建并用一个“需求拆解技能”走通了从 SKILL.md 编写到 Agent 加载验证的全流程。对于常见安装失败、技能未加载、执行中断、本地代理配置报错等问题也给出了具体的排查思路。接下来可以继续深入的方向有三块一是学习 MCP 协议把 Agent 连接到真实的数据库、文件服务和第三方 API二是研究多 Agent 协作模式让不同技能由不同 Agent 分工执行三是建立自己的技能库把日常开发中反复出现的工作流逐步沉淀为可复用的 Agent Skills。开发 Agent 的过程很像搭积木模型是底座技能是模块能拼出多强的系统取决于你积累了多少高质量模块以及你愿不愿意持续打磨它们。如果这篇文章对你有帮助可以收藏备用也欢迎在评论区聊聊你在 Agent 开发中踩过的坑。