如果你最近开始在终端里用 Claude Code大概率和我一开始的状态一模一样裸用。打开终端敲一句claude然后把需求像聊天一样丢给它让它读代码、改文件、跑测试能跑通就算胜利。头两个星期我也沉浸在这种“AI 替我干活”的爽感里但很快问题就来了——每次新开会话它都不认识我的项目规范让它调用 Git、操作数据库、访问设计稿它只能干瞪眼更别提那些需要专业软件配合的流程基本等于手动复制粘贴。真正改变我工作方式的是两样东西Skills和MCP。标题里这三个词——Claude Code、Skills、MCP——放在一起就是我们常说的“AI 开发工作流”工程化的完整拼图。这篇博客不聊概念定义就聊我真正踩过的坑、写过的配置、总结出的方法。无论你是刚接触 Claude Code 的新手还是已经在裸用但总觉得差点意思的开发者这篇内容应该能帮你把工具链真正立起来。1. 为什么我会从“裸用”开始又为什么不得不走向工程化1.1 裸用的舒适区与它的隐性成本裸用阶段的体验其实相当不错。Claude Code 本身是一个运行在终端里的编程代理它最大的特点就是把“读代码—想方案—改文件—跑命令”这整条链路串了起来。你只需要在项目目录里启动它它就能通过内置的 Bash 工具执行命令、通过文件读写工具直接修改源码甚至能自己打开浏览器查看页面效果。这种一体化体验比过去在网页对话框里粘贴代码、再把结果复制回来要高出一个维度。但舒适区是有代价的。裸用最明显的痛点是上下文饥饿每开一个会话代理都要重新读取项目结构、关键文件、编码风格。项目一大你三分之一的时间都花在“让它先读懂项目”上。第二个痛点是工具边界Claude Code 默认能操作文件、终端但它不知道你公司的代码仓库地址、连不上数据库、没法操作 Figma 设计稿、也不能跟调试器对话。第三个痛点是能力不可复用你在一次会话里辛辛苦苦教出来的“最佳实践”换一个会话就全部忘光就像每次都要重新教一遍实习生。1.2 一个真实项目把问题逼到了临界点让我决定彻底改造工作流的是一个中小型前端项目。项目里有一套自定义的组件规范、模块命名规则和提交信息格式每次写代码我都得在提示词里反复叮嘱但 Claude Code 还是会偶尔“忘记”产出不符合规范的代码。我试过把规范文档直接拖进上下文但项目一复杂几千行的规范文档反而占满了上下文窗口真正需要集中注意力的业务逻辑反而被挤掉。后来我开始尝试把规范写成一份结构化的AGENTS.md文件放到项目根目录让代理每次自动读取。这算是最初级的“工程化”也确实解决了一部分问题。但更复杂的场景——比如“帮我根据 Figma 设计稿生成组件代码”“帮我用调试器定位崩溃现场”就不是一份文档能解决的了。这时候我才意识到真正缺少的是两个东西一套可以让代理稳定复用能力的机制Skills以及一条让代理对接外部工具的标准通道MCP。说白了裸用是在用对话的灵活性掩盖能力的匮乏工程化则是把能力和工具都变成基础设施。2. 先搞清楚三个概念Claude Code、Skills、MCP 到底分别是什么2.1 Claude Code运行在终端里的编程代理Claude Code 不是聊天网页也不是普通 CLI 工具。它是一个能主动感知项目环境、调用命令、修改文件的智能代理。直观理解你在终端里运行claude进入一个交互式 REPL但它比传统 REPL 多了一整套“动手能力”。它有自己的权限体系默认情况下命令执行需要你按快捷键确认也可以配置自动允许白名单命令实现无人值守。我建议你先记住一个事实Claude Code 是执行者不是知识库。它的聪明程度取决于两件事——模型本身的推理能力以及它当时能访问到的上下文和工具。Skills 和 MCP 这两个设计本质上都是在“扩充它可访问的资源”而不是“让模型变得更聪明”。2.2 Skills插拔式的专业技能包Skills 是 Anthropic 为代理设计的一种“能力包”你可以把它理解成给 Claude Code 安装的“职业技能证书”。每个 Skill 是一个独立的目录里面至少包含一个SKILL.md文件文件开头用 YAML 格式写元信息比如技能名称、适用场景、描述后面用 Markdown 写详细的执行步骤、注意事项、工作流。目录里还可以放scripts脚本、参考资料、模板文件。它与传统提示词工程的最大区别在于按需加载。如果没有 Skills 机制你想让代理会写单元测试就得把“如何写单元测试”的完整指南塞进每次对话有了 Skills代理会先判断当前任务是否匹配某个技能匹配上了才读取对应的SKILL.md。这样既不会污染上下文又能把复杂的流程拆成可维护的模块。我后来自己写了不少 Skills感受是这本质上是在给代理建立一套可复用的操作手册。2.3 MCP工具接入的统一协议MCPModel Context Protocol解决的是“连接”问题。想象一下电脑上的 USB-C 接口不管你是接显示器、硬盘还是手机只要协议统一插上就能用。MCP 就是给 AI 代理设计的“USB-C”——它定义了一套标准化的客户端-服务器通信协议基于 JSON-RPC 2.0让代理能够发现并调用外部工具。一个 MCP 服务器可以暴露若干工具比如文件搜索、Git 操作、浏览器控制、数据库查询。Claude Code 作为 MCP 客户端在会话中会自动获取这些工具的描述和参数格式并在需要时调用它们。传输方式上最常见的是 stdio子进程通信和 HTTP/SSE远程服务配置都在 JSON 文件里。你不需要理解协议底层每个字段但你必须知道一件事只要有人为某个软件写好了 MCP 服务AI 代理就能像使用内置工具一样使用它。2.4 三者关系一张白话说清的架构图把三者关系用大白话讲清楚就是Claude Code 是身体Skills 是方法MCP 是感官和手脚。身体负责思考和移动方法决定它遇到问题时按照什么套路处理感官和手脚负责把外部世界的信息传进来、把操作执行出去。举个例子我想让 Claude Code 检查设计稿还原度。MCP 负责从 Figma 拉取设计稿信息感官Claude Code 读取前端代码并截图比对身体而一个“视觉走查” Skill 则规定了检查哪些指标、按什么顺序排查方法。没有 MCP代理接触不到设计稿没有 Skill它即使拿到设计稿也不知道该按什么标准查。这三个组件不是替代关系而是各管一层的协作关系。3. 实操第一步把 Claude Code 装好、跑起来3.1 安装、登录与版本升级的注意事项Claude Code 的安装很简单核心依赖是 Node.js 环境。官方推荐的安装方式是通过 npm 全局安装命令行工具装完后在终端里执行claude就会进入登录流程需要你的 Claude 账号授权。这里有一条特别容易被忽视的坑Agent 类工具迭代非常快旧版本经常会出现上下文丢字、工具调用异常的问题所以一定要养成升级的习惯。我当时就是因为没有升级卡在一个已经修复的权限 bug 上排查了半天。升级命令也不复杂重新执行安装命令即可。如果你是在 CI/CD 或云服务器上使用记得把登录凭证放到环境变量里避免交互式登录无法执行。安装完成后我建议你做的第一件事是跑一个最小测试让它读当前目录下的一个文件做一个小修改确认文件读写链路正常。3.2 在 VS Code 里配置 Claude Code 联动终端里用 Claude Code 体验很好但遇到复杂代码时我还是更习惯在 VS Code 里看代码。官方提供了 VS Code 扩展安装后可以在编辑器右侧打开一个交互面板同一个会话既能看代码又能让代理操作文件。配置方面有两个点值得注意。第一扩展会复用你终端里的登录状态所以终端登录一次VS Code 里就不用重复登录。第二如果你自定义了模型的 API 端点比如用第三方模型VS Code 扩展也需要同步修改环境变量否则会出现“终端能用、扩展不能用”的割裂现象。我当时就是用 CC Switch 切换了模型之后忘了在 VS Code 的启动脚本里同步配置折腾了一下午。3.3 用 CC Switch 接入 DeepSeek、Qwen、GLM 等第三方模型Claude Code 默认绑定 Claude 模型但它的底层设计允许通过环境变量替换 API 端点和密钥。社区里常说的 CC Switch就是这样一个可视化切换工具本质上是替你管理一组环境变量ANTHROPIC_BASE_URL指向模型服务的兼容端点ANTHROPIC_AUTH_TOKEN填入对应的密钥ANTHROPIC_MODEL指定模型名称。实际操作上我在 CC Switch 里配了三套配置一套是官方 Claude用于复杂架构设计一套是 DeepSeek V3用于日常编码和成本敏感的任务还有一套是本地通过 LM Studio 启动的模型用于离线环境下验证脚本逻辑。切换的瞬间生效不用重启终端非常方便。这里有个关键提醒不是所有 Skills 和 MCP 工具在第三方模型上都能正常工作。Claude Code 的很多工具调用能力是 Agent 循环的一部分模型能力不够容易导致工具调用格式错误我后面会专门讲怎么排查。3.4 让 Claude Code 安全地直接执行终端命令裸用阶段我习惯每条命令都手动确认但工程化之后频繁确认会打断 Agent 的连续思考。Claude Code 提供了权限配置可以让它直接执行特定命令。在交互界面里可以用/permissions打开设置选择“允许所有命令”“询问”“拒绝”三种模式。我的建议是分级管理对只读命令cat、git status、ls直接允许对可能有副作用的命令rm、git push、npm install保持询问。你还可以通过配置规则把某些命令或路径直接加入白名单比如允许在指定的构建目录下执行npm run build。这样既保留了自动化效率又不至于让代理在关键时刻做出危险操作。永远不要把“允许所有命令”开成默认除非你在跑一个完全隔离的容器环境。4. 工程化核心Skills 的安装、查找与自研4.1 去哪里找 Skills官方市场、GitHub 与社区推荐Skills 生态兴起得很快目前主要来源有三个。第一个是官方市场Claude Code 提供了内置的技能市场可以直接在交互界面里浏览和安装官方精选的 Skills分类覆盖代码审查、单元测试、架构设计、文档生成等常见场景。第二个是 GitHub很多开发者把自己实践沉淀的 Skills 仓库开源出来搜索关键词claude skills能看到大量仓库其中社区最知名的是superpower skills系列。第三个是各类技术社区和博客分享有人会把自己的技能配置整理成文章发布。安装前一定要看一眼这个SKILL.md的内容是否安全毕竟它本质上是一段会指导代理做事的指令。我见过某些“花哨技能”里隐藏了不安全的命令提示对代理无害但可能诱导它尝试执行你不想执行的系统操作。原则很简单不装来源不明的技能装之前先读文件。4.2 安装 Skills 的正确姿势目录与命名规则Skills 的加载遵循目录约定。Claude Code 会扫描几个特定目录用户级目录~/.claude/skills/项目级目录.claude/skills/以及通过插件或市场安装的目录。把某个技能目录放进去它就能在会话中被发现。目录结构通常是这样的~/.claude/skills/ └── code-review/ ├── SKILL.md └── scripts/ └── check_style.pySKILL.md开头是 YAML frontmatter包含name和description。description写得越精准代理越能在合适的时机自动激活这个技能。比如不要写“处理代码”而要写“当用户要求做代码审查、检查代码规范时才使用”。我还发现一个细节技能名称最好用中划线分隔的小写单词不要包含空格和特殊字符否则在部分文件系统上容易出问题。4.3 自己动手写一个 Skill结构、元信息与脚本设计写自己的 Skill 并没有想象中那么高深本质上是“把你想教给代理的流程固化成文件”。先创建一个目录比如frontend-audit在目录里新建SKILL.md。开头是 frontmatter--- name: frontend-audit description: 对前端项目执行规范化审查检查组件模式、样式约定和提交信息。仅当用户要求审查前端代码时使用。 ---正文部分我一般按四个小节组织适用场景、执行步骤、评判标准、常见坑。执行步骤要写清楚操作顺序比如“先读取 package.json 确认依赖模式”“再扫描 src/components 下的组件文件”“最后用脚本检查样式 token”。评判标准要具体比如“组件文件命名必须为 PascalCase”“禁止直接使用魔法数字”。如果技能需要执行脚本就把脚本放在scripts目录然后在SKILL.md中说明如何调用。脚本设计上要克制不要指望脚本做太多事尽量让脚本做机械性的检查把需要判断力的审查留给代理本身。我写过一个检查“TODO 残留”的脚本只有二十行但配合代理的上下文理解效果远超复杂脚本。4.4 实战案例为一个前端项目写“代码审查”Skill拿我最近维护的一个 Vue3 项目举例。裸用阶段让 Claude Code 审查代码它只能泛泛地说“代码整体清晰存在一些可优化空间”——这种毫无用处的废话。后来我写了一个frontend-review技能把团队规范全部固化进去第一组件命名。规定所有组件文件名必须是大驼峰且目录层级与路由结构对应。第二状态管理。规定只有stores目录下的文件可以引入 Pinia组件内禁止直接修改全局状态。第三样式规范。颜色一律从设计 token 引用不允许硬编码色值。第四提交信息格式。必须是type(scope): subject结构比如fix(form): correct validation logic。写好之后的效果是立竿见影的。我在会话里输入“审查一下昨天提交的代码”Claude Code 会在几秒内自动加载这个技能然后逐条对照规范检查。凡是违规项它都能明确指出文件和行号。这让我明显感觉到代理从“泛泛的建议者”变成了“懂团队规矩的同事”。这个经验是最值得复制的先找出那些你反复在提示词里强调的内容把它们变成技能文件基本不会有错。4.5 值得收藏的 Skills 推荐清单根据我这段时间的筛选和实际使用推荐几个值得关注的 Skills 方向。第一是superpower skills它是一组打包的高阶技能集合内含系统设计、日志分析、复杂任务拆解等模块适合做代理能力扩展的基础包。第二是前端开发相关 skills社区里有很多针对 React、Vue、Tailwind 等框架的技能能大幅提升页面生成质量。第三是GitHub skills主要用于规范提交信息、自动生成 release notes、审查 PR。第四是写作类 skills不只是写代码还有人用 Skills 来做论文润色、技术文档规范化这类技能本质上和代码审查是同一个思路只是内容不同。安装这些技能之前我都坚持读一遍它们的SKILL.md。不读一遍就启用就像让别人给你写操作手册但你从不检查内容一样风险太大了。5. MCP 接入实战从文件系统到专业软件5.1 MCP 服务器配置基线JSON 与命令行两种方式MCP 接入的第一步是配置服务器。Claude Code 支持在配置文件里定义 MCP 服务器也可以在会话里用命令添加。配置文件的典型结构是定义一个mcpServers对象每个服务器标明command、args和env。一个简单的例子{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /path/to/workspace] } } }这里有几个坑要提醒。第一command不要在 Windows 上直接用npx要写cmd /c npx或者使用.cmd后缀否则会出现静默失败。第二env里的密钥不要硬编码提交到仓库我用的是专门的环境变量文件加载。第三如果 MCP 服务器启动失败Claude Code 未必会在会话里弹出红色错误它可能只是“感知不到工具”这时候需要用claude mcp list之类的命令检查连接状态。5.2 通用型 MCP文件、Git、浏览器与数据库通用 MCP 是工程化起步的第一批装备。文件系统 MCP 提供了更精细的文件读写和搜索能力比默认工具更适合跨目录操作。Git MCP 可以让你用自然语言执行“查看当前分支的未提交改动”“列出最近五次的提交记录”这类操作比手动敲命令更高效。浏览器 MCP 的价值在于前端工作流尤其是 Dify 这类低代码平台也推出了浏览器 MCP可以让代理在浏览器里操作页面、抓取数据。数据库 MCP 则把“查数据库”变成了代理的默认技能我可以直接说“查一下订单表最近十天的数据分布”代理会生成 SQL 并执行返回结果。我建议逐步接入不要一次配十个服务器否则工具描述会占用大量上下文窗口反而让代理“眼花缭乱”。5.3 专业软件场景Unreal、Altium、IDA、TIA 这些重量级选手通用 MCP 只是开胃菜真正让工作流发生质变的是专业软件 MCP。做游戏开发的同事应该听说过 Unreal Engine 5.8 MCP 服务社区已经实现了让代理控制编辑器、创建关卡、修改蓝图参数的桥接硬件工程师那边有人把 Altium Designer 的设计接口包成了 MCP让 AI 能读取 PCB 信息、检查约束逆向和二进制安全方向IDA 和 x32dbg 的 MCP 插件也已经出现可以在调试会话中直接让代理查询反汇编结果或操作断点工业自动化领域甚至还有 TIA 项目的交付包。这些方案的共同点是把原本封闭的软件 API 用 MCP 协议重新包装一遍。接入方法也可复用先找到对应 MCP 服务配置好连接参数通常是本机端口或共享内存然后在 Claude Code 里添加服务器即可。我不建议你在没有实际需求的情况下跟风安装这些东西——MCP 是解决问题的不是用来堆数量的。我目前只保留三四个常用的 MCP 服务器其余全部按项目需求临时启用。5.4 用 MCP 工具把流式输出内容写到文件很多人写代码时喜欢让 AI 生成一大段完整代码但在生成超长内容时代理的输出长度有限经常生成到一半就中断了。我的解决方案是让 MCP 的文件写入工具来承担“搬运”职责先让代理把思考过程或代码块分块写入临时文件最后再统一合并。具体做法是给代理提供“追加写入”的指令模板让它在生成内容时每完成一部分就调用一次 MCP 工具把内容追加到目标文件。这样有两个好处一是规避了单次回复的长度限制二是生成过程像流水一样你可以随时查看文件内容发现问题及时叫停。我遇到过的障碍主要是编码问题写入文件时默认编码不统一导致中文注释乱码。后来在配置里明确了 UTF-8 编码约定这个问题才消失。5.5 接入 Figma 和设计工具时绕不开的授权问题前端开发绕不开设计稿而 Figma 的设计文件通常需要授权才能访问。Figma 官方 MCP 服务器要求你提供一个个人访问令牌personal access token这个令牌在 Figma 账号设置里生成。在 MCP 配置里把令牌放到env中代理就能代表你去读取设计稿、获取图层信息和样式数据。这里最容易踩的坑是权限范围。个人令牌默认拥有该账号能访问的所有文件如果你在一个大团队里等于让代理拥有了所有设计资料的读取能力。我建议申请一个专门的“机器人账号”或使用权限受限的应用令牌只开放必要项目降低安全风险。类似的蓝湖也有对应的 MCP 接入方案授权思路一致都需要先申请接口凭证。没有授权的时候代理会报“无法访问”但是不会告诉你具体是网络问题还是权限问题所以排查时需要先确认令牌是否有效。6. 常见问题与排查实录6.1 订阅访问被禁用那句困扰很多人的报错有一个报错极具代表性“Your organization has disabled Claude subscription access for Claude Code”。遇到这个提示通常不是你的账号有问题而是企业策略层面的限制。Claude Code 在组织场景下管理员可以关闭成员使用 Claude Code 的权限。解决办法有两个方向一是联系管理员确认订阅计划是否包含 Claude Code 权限二是如果只是个人使用用个人账号登录不依赖组织订阅。还有一种常见情境是多人共用机器时缓存了组织账号的登录态。这时候需要清理本地凭证重新登录个人账号。注意不要用第三方脚本强行修改权限配置很容易触发风控得不偿失。6.2 Codex 找不到 MCP工具发现失败的根因我同时在用 OpenAI Codex 和 Claude Code 两套 Agent遇到过 Codex 加载不到 MCP 工具的问题。排查下来根因大多是配置文件路径不对。Codex 对 MCP 配置的读取路径和 Claude Code 不同它默认读取特定位置的 JSON 文件如果你把服务器配置写到了 Claude Code 的配置里Codex 当然看不到。另一个原因是启动顺序。有些 MCP 服务器依赖本地服务先运行比如数据库 MCP 要等数据库实例起来如果 Agent 启动时服务还没就绪工具列表就会缺失。解决方法很简单先启动依赖服务再启动 Agent然后用工具列表检查命令确认服务器有没有注册成功。6.3 流式输出到文件内容没刷新、中文乱码的真相流式输出到文件时最典型的问题是“文件没变化”。其实不是没变化而是部分编辑器不会自动感知外部写入需要手动刷新。这不是代理的问题是编辑器缓存问题。用 VS Code 时我一般关闭自动保存写完后手动刷新或直接看终端tail输出。中文乱码的根源是编码。默认情况下某些 MCP 写文件工具以 UTF-8 写入但 Windows 终端和部分编辑器默认是 GBK显示时才乱码。我建议在项目根目录放一个.editorconfig明确charset utf-8同时在写入指令模板里指定编码参数。这样两边对齐乱码就再没出现过。6.4 第三方模型接入后Skills 失效和工具调用质量下降用 CC Switch 切换到 DeepSeek 或 Qwen 之后我发现 Skills 仍然能加载但工具调用的格式稳定性明显下降偶尔会出现“想用工具但参数写错”的情况。这不是模型能力不行而是这些模型在 Agent 工具调用训练数据上不如原生模型充分。应对办法有两个一是降低任务复杂度把一个大任务拆成多个小步骤减少一次会话中需要连续调用工具的次数二是尽量选择工具调用兼容性好的模型版本。DeepSeek V3 和 Qwen 最新版本在工具调用上已经做得不错但如果你开的对话超过二十轮还是要做好中途出错的准备。我现在的策略是复杂架构设计用官方模型简单编码和日志分析用第三方模型。6.5 排查问题速查表现象常见根因快速排查方案MCP 工具列表为空配置路径错误 / 服务器启动失败用配置文件检查命令查看实际注册项命令执行被拒绝权限规则过严用/permissions调整白名单第三方模型工具调用出错模型能力不匹配切换模型或拆解任务Skills 未被触发description 描述不精准在提示词中显式提到技能名输出内容乱码编码不一致统一 UTF-8 并检查.editorconfig登录态失效组织策略或凭证过期清理凭证重新登录7. 一些经验与扩展想法讲到这里估计你已经能感受到Claude Code、Skills 和 MCP 组合起来完全可以把一个“聪明的对话窗口”变成“真正参与工程流程的同事”。但我也想说工程化并不是越复杂越好。我在实际搭建这套体系时最深的体会是要给代理做减法。Skills 多了代理反而会因为加载判断不准确而变得迟钝MCP 服务器多了工具描述会占据大量上下文。我现在维护一个“能力最小集”五六个高频 Skills 和四个 MCP 服务器覆盖代码审查、数据库查询、浏览器调试、设计稿获取这几个核心场景。新技能先临时启用用顺手了再转正用不上的就删掉。最后再分享一个小技巧把常用的 MCP 配置和 Skills 目录纳入版本管理跟项目一起走。这样新同事克隆代码后只需要跑一条安装命令整套代理工作流就可以在本地复现。我甚至见过有团队把代理的能力配置写进 CI 流水线让代码提交前自动跑一轮技能检查。这种把人的经验和标准化能力沉淀到代码库里的思路也许才是 AI 开发工作流工程化的真正方向。