先聊几句题外话。最近圈子里很多人问我现在做 AI Agent到底该从框架入手还是直接用 Claude Code 这类工具把能力堆起来我自己的答案是框架思路该学但真正要落地出活Claude Skills 这套机制是目前性价比最高的路径。这篇博文就围绕 claude skills 安装、Skill 目录规范、Agent 编排、MCP 配合 这几个关键词展开把我在项目里从零搭到生产可用的完整过程拆开讲一遍。无论你是刚开始研究 AI Agent 的入门者还是已经用 LangGraph、n8n 折腾过一轮的开发者这篇东西应该都能给你一些可以直接抄走的经验。先说清楚一个容易混淆的点Claude Skills 不是 OpenAI 那种插件市场它本质上是一种把能力封装成文档 脚本让 Claude 在需要时自动调用的机制。你不需要维护复杂的状态机不需要手写 ReAct 循环Claude 自己会读你的技能描述、决定何时调用、然后用什么参数调用。换句话说框架帮你把Agent 骨架搭好了而 Skills 是往骨架上装器官。下面我按实际构建顺序讲。1. 为什么我把 Agent 构建重心从 Agent 框架搬到了 Claude Skills1.1 传统 Agent 框架在真实项目里的三个痛点我最早做 Agent 项目时用的是 LangGraph 这类专门的状态编排框架。思路很正统定义节点、定义边、设计状态对象、写工具函数、然后注册工具。听起来没问题但一进真实项目就暴露问题。第一个痛点是状态管理。LangGraph 的状态本质是一张图节点之间通过 state 传递数据看起来灵活但调试的时候你会在这个字段到底在哪一层被覆盖了这种事上耗掉大量时间。尤其当你有多个 Agent 协作类似 Spring AI Multi Agent 的场景状态同步这件事会膨胀到失控。第二个痛点是工具接入太重。每接一个外部能力你都要写工具类、定义输入输出 schema、注册进模型上下文还要考虑错误重试。写业务代码的时间还没写工具适配代码的时间多。第三个痛点是交互模式的绑定。框架往往把用户─Agent─工具的交互方式定死了你想让 Agent 先做需求澄清再做方案设计、再写代码意味着你得自己实现一套阶段控制逻辑。这些痛点不是说框架不好而是对大多数想快速做出一个能用的 Agent的团队来说框架的复杂度远超收益。1.2 Claude Skills 解决的是最后一公里问题Claude Skills尤其是 Claude Code 的 Skills 机制换了一个思路它把Agent 如何完成任务交给了模型自己而开发者只需要关注我能提供哪些能力。每个 Skill 就是一个文件夹里面有一个 SKILL.md 文件写清楚这个技能是什么、什么时候用、怎么用可以再附上脚本、参考文档、模板文件。Claude 会在对话中根据用户的请求自动决定要不要加载某个 Skill、运行里面的脚本、读取附件。这种设计最大的好处是你不需要写 Agent 的调度逻辑。调度是模型根据语义自主完成的。我只需要把一个个 Skill 建好描述写得足够清晰Claude 就能在合适的时候抽取出来用。这像什么像你把工具放在工具箱里每个工具上贴了标签老师傅模型看到活儿就知道拿哪把。1.3 这套方案适合谁、不适合谁从我几个项目实测来看Claude Skills 特别适合这几类场景用 Claude Code 做 AI 编程辅助想把团队规范、常用脚手架、评审流程固化下来想快速搭建一个能自主完成需求分析→编码→测试全流程的 Agent又不想陷入框架泥潭已经在用 MCP 接外部工具但发现某些静态能力文档规范、Prompt 模板用 MCP 写太重希望有更轻量的方案。不太适合的场景也有如果你的 Agent 需要高并发、复杂的优先级抢占、严格的 DAG 任务依赖那还是老老实实用 LangGraph 这类专用编排框架。Claude Skills 本质是模型自主决定任务流程的确定性没那么强。2. Claude Skills 的加载机制与目录规范SKILL.md 里到底该写什么2.1 三类存放位置与优先级Claude Skills 不是随手放哪都能被识别。按我实际使用的经验目录主要分三种项目级项目根目录下的.claude/skills/只对当前项目生效。适合放团队规范、项目专属工具比如读取本项目的 changelog 并生成发布说明这类高度定制的能力。用户级~/.claude/skills/对当前用户所有项目生效。适合放个人通用能力比如把我的代码按 PEP 8 风格整理这类通用技能。插件级Claude Code 插件里自带的 skills 目录一般装完插件自动注册。加载优先级上项目级会盖过用户级同名 Skill 以更具体项目级为准。这个特性很容易被忽略但也常给人挖坑——你以为改了全局的结果项目里有个同名旧版本一直生效。2.2 SKILL.md 的元数据与正文结构SKILL.md 是整个 Skill 的灵魂。它有固定的 frontmatter 格式最少要包含 name 和 description 两个字段。下面是我一个代码评审 Skill 的真实写法--- name: code-review description: 对指定代码文件或 Git diff 进行团队规范检查输出逐条评审意见包含严重级别和修改建议。当用户要求评审走查检查代码质量或提交 Pull Request 前自检时使用。使用前必须确认 review 脚本存在。 --- # 代码评审技能 ## 执行步骤 1. 获取变更文件列表优先使用 git diff --cached若无暂存内容则用 git diff。 2. 对每个变更文件运行 python3 scripts/review.py file 生成静态检查结果。 3. 结合团队规范见 docs/team-coding-rules.md逐条列出问题标记严重级别P0/P1/P2。 4. 输出建议修复代码片段不要直接修改文件除非用户明确要求。description 的写法特别讲究这点我后面专门展开。正文部分则要写清楚触发条件→执行步骤→输出格式最好把边界条件也写清楚比如哪些情况下不要使用能有效避免误触发。2.3 附加资源脚本、模板、参考文档SKILL.md 只是入口真正干活的是它引用的资源。我通常会在 Skill 目录里放scripts/可执行的检查、生成、转换脚本Python、Shell、Node 都行。docs/团队规范、术语表、架构文档等静态参考。templates/生成的代码模板、PR 描述模板、提交信息模板。这些资源用相对路径引用即可。Claude 在加载 Skill 后能看到整个目录的内容清单需要读取某个文件时会自动打开。2.4 description 是路由信号值得花一小时打磨这是我这几个月最有体感的一点Skill 的 description 就是 Agent 做工具路由的信号。Claude 每次决策要不要用某个 Skill靠的就是 description 和当前用户意图的语义匹配度。如果你写得含糊结果就是要么该调用时不调用要么不该调用时疯狂误触。我的经验是 description 要满足三个条件明确触发场景写清楚当用户提到 XX 或要求 XX 时使用而不是笼统写用于代码检查。明确限制边界写清楚当用户只问建议、不需要实际操作时不要用减少误判。写清前置依赖如果 Skill 依赖特定脚本或环境一定要写进去否则模型会自信地假装执行。3. 实战从零搭建一个代码评审助手 Skill3.1 先定义这个 Skill 要解决什么问题我团队的代码评审一直有个痛点每个人评审标准不统一有人只看逻辑不看规范有人只抓代码风格不关心性能隐患。我想要的评审助手不是那种大而全的AI 检查工具而是结合团队内部规范、能跑静态检查、能输出统一格式报告的 Agent 能力。我选的切入点是Git diff 变更评审。原因很实际Agent 在真实研发流程里最常用的场景就是提交前自检而不是对全量代码做审查。3.2 目录结构与文件内容我的完整结构长这样.claude/skills/code-review/ ├── SKILL.md ├── scripts/ │ └── review.py └── docs/ └── team-coding-rules.mdSKILL.md 的完整内容frontmatter 正文--- name: code-review description: 对当前分支的 Git 变更执行代码评审输出严重级别P0/P1/P2与修改建议。当用户要求评审走查检查代码提交前自检或提到看看这个 diff 有没有问题时使用。如果用户只是泛泛询问代码质量意见且没有具体文件先询问目标范围。 --- # 团队代码评审 ## 触发条件 - 用户要求对代码变更做评审。 - 用户要求提交 PR 前做自检。 - 用户要求按团队规范检查代码。 ## 执行流程 1. 用 git status 确认工作区状态用 git diff HEAD 获取变更内容。 2. 将变更文件列表写入临时文件。 3. 逐个文件运行 python3 scripts/review.py file收集输出。 4. 对照 docs/team-coding-rules.md 里的规范校核补充静态检查无法覆盖的点如命名、抽象层次。 5. 按以下格式输出 - 问题清单表格文件、行号、级别、问题描述、建议。 - 顶部给出一句话总结是否存在 P0 级问题。 ## 边界 - 只评审变更文件不评审全量代码。 - 不直接修改文件除非用户明确说直接改。 - 如果 diff 为空提示暂无变更。review.py 我用了 Python 内置的ast做基础语法检查加上简单的行宽检测、TODO 标记检测没有引第三方库。核心逻辑是遍历文件、按规则产出问题列表并打印 JSON。这样 Claude 读取输出后能和规范文档对照生成最后的评审意见。3.3 调用与验证的完整过程装好之后怎么验证我习惯开一个干净的测试目录建一个带故意错误的 Python 文件让 Claude 评审这个文件的变更。实测中 Claude 会做的事先执行git diff看变更发现文件路径后自动调用python3 scripts/review.py读取脚本输出对照docs/team-coding-rules.md最后以表格形式输出评审结论。第一次跑通时最明显的体感是真正干活的脚本可能只有几十行价值最大的反而是 SKILL.md 里的上下文描述。它让模型知道流程怎么走、规范是什么、输出长什么样。这也印证了我前面说的Skills 的本质是上下文与工具的封装不是代码量的堆积。3.4 给 Skill 加一点门禁逻辑更进一步我在 review.py 里加了一个退出码如果存在 P0 问题返回非 0。这样 Claude 在评审后如果用户继续问能提交吗它就能通过退出码判断并给出暂不建议提交的结论。这算是我自己在实践中摸索出来的模式Skill 的执行结果不应只是文本也要通过退出码这类信号给 Agent 决策依据。4. 让 Agent 学会分工多 Skill 编排与任务路由的设计思路4.1 从单 Skill 到多 Skill为什么需要设计技能边界单个 Skill 只能解决单一问题。你要一个真正的开发 Agent至少需要需求分析、技术方案、代码生成、代码评审、测试执行这些能力。对应地我建了五个 Skill。但建完就发现问题如果不做边界设计多个 Skill 的 description 会在语义空间里互相打架。举个例子我最初给代码生成和代码评审两个 Skill 都写了类似处理用户代码相关请求的描述结果 Claude 经常在用户要求写代码时先去调用评审模块白白绕一圈。后来我把描述改成强触发、强排他代码生成当用户要求写/生成/实现一个新函数、类或模块时使用代码评审当用户要求检查/评审/走查已有代码时使用。关键词边界清晰之后路由准确率明显上升。4.2 用 CLAUDE.md 约定工作流程Claude Code 的项目根目录还有一个CLAUDE.md文件它定义了 Agent 全局的工作约定。我会把多 Skill 协作的流程写在里面比如# 项目级约定 当用户提出一个功能开发任务时按以下顺序执行 1. 使用 skill:requirement-analysis 澄清需求边界 2. 使用 skill:tech-design 产出技术方案 3. 使用 skill:code-gen 生成实现代码 4. 使用 skill:code-review 对变更代码做自检 5. 使用 skill:test-run 执行测试并输出结果 各步骤之间需要用户确认确认前不继续下一步。这里的思路是Skills 提供能力CLAUDE.md 提供流程骨架。模型读 CLAUDE.md 后在收到任务时先判断该走哪个流程再在流程里按需调用 Skill。这比在框架里写状态机轻量得多也直观得多。4.3 一个实际的任务路由案例我之前接了一个需求给前端加一个用户登录弹窗并保证现有测试通过。Agent 的实际执行路径是这样的读 CLAUDE.md识别这是一个功能开发任务进入五步流程调requirement-analysis生成澄清问题登录弹窗的触发方式还要保留现有注册入口吗用户回答后更新需求摘要调tech-design输出涉及组件、接口、状态管理的方案调code-gen生成改动代码调code-review发现两个 P1 问题未处理 loading 状态、缺少错误边界Agent 自己按建议修了调test-run跑单测全部通过。整个过程我只需要在第一步和最后一步人工确认。这套流程如果用 LangGraph 写状态节点至少十几个而现在只是五个 Skill 一份 CLAUDE.md。4.4 技能协作时的上下文传递技巧多 Skill 协作最容易断的地方是上下文。一个 Skill 处理完输出要能被下一个 Skill 复用。我常用的做法是Skill 的执行结果写到固定路径比如.agent/artifacts/requirement.md然后在下一个 Skill 的 SKILL.md 里写明开始前若存在 artifacts/tech-design.md 则先读取。这样即使 Claude 上下文被压缩下一个 Skill 也能从文件里找回中间产物。5. 踩坑实录Skill 不生效、误调用与执行失败的三类排查链路5.1 Skill 完全不生效先查目录再查文件名最后查描述这是我被问得最多的问题。如果你新建了 Skill 目录但 Claude 毫无反应按这个顺序排查确认目录位置项目级要放在.claude/skills/注意是点开头。用户级放~/.claude/skills/。确认入口文件名必须是SKILL.md全大写。写成了skill.md或Skill.md都不会被识别。确认 frontmatter 格式name和description两个字段缺一不可且 frontmatter 要用---包裹不能有拼写错误。重启 Claude Code 会话Skills 的索引是在会话启动时加载的新增或改名 Skill 后不重启就不会生效。有一次我排查了半小时最后发现原因是~/.claude/skills/code-review/SKILL.md里的name: code_review用了下划线虽然不影响描述匹配但跟目录名不一致导致某些场景下定位异常。现在我的默认规则是目录名 name 全小写 中划线连接。5.2 误调用多个 Skill 描述语义重叠前面提到过description 是路由信号。如果你发现 Claude 频繁用错 Skill大概率不是模型笨而是你的描述没写清楚。我做了一次系统性的排查把每个 Skill 的 description 拿出来看凡是出现处理代码问题提供帮助这类宽泛字眼的全部重写。我最后形成的风格是这样的模板description: 当用户要求【具体动作】并涉及【具体对象/范围】时使用输出【具体产物】。如果用户只是【排除情况】不要使用本技能改用【另一个技能名】。5.3 执行失败脚本权限、解释器路径与工作目录Skill 里调脚本最常见的三类执行失败权限问题脚本没有可执行权限。解决chmod x scripts/review.py。不过我更推荐在 SKILL.md 里明确写使用python3 scripts/review.py file方式运行不依赖可执行位。解释器路径SKILL.md 里写python但系统只有python3就会直接报错。建议统一写明python3或者在 SKILL.md 里提前说明环境要求。工作目录Claude 执行命令时的工作目录未必是项目根目录。我的做法是所有脚本内部用git rev-parse --show-toplevel或类似方式动态定位项目根目录避免相对路径写死。5.4 循环调用与假装执行Agent 的自信问题还有一个很有意思的坑Skill 脚本输出为空时Claude 可能不会告诉你执行失败而是凭空生成一份看起来合理的结果。比如我的 review.py 如果因为文件路径错误没匹配到任何文件它会输出一个空数组Claude 看到空数组后居然会自己脑补几条评审建议。这个问题我第一次遇到时很震惊后来想明白了模型是生成式的它倾向于完成用户的请求而不是报告工具异常。解决办法是脚本端做好显式输出没有匹配到任何文件时明确输出一行NO_CHANGES并且 SKILL.md 里写明读到NO_CHANGES时必须告知用户未获取到变更请暂存代码或提供 diff而不是继续编造评审结果。5.5 一个简洁的问题排查对照表现象可能原因优先检查Skill 完全没有被触发目录位置/文件名/大小写错误确认.claude/skills/name/SKILL.md描述能感知但不调用description 触发场景太模糊补上强触发词调用了但脚本报错解释器/权限/路径问题手动跑一遍脚本验证脚本输出空但 Agent 继续编缺少空输出保护脚本显式输出空标记多个 Skill 交叉误用description 语义重叠按模板重写 description 并加排除条件6. Skills 与 MCP 的职责划分以及生产级 Agent 的架构建议6.1 Skills 和 MCP 到底有什么不同很多人搞混 Skills 和 MCP我自己一开始也没分得很清。简单说MCPModel Context Protocol是给模型提供实时数据/外部操作能力的协议它连接的往往是数据库、浏览器、内部系统这类动态资源而 Skill 更像打包好的操作流程里面有静态文档、脚本逻辑、执行规范。拿我做的一个发布助手举例用 MCP 连接 GitHub API让 Agent 能查 PR 状态、创建 Release用 Skill 封装发布前检查清单里面写了要跑哪些测试、要更新哪些版本号、要遵守哪些命名规范。MCP 解决能不能访问的问题Skill 解决该怎么干的问题。两者不是替代关系而是互补。实践中的感受是凡是需要实时数据源的能力走 MCP凡是固定套路 团队知识的能力走 Skill。6.2 生产级 Agent 的推荐架构我这段时间沉淀下来的一个相对可复用的架构是四层入口层Claude Code 作为 Agent 运行时加载 CLAUDE.md 定义总体流程。能力层一组按单一职责拆分的 Skills需求分析、方案设计、编码、评审、测试。连接层MCP Server 负责接 GitHub、数据库、监控系统等外部资源。产物层中间产物统一落到.agent/artifacts/目录跨 Skill 传递上下文。这套架构的弹性很好。新团队进来加一个新人入职指引 Skill 就行要接入新系统加一个 MCP Server 就行要改流程改 CLAUDE.md 即可。相比传统框架改造成本低很多。6.3 外部编排工具与 Claude 模型结合的场景如果需求超出了 Claude Code 自身范围比如要做定时触发、多人协作审批、复杂条件分支我也试过用 n8n 这类自动化工作流工具把 Claude 的能力编排进去。做法是用 n8n 的 HTTP 节点调用 Claude API同时把团队某个 Skill 的 SKILL.md 作为 system prompt 的一部分注入。这样 n8n 负责流程触发和分支判断Claude 负责需要语义理解的部分。本质上就是把 Skill 变成可复用的 Prompt 资产。如果项目里需要多个异构 Agent 协作比如一个负责数据分析、一个负责文案生成我也会用 LangGraph 来管理它们之间的数据流但每个 Agent 内部仍然用Skills 打包能力的方式。框架管编排Skills 管执行这个组合我目前用下来是最顺的。最后再分享一条个人体会Skill 别一上来就建一大堆。先挑你每周重复次数最多的三件事把它做成 Skill用两周再回头优化描述和脚本。你会发现很多你以为需要复杂框架解决的问题其实只需要把规范写清楚、让模型按步骤来就够了。做 Agent 这事复杂的是把一件事想明白而不是把代码堆多。