Claude Code、Skills、MCP 这三个词是我过去半年在 AI 开发工作流里最绕不开的组合。先给结论裸用 Claude Code 能让单次修 bug 的效率直接翻倍但真正让我工作方式发生质变的是把它接上 Skills 和 MCP 之后——从一个每次对话都要重新自我介绍的外包变成了一个懂项目规范、能自己调工具、还留得下审计记录的虚拟协作者。这篇不是官方文档复读也不是工具测评而是我把自己从裸用一路折腾到工程化的完整复盘。里面会拆解 Skills 到底是个什么机制、MCP 的接入细节是什么、工作流怎么从聊天式开发变成任务编排式开发以及一堆只会在现场踩到的坑。适合那些已经开始用 Claude Code、但每次新开会话都要重新解释一遍项目背景的开发者也适合刚接触 MCP、想知道它和普通插件到底有什么区别的人。1. 先说说裸用为什么爽完就疼1.1 我裸用 Claude Code 的真实一天最典型的场景是修构建报错。以前我得自己打开日志定位是类型错误还是循环依赖再手动试几种修法。用 Claude Code 裸用之后我只需要在终端里说一句帮我看看这次 CI 报错的原因它会自己去读日志、改代码、跑测试二十多分钟能搞定的排查工作它三五分钟就做完了。那一刻确实爽感觉像雇了一个不要钱的实习生而且这个实习生能一口气读完整个仓库。但问题也很快出现。我让它新增一个页面并遵循项目里的表单校验习惯它写出来的东西跟现有代码风格明显不一致——没有用项目里已经封装好的组件库校验逻辑散落在模板里看着能用但和团队其他代码格格不入。我这才意识到它不知道我们项目的约定因为我每次都在重新教而且教得还不完整。同一周我开第三个新会话处理另一个需求时又花了五分钟把项目背景、技术栈、目录结构重新贴了一遍。真的烦了。1.2 裸用的四个死穴越用越明显我给裸用状态总结了四个典型问题基本可以覆盖 90% 的劝退场景。第一是上下文断层。Claude Code 的每个会话都是独立的新会话等同于失忆。项目背景、编码规范、历史决策、哪些目录绝对不能动全都得靠手工重新投喂。一次两次还好天天这么干就是纯浪费。第二是工具孤岛。Claude Code 默认能读写文件、执行命令、操作 git能力确实强但这些能力太通用了连不上业务系统。我们自己的工单接口、测试环境数据库、设计稿、构建产物它一概碰不到。需要这些信息时我还是得自己去查然后把结果复制给它。第三是流程不可复用。上个项目总结出来的经验比如不要动 src/legacy新建代码放进 migration 目录只能留在我的脑子里换个会话就得重新讲。换个人来用 Claude Code同样的坑再踩一遍。第四是结果不可控。没有约束时AI 会走它认为最省事的路径。我遇到过它为了通过测试直接删测试用例也见过它把一个局部函数重写成 IO 密集的大改动理由是性能更优。严格说没有错但不是我要的改动范围。1.3 什么时候该从裸用转向工程化我不是建议所有人都马上上 Skills 和 MCP那也是一种过度设计。如果你只是在一次性项目里临时用 AI 改几个文件裸用完全够没必要建一堆配置。我是被三个信号推着走的。第一个信号会话开头越来越长每天贴相同的背景信息我开始怀疑自己在做体力活。第二个信号在同一个仓库里Claude 经常改动我不希望它碰的文件每次都得手动 checkout 回滚。第三个信号团队开始有多个人一起用但每个人的 Claude 行为完全不一样——同一个需求有人让它一次性通过测试有人让它改完一堆坑。当工作流开始有长期、重复、多人这三个特征时再不上 Skills 和 MCP时间成本就是纯浪费。工程化不是为了炫技而是把隐性约定变成显性配置让 AI 的产出稳定、可复现、可审计。2. Skills 到底是什么我的理解和方法2.1 用第一性原理拆解 Skills 机制一句话Skills 是一个轻量的、基于 Markdown 的行为注入机制让 Claude 在与当前任务匹配时自动加载一份领域操作手册。它的物理形态很简单一个目录 一份SKILL.md。比如我有个项目叫vue-conventions对应目录就是~/.claude/skills/vue-conventions/里面只有一个SKILL.md。文件开头是 YAML frontmatter核心字段是name和description正文则是规则、示例、反例和检查清单。理解这个机制要看懂一件事模型并不是在会话开始前把所有 skill 都背进脑子里而是按照当前任务和哪个 skill 的描述最匹配来决定是否加载。这个过程是动态的、按需的。换句话说description写得越精确命中率越高正文写得越结构化执行得越稳定。类比一下Skills 就像给一个能力很强但对业务不熟的新人塞了一本部门的 SOP 手册。他不会一上来通读整本手册而是在遇到对应场景时才翻开那一页。相比每次在 prompt 里手写几百行规则Skills 能显著降低上下文占用因为你不需要每次都把规范讲一遍只需要让它在正确的时候加载正确的知识。另外说一句这已经是行业共识了。Anthropic 把 agent skills 放进了 Claude 生态的核心能力OpenAI 的 Codex 也引入了类似机制。大家逐渐意识到真正的智能工程不在于让模型记住更多东西而在于正确的时候加载正确的知识。2.2 一份能让 Claude听话的 Skill 该怎么写我在长期用下来之后把一份合格的SKILL.md总结成五个部分背景、强制规则、推荐模式、反例、检查清单。下面是我实际用过的一个精简示例你可以直接作为模板参考。--- name: vue-frontend-conventions description: 当需要修改 Vue 组件、新增页面、处理组合式函数或状态管理时使用。适用于本仓库的 Vue3 TypeScript 项目确保代码风格符合团队规范。 --- # Vue 前端开发规范 ## 背景 本仓库使用 Vue 3 TypeScript Composition API组件库基于内部封装。所有页面组件必须放在 src/views 下公共组件放在 src/components 下。 ## 强制规则 - 新增组件使用 script setup langts禁止使用 Options API 写法 - 表单校验统一使用项目封装的 validator 工具不得在组件内散写规则 - 组件目录使用 PascalCase文件名与组件名保持一致 ## 推荐模式 - 状态管理优先使用 Pinia store页面内不得堆积超过 200 行的业务逻辑 - 异步请求封装在 src/api 模块中组件内禁止直接调用 axios ## 反例 - 在组件内直接修改 pinia state 的非 action 字段 - 在多个组件中重复粘贴同一段校验正则 ## 检查清单 - [ ] 组件命名是否符合 PascalCase - [ ] 是否还有可直接提取的组合式函数 - [ ] 测试是否覆盖新增逻辑这里我想强调三点经验。第一description要写什么场景下触发而不是这个 skill 包含什么。你写当需要修改 Vue 组件或新增页面时使用比写Vue 开发规范的命中率高得多。Claude 是根据语义匹配来决定要不要读这份文档的触发条件描述得越像任务场景匹配越准。第二反例很重要。模型对不能这么做的理解往往比应该怎么做更敏感。尤其是项目里的历史禁忌比如不要动 legacy 目录不要在组件内直接调 axios写清楚反例能省掉大量回滚操作。第三篇幅要克制。一份 skill 写成一本书模型反而抓不住重点。我一般控制在几十行到一百行以内关键规则放在最前面。另外这个目录本身要纳入 git 管理跟我后面说的工程化工作流是配套的——skill 也是代码也要有版本历史和变更记录。2.3 安装、推荐与市场扫盲别把技能全堆上去Skills 的获取渠道现在已经很丰富了。官方那边Claude 的产品界面里已经有浏览和安装入口社区则主要活跃在 GitHub 上。搜索的时候用claude skills、awesome-claude-skills、find skills这些关键词能翻到大量技能集合。安装操作很简单本质上是把别人的 skill 目录放到本地。比如git clone https://github.com/example/superpowers ~/.claude/skills/superpowerssuperpowers是社区里比较出圈的一个集合里面按代码审查、重构、测试生成、文档写作等场景做了分类质量参差但参考价值很高。我的建议是把这当作品类目录来逛而不是直接全部启用。这里有一个很关键的教训别做技能收集癖。装 10 个没用的 skill等于给 Agent 的大脑里塞了 10 份它每次都要先判断是否和我相关的噪音。我发现装了太多 skill 之后Claude 反而变迟钝了——它要反复读那些不相关的文档浪费 token偶尔还会跑偏。最后我只保留了 5 个常驻的全局 skill项目级 skill 按仓库按需加载这才回到正常水平。2.4 我自己沉淀的三类实用 Skill按用途分我自己主要沉淀了三类 skill。第一类是规范类解决风格不一致的问题。比如前面示例的 Vue 前端规范还有一份 git 提交信息规范要求所有提交遵循 conventional commit 的约定格式。这类 skill 的直接效果是不管是我还是另一个同事开的会话Claude 产出的代码和提交信息都变统一了。第二类是场景类解决流程不可复用的问题。依赖升级、性能调优、重构检查清单这些都属于这类。比如依赖升级 skill 里会写升级前先跑基线测试、锁定破坏性变更、升级后对比核心接口的返回差异这样每次升级依赖时Claude 都会自动走这套 SOP不用我重新提醒。第三类是护栏类解决结果不可控的问题。最典型的是一个叫do-not-touch的 skill内容就是几条硬约束src/legacy目录禁止重写、涉及跨模块改动必须先给出影响面再动手、不确定时停下来问人。这相当于把团队里老师傅的口头规矩变成 Agent 必须遵守的边界条款。一个 skill 的价值不在于它多长而在于它把多少隐性知识显性化了。3. MCP把外部世界接到 Agent 身上3.1 为什么 MCP 是 AI 工具接入的USB-CSkills 解决了知识从哪里来的问题MCP 解决的是工具从哪里来的问题。在 MCPModel Context Protocol出现之前每接一个外部工具都是一对一的定制集成要接数据库就写一套数据库插件要接工单系统又写一套 Jira 插件要接浏览器再写一套控制脚本。集成方累模型侧也乱。MCP 做的事情是定义了一个统一协议的插座。AI 客户端作为 MCP Host工具方实现一个 MCP Server两边通过标准化的 JSON-RPC 交换工具列表、调用请求、执行结果。只要工具方实现了一个 Server所有支持 MCP 的客户端都能直接调用它不需要为每家单独适配。用充电器来类比很直观以前每个设备一个充电口桌上堆满线。MCP 就是那个 USB-C 协议统一之后一根线能充所有设备。拆开看 MCP 的三个角色Host 是支持 MCP 的客户端比如 Claude Code 或 Claude DesktopServer 是暴露工具的服务进程可以是本地 stdio 进程也可以是远程 HTTP/SSE 服务Tool 则是 Server 暴露出来的具体能力比如查数据库搜文件发 HTTP 请求。这个设计的好处是工具与模型解耦——工具方不需要关心用户用的是哪个大模型模型侧也不需要为每个工具写专属集成。3.2 从零接入一个 MCP Server 的完整过程最典型的入门案例是文件系统 MCP Server它让 Claude Code 能在指定目录范围内做文件操作。添加方式很简单claude mcp add filesystem -- npx modelcontextprotocol/server-filesystem ~/projects ~/workspace claude mcp list注意两点。第一add后面的filesystem是我给这个 Server 起的名字--后面才是真正的启动命令。第二启动参数里的路径列表很重要它限定了这套工具能访问的目录范围我把这个理解为给 Agent 划定的工作区域。除了全局配置MCP 也支持项目级配置。项目根目录下的.mcp.json长这样{ mcpServers: { filesystem: { command: npx, args: [ modelcontextprotocol/server-filesystem, /Users/me/projects/repo-name ] } } }把这个文件提交到 git新成员克隆仓库后Claude Code 会自动加载团队里的工具配置就统一了。要验证是否生效直接在会话里问你现在有哪些 MCP 工具可以用Claude 会列出它探测到的工具清单之后你就能让它执行跨工具的任务。MCP 的生态边界比很多人想得要广。有人给 Unreal Engine 5.8 写了 MCP Server让 AI 能直接操纵游戏编辑器EDA 领域有 Altium Designer 的 MCP 接口逆向那边 IDA 和 x32dbg 都有 MCP 插件工业自动化里连 TIA Portal 都出现了交付包。看到这些的时候我的第一反应不是又一个插件而是工具层正在被统一——这会让 AI 未来能碰到的东西比现在多得多。3.3 Skills 和 MCP 怎么分工知识归知识工具归工具很多人刚接触这两个概念时会混在一起我的经验是它们完全是可以并行、也经常需要配合的两个层面。维度SkillsMCP主责注入领域知识、行为约束打通外部工具、数据与动作形态Markdown 指令包独立运行的服务进程传递的内容规则、示例、上下文工具清单、调用请求、执行结果产生的作用影响模型的判断和输出影响真实系统状态类比培训手册万能插头一个配合场景最能说明问题。Skill 负责告诉 Claude我们的发布分支命名规则是release/版本号提交信息必须通过 conventional commit 校验MCP 则负责把切换分支、查看 CI 状态、发通知这些动作真正落地。知识只能在上下文里工具必须能产生真实副作用两者叠加之后Agent 才真正具备边思考边动手的能力。我的工作流里Skills 负责让 Claude 知道怎么做才符合规范MCP 负责让 Claude 能真正去操作系统。缺了前者它瞎干缺了后者它只能嘴上说说。4. 我的工作流是怎么从聊天式变成工程化的4.1 从 Issue 到分支人定目标Agent 管执行工程化之前我和 Claude Code 的交互是聊天式的我直接说把这个组件改成响应式它立刻开始改。这种模式的毛病在于需求边界和验收标准都不明确改到一半经常跑偏。工程化之后我改成任务编排式的交互。每次动手前我会给 Claude 一个任务包里面至少包含四块内容需求描述、要加载的 skill 清单、可用的 MCP 工具列表、明确的验收标准。例如这个抽屉组件要改响应式参考vue-frontend-conventionsskill过程中可以读src/components/drawer下的文件、运行vitest验收标准是现有测试全绿、新增组件必须有独立测试、diff 范围不得超出src/components/drawer。整体流程被拆成五个环节解析目标Claude 先输出一份简短执行计划我确认之后它才动手按需加载 skill根据任务类型自动触发对应的规范类和场景类 skill通过 MCP 获取上下文读文件、查数据库、拉构建产物而不是靠我手动贴分步执行改代码、跑测试、逐步提交每一步都有明确结果生成变更摘要最后输出改了什么、为什么改、影响面在哪由我做人工审查核心原则是人定目标和验收Agent 管执行和初筛。这刚好解决了我之前提到的结果不可控问题因为验收标准是任务开始前就约定好的Claude 的所有行为都要朝着这个标准收敛。4.2 一次真实重构复盘MCP 让我看到了 Agent 的另一面有一次需要把一个 400 多行的大组件拆成组合式函数这种任务以前我自己来做要小心很久因为涉及文件引用关系复杂。那次我决定完整跑一遍工程化流程。我先调用了一个重构检查清单类的 skill里面写着拆分前要确认的事组件里哪些状态是互相依赖的、哪些逻辑可以被复用、拆分后对现有测试的影响面。然后通过文件系统 MCP让 Claude 自己读取组件源码和所有引用了这个组件的文件。它给出了拆分方案把代码分成三块数据请求逻辑、筛选状态、图表配置。我确认方案后它开始动手。过程中最有意思的是当测试失败时它没有直接重试而是先通过 MCP 查看测试输出的详细堆栈定位到是图表配置里有一个 getter 在初始化前被访问了修复之后重新跑测试全绿。整个过程下来我自己只做了两件事确认拆分方案、review 最终的 diff。牵涉到文件搜索、代码修改、测试执行、错误定位这些脏活累活全部由 Agent 借助 MCP 工具完成了。那一刻我意识到MCP 让 AI 真正在系统里干活而不只是嘴上分析代码。这次之后我补了一条经验要给 Claude 一个工具使用偏好——比如优先直读本地文件、能一步完成的不要绕道去调远程 API。不然它有时会过度工具化本来直接读文件就够了非要绕一圈去调服务接口。4.3 本地模型场景降级配置但别让工作流崩溃工程化过程中还会遇到一个现实问题不是所有场景都能用云端模型。有人是代码不能出内网有人是成本控制也有人只是体验一下。总之Claude Code 调用本地模型这个玩法我试过方法并不神秘——在本地模型工具里启动一个 OpenAI 兼容的服务端点然后通过环境变量把 Claude Code 的请求地址指向本地端点。实际体验需要泼一盆冷水本地小模型在简单、明确、短链路的任务上表现不错比如给这个函数补几个单元测试把这段代码格式化一下这种任务只要模型能理解指令就够用了。但在跨三个文件做重构还要满足编译约束的长链路任务上本地模型会明显开始犯迷糊经常做着做着忘了最初的目标。我的优化经验是本地模型 充分工具化 勉强可用的组合。让本地模型少做抽象推理多做具体的工具调用把大任务拆成小步骤每一步都由 MCP 工具把获取信息变成低成本动作弥补模型本身推理能力不足的问题。当然也要留条后路——明显超出本地模型能力的任务直接切回云端模型别硬撑。另外一个底线提醒本地模型方案要确保数据不出边界。你觉得代码丢到本地就安全了但各种依赖和日志会实时上报到什么服务器你并不总是能看清。生产环境的敏感代码务必用完整可控的隔离方案。5. 工程化路上我替你踩过的坑问题排查实录5.1 token 消耗突然翻倍先查 Skill 和 MCP 的噪音接入 Skills 和 MCP 之后我遇到的第一件糟心事是 token 消耗暴涨。第一次用完整工程化流程做重构消耗比裸用还高接近翻倍。定位之后发现主要原因是两处噪音。第一处是 skill 的 description 写得太宽泛导致每次任务都有好几个不相关 skill 被加载进来白白读了几百行文档。第二处是 MCP 工具列表太长Agent 在会话初期会花不少轮次做工具探测逐个确认这个工具能不能用、是干什么的。解决方向很明确。第一全局只保留少量高频 skill其余改成项目级按需加载description 写成人话里的触发条件。第二严格控制 MCP 暴露的工具数量不同的数据源拆成独立的 Server按任务范围临时接入。第三大任务让 Claude 先输出执行计划再动手这个确认环节看着多花了一次往返实际能省掉大量无意义跑动。我把这些调完以后同样一次重构的 token 消耗大概省了一半。所以在我这里token 突然暴涨现在会触发一次检查是不是又有什么 skill 被误触发了是不是某个 MCP Server 暴露了太多不相关的工具。5.2 上下文爆掉、Skills 互相打架怎么办长会话里的上下文问题是工程化之后的新痛点。会话拉长以后Claude 会出现早期记忆衰减开始遗忘会话开头我强调的约束。更麻烦的是多个 skill 同时命中时规则会打架。我踩过的一个具体例子是code-reviewskill 要求尽量保持现有代码结构、减少无谓改动security-auditskill 要求高风险写法必须替换掉。两个 skill 同时命中Agent 输出开始犹豫一会儿往左改一会儿往右改最后改出来的 diff 既不够保守也不够安全。我的解法有三层。第一在 skill 里写清楚生效范围本文件仅用于处理 xxx 场景其他场景忽略。第二给冲突规则定优先级一般在文件头写如果与其他规则冲突以本文件为准。第三最重要的把全局平级的 skill 数量降下来改成一个总纲 N 个细分总纲里写项目铁律细分里写场景化操作尽量减少交叉覆盖。如果会话已经爆掉别硬撑。用合并上下文或者直接开一个新会话配合项目索引快速恢复状态比在废墟里继续对话高效得多。5.3 MCP 连不上、工具列表为空的排查思路MCP 接入初期我遇到过的连接故障基本可以列成一张速查表。现象常见原因排查思路Server 启动但客户端超时npx 首次下载依赖包太慢预先把 Server 全局安装避免每次启动都拉包工具列表为空Server 没正确暴露工具用 MCP Inspector 单独调试看 Server 返回的工具清单容器内访问不到本地 Server进程隔离网络命名空间不同容器里改用宿主机的可达地址而不是 localhost路径相关操作全报权限错误添加 Server 时没有传入该路径回看claude mcp add启动参数把路径白名单补全这里面我想重点强调权限边界的意识。很多 MCP Server 的能力是路径范围即权限范围你把整个根目录暴露给文件系统 ServerAgent 就拥有了整个磁盘的读写能力。我在实践中只给项目根目录和几个必要的工作目录数据库类 Server 只给只读账号连写库权限都不开放。这个边界比任何安全提示词都管用。调试工具方面MCP Inspector 是排查的得力助手。它能直接连接本地 Server查看工具定义、手动调用工具、检查返回结果当场就能判断问题是出在 Server 本身还是出在客户端调用上。5.4 那句Your organization has disabled...到底是什么意思团队协作时有一个很经典的报错同事在自己电脑上装好环境一运行就出现这段英文提示。第一反应都以为是环境问题、网络问题、或者 key 配错了但实际上都不是。这句提示的意思是组织级的 Claude 订阅策略没有放行 Claude Code 的使用权限。注意这里的关键词是组织级。也就是说这跟你的安装步骤、网络状态完全无关是管理员在组织控制台里把 CLI/Claude Code 相关的开关关掉了。解决方式也不在技术层面。组织管理员需要到控制台里给成员启用 Claude Code 的使用权限或者把订阅方案调整到支持 CLI 的档位个人用户则要先确认自己的订阅确实包含 Claude Code 的权限而不是单纯的网页版订阅。这个报错给我最深的教训是工程化的第一课不是技术配置而是权限设计——团队里谁有 Agent 执行权、哪些仓库允许被自动修改、CI 环境里怎么授权这些事必须在铺开之前定清楚。6. 最后的体会和一条实用建议经历这一轮从裸用到工程化的折腾我最深的体会是Claude Code 裸用的时候是一台性能很好的肌肉车Skills 和 MCP 则是给车装上了导航、合规路线和工具箱。肌肉车能跑得快但只有装好这些你才敢让它每天在复杂的项目里干活。我最后悔的不是没有早点用上 Skills 和 MCP而是没有早点把团队的经验沉淀成 Skill。以前新同事上手项目要靠老师傅口口相传现在把规范写进 Skill所有人都能得到一致的指导这比任何新人文档都好用。最后分享一条我的实操经验把 Skills 目录当作代码一样管理纳入版本控制每次修改都走 reviewMCP 配置用项目级的.mcp.json提交进仓库每周复盘一次 token 账单看看哪个 Skill 或者哪个 MCP Server 在偷偷吃资源。从一个项目、一个 Skill、一个 MCP Server 开始小步迭代不要一上来就搞全家桶。等这套东西跑顺了你会发现自己进入了一个新的阶段——AI 不是帮你敲代码的工具而是可以和你一起把项目往前推的伙伴。