1. 从“裸用”到工程化为什么我决定重构自己的 AI 开发工作流最早用 Claude Code 的时候我跟大多数人一样就是打开终端敲一句需求等它吐代码复制粘贴跑一下报错了再贴回去让它改。这个阶段我管它叫“裸用”——没有任何结构没有任何复用每次对话都是从零开始上下文全靠临时拼凑。效率确实比纯手写高但问题也很明显同一个项目里反复出现的规范、目录结构、接口约定每次都要重新解释一遍换一个会话窗口之前积累的上下文全部归零团队里几个人各用各的提示词产出风格完全不一致。后来我开始接触两个东西Claude Code Skills和MCP。前者解决的是“能力封装与复用”的问题后者解决的是“工具与数据源接入”的问题。把这两个东西组合起来之后我的开发工作流发生了质的变化——从每次都要手把手教 AI 干活变成了 AI 按照我预设的工程规范自动运转。这篇文章就是把这套工作流的搭建过程、核心原理、实操细节和踩过的坑完整拆解一遍适合已经在用 Claude Code 但还停留在“裸用”阶段的开发者也适合想了解 Agent Skills 和 MCP 到底怎么落地的人。先说结论Skills 本质上是把“提示词 脚本 资源文件”打包成一个可复用的能力单元MCP 本质上是把外部工具和数据源以标准化协议暴露给模型。两者结合你就能构建一个真正意义上的“AI 开发工作台”而不是一个只会聊天的代码补全器。2. 核心概念拆解Skills 和 MCP 到底在解决什么问题2.1 Claude Code Skills 的本质把经验固化成可执行的能力包很多人第一次听到 Skills 会以为是插件市场里的那种扩展其实不是。Skills 的核心逻辑是用文件系统组织一套指令、脚本和参考资料让模型在需要的时候自动加载并执行。一个 Skill 通常包含一个主描述文件比如SKILL.md里面写清楚这个 Skill 是干什么的、什么时候触发、执行步骤是什么再配合若干辅助脚本和模板文件。我自己的理解是Skills 解决的是“重复解释成本”的问题。举个例子我们团队的前端项目有一套固定的组件目录规范、状态管理约定、API 请求封装方式。以前每次让 Claude Code 写一个新页面我都要在提示词里把这些规范重复一遍写少了它就跑偏写多了 token 消耗巨大。做成 Skill 之后我只需要在描述文件里把这些规范写一次之后每次触发这个 Skill模型自动读取完整规范产出直接符合团队标准。从技术实现角度看Skills 的加载机制是基于文件路径和描述匹配的。Claude Code 会在特定目录下扫描 Skill 定义根据当前任务上下文判断是否需要激活某个 Skill。这个判断过程依赖描述文件里的触发条件说明所以写清楚“什么时候用这个 Skill”比写清楚“这个 Skill 做什么”更重要。2.2 MCP 的定位让模型真正“够得着”外部世界MCP 全称是 Model Context Protocol翻译过来就是模型上下文协议。这个名字听起来很抽象但它的作用非常具体定义了一套标准接口让模型能够调用外部工具、读取外部资源、执行外部操作。在没有 MCP 之前模型和外部世界的交互基本靠“你贴给它”或者“它生成代码你自己跑”。有了 MCP模型可以直接调用你配置好的工具服务比如查数据库、读文件系统、调 API、操作设计工具等等。我一开始也觉得 MCP 有点多余心想我直接让 Claude Code 执行终端命令不就行了。但实际用下来发现区别很大。直接执行终端命令是“一次性”的每次都要重新构造命令、处理输出、解析结果。而 MCP 是把一个工具的能力标准化暴露出来模型知道这个工具接受什么参数、返回什么格式调用过程更稳定错误处理也更规范。更重要的是MCP 让“工具复用”成为可能。你配置好一个数据库查询的 MCP Server之后所有会话都能用不用每次重新交代连接信息、表结构、查询规范。这对于需要频繁访问外部资源的开发场景来说效率提升非常明显。2.3 两者结合的价值从“对话式编程”到“工程化流水线”单独用 Skills你得到的是“能力复用”单独用 MCP你得到的是“工具接入”。两者结合之后产生的是一个完整的工程化闭环Skills 负责定义“怎么做”和“按什么规范做”MCP 负责提供“用什么做”和“从哪里拿数据”。模型在这个框架里不再是一个需要你反复调教的实习生而是一个按照既定工程规范自动运转的执行单元。我举个实际场景来说明这种结合的价值。我们有一个内部的数据分析平台前端用 React后端用 Python数据存在 PostgreSQL 里。以前我要做一个新报表页面流程是这样的先让 Claude Code 读一下现有的页面结构再告诉它我们的组件规范再让它写 SQL 查询再让它把查询结果映射到前端组件最后手动跑一遍看有没有问题。整个过程要来回对话十几次。现在我的做法是做一个“报表页面生成”Skill里面写清楚页面结构模板、组件使用规范、数据映射约定再配一个 PostgreSQL 的 MCP Server让模型能直接查表结构和样本数据。之后我只需要说“帮我做一个按周统计用户活跃度的报表页面”模型会自动激活 Skill通过 MCP 读取表结构按照规范生成完整代码。整个过程从十几次对话压缩到一两次确认。3. 环境搭建与基础配置从零把工作流跑起来3.1 Claude Code 的安装与基础环境准备Claude Code 的安装方式取决于你的操作系统。macOS 和 Linux 用户通常通过包管理器或者官方提供的安装脚本完成Windows 用户建议在 WSL 环境下操作因为很多工具链在原生 Windows 下会有兼容性问题。安装完成后你需要配置 API 访问凭证这一步根据你使用的模型服务商不同而有所差异。我自己的环境是 macOS iTerm2 zsh安装过程比较顺畅。需要注意的是Claude Code 对 Node.js 版本有要求建议用最新的 LTS 版本。如果你之前装过旧版本建议先清理干净再装避免路径冲突。# 检查 Node 版本建议 18 以上 node -v # 如果版本过低用 nvm 切换 nvm install --lts nvm use --lts安装完成后第一次运行需要初始化配置。这个过程中会让你选择模型、配置访问凭证、设置工作目录等。工作目录建议设置成你日常开发的项目根目录这样 Claude Code 能直接访问项目文件Skills 和 MCP 的配置也能跟着项目走。注意如果你在公司网络环境下使用可能需要配置代理或者私有镜像源。这部分根据实际情况处理核心原则是确保 Claude Code 能正常访问模型服务。3.2 Skills 的目录结构与加载机制Skills 的存放位置通常有两个选择全局目录和项目目录。全局目录下的 Skills 对所有项目生效适合放通用能力比如代码审查、提交信息生成、文档撰写等。项目目录下的 Skills 只对当前项目生效适合放项目特有的规范比如组件模板、API 约定、数据库访问规则等。一个标准的 Skill 目录结构大概长这样.claude/skills/ report-page-generator/ SKILL.md templates/ page-template.tsx api-template.ts scripts/ validate-schema.sh references/ component-conventions.mdSKILL.md是核心文件里面需要写清楚几个关键信息这个 Skill 的名称和描述、触发条件、执行步骤、依赖的资源文件。描述部分要写得足够具体让模型能准确判断什么时候该激活这个 Skill。触发条件可以写关键词也可以写场景描述。我踩过的一个坑是一开始把SKILL.md写得太笼统比如“用于生成前端页面”结果模型在任何跟前端相关的任务里都会激活这个 Skill包括简单的样式修改。后来我把描述改得更精确比如“用于从零生成符合团队规范的新报表页面包含路由配置、API 封装和组件组装”激活准确率就高了很多。3.3 MCP Server 的接入与配置要点MCP Server 的配置通常写在 Claude Code 的配置文件里格式根据你使用的 MCP 实现不同而有所差异。核心配置项包括Server 名称、启动命令、参数、环境变量等。配置完成后Claude Code 会在启动时自动拉起这些 Server并在需要的时候调用。{ mcpServers: { postgres: { command: npx, args: [-y, modelcontextprotocol/server-postgres], env: { DATABASE_URL: postgresql://user:passlocalhost:5432/mydb } }, filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /path/to/project] } } }配置 MCP Server 的时候有几个关键点需要注意。第一是权限控制尤其是文件系统和数据库类的 Server一定要限制访问范围避免模型误操作。第二是连接稳定性有些 Server 在长时间空闲后会断开需要配置重连机制。第三是输出格式尽量让 Server 返回结构化的数据这样模型解析起来更准确。我实际用下来最实用的几个 MCP Server 分别是文件系统访问、PostgreSQL 查询、Git 操作、以及一个自定义的内部 API 网关。文件系统和 Git 是高频使用的数据库查询在做数据相关功能时必不可少自定义 API 网关则把内部服务的调用标准化了。4. 实操过程搭建一套完整的 AI 开发工作流4.1 第一步定义项目级的 Skill 体系搭建工作流的第一步不是写代码而是梳理你日常开发中反复出现的模式和规范。我建议拿一张纸把你最近一周让 Claude Code 做的事情列出来然后归类。你会发现很多任务其实是重复的只是输入不同。这些重复任务就是 Skill 的候选。以我的前端项目为例我梳理出了四个核心 SkillSkill 名称触发场景核心内容page-generator需要新建页面时页面模板、路由配置、组件组装规范api-builder需要新增接口封装时请求方法封装、错误处理、类型定义component-creator需要新建通用组件时组件结构、样式约定、测试文件code-reviewer提交代码前审查清单、常见问题、规范检查每个 Skill 的SKILL.md我都遵循一个固定结构先用一段话描述这个 Skill 的用途和触发条件然后列出执行步骤最后附上依赖的模板文件和参考文档。执行步骤要写得足够细细到模型不需要额外猜测就能执行。实操心得Skill 的描述文件不要一次写完美先写个初版用几次之后根据实际激活情况和产出质量再调整。我前后改了五六版才把激活准确率调到满意的水平。4.2 第二步配置 MCP Server 打通数据源Skill 定义好之后下一步是让模型能访问到需要的数据。这一步的核心是配置合适的 MCP Server。我的配置策略是能用官方 Server 就用官方官方没有的就自己写一个轻量的。官方 Server 里文件系统和 PostgreSQL 是我用得最多的。文件系统 Server 让模型能直接读取项目里的现有代码作为参考这对于保持代码风格一致性非常重要。PostgreSQL Server 让模型能查表结构和样本数据生成 SQL 的时候准确率高很多。自定义 Server 我写了一个内部 API 网关把公司内部几个常用服务的接口封装成 MCP 工具。这样模型在需要查用户信息、订单数据、配置项的时候可以直接调用不用我手动去查再贴给它。# 一个简化的自定义 MCP Server 示例 from mcp.server import Server from mcp.types import Tool, TextContent server Server(internal-api) server.tool() async def query_user(user_id: str) - list[TextContent]: 根据用户 ID 查询用户基本信息 # 实际调用内部 API result await internal_api.get_user(user_id) return [TextContent(typetext, textjson.dumps(result))] server.tool() async def query_order(order_id: str) - list[TextContent]: 根据订单 ID 查询订单详情 result await internal_api.get_order(order_id) return [TextContent(typetext, textjson.dumps(result))]写自定义 Server 的时候工具的描述要写得非常清楚包括参数含义、返回格式、使用场景。模型判断是否调用某个工具完全依赖这些描述。描述写得模糊模型要么不用要么用错。4.3 第三步串联工作流并验证效果Skill 和 MCP 都配置好之后就可以串联起来验证效果了。我拿一个真实需求来测试给数据分析平台新增一个“按渠道统计转化率”的报表页面。我的操作流程是这样的打开 Claude Code输入需求描述然后观察它的行为。理想情况下它应该自动激活page-generatorSkill通过 PostgreSQL MCP 查询渠道表和转化表的结构按照模板生成页面代码和 API 封装最后输出完整的文件列表和变更说明。实际第一次跑的时候并不顺利。模型确实激活了 Skill但查询表结构的时候只查了主表没有查关联表导致生成的 SQL 缺少 JOIN。我排查后发现是 MCP Server 的工具描述里没有强调“需要同时查询关联表结构”模型就只做了最直接的查询。调整方案是在 Skill 的执行步骤里加一条“生成 SQL 前先通过 MCP 查询所有相关表的结构包括外键关联的表。” 加上这一条之后第二次跑就正确了。这个调试过程让我意识到Skill 和 MCP 的配合不是自动就完美的需要在执行步骤里显式地引导模型去调用正确的工具。模型不会自己想到“我应该多查几张表”你需要在 Skill 里把这个意图写清楚。4.4 第四步迭代优化与团队推广工作流跑通之后接下来的重点是迭代优化和团队推广。迭代优化的方向主要有两个一是提高 Skill 的激活准确率减少误触发和漏触发二是提高产出质量减少人工修正的次数。我的做法是每次用完都记录一下这次激活对不对、产出有没有问题、哪里需要手动改。积累一周之后把高频问题归类针对性地调整 Skill 描述或 MCP 配置。比如发现模型经常忘记写单元测试就在 Skill 的执行步骤里加一条“生成组件后同步生成对应的测试文件”。团队推广方面我把 Skill 和 MCP 配置都放进了项目仓库的.claude目录下新成员克隆项目后自动获得这套配置。同时写了一份简短的内部文档说明每个 Skill 的用途和触发方式。这样团队里每个人用 Claude Code 的时候产出的代码风格和结构都是一致的代码审查的成本也降低了不少。5. 常见问题与排查技巧实录5.1 Skill 不激活或者激活错误怎么办这是最常见的问题。表现是你明明想让它用某个 Skill但它就是不用或者你只是改个样式它却激活了完整的页面生成 Skill。排查思路分三步。第一检查SKILL.md里的描述是否足够具体。描述太宽泛会导致误激活描述太窄会导致不激活。第二检查触发条件是否和当前任务匹配。如果你用的是关键词触发确认关键词是否出现在你的输入里。第三检查 Skill 的存放位置是否正确。项目级 Skill 要放在项目目录下全局 Skill 要放在全局目录下放错了就不会被扫描到。我的经验是描述文件里的第一段话最关键。模型主要根据这段话判断是否激活。所以这段话要同时包含“做什么”和“什么时候做”比如“当需要从零创建一个新的报表页面时使用包含路由、API 和组件组装”。5.2 MCP Server 连接失败或超时MCP Server 连接问题通常有几个原因启动命令写错了、环境变量没配、端口被占用、或者 Server 本身崩溃了。排查的时候先看 Claude Code 的日志输出通常会显示 Server 启动失败的具体原因。如果是命令找不到检查command和args是否正确。如果是环境变量问题确认env字段里的变量名和值都对。如果是端口冲突换一个端口。我遇到过一次比较隐蔽的问题Server 启动成功了但调用的时候一直超时。后来发现是 Server 内部的数据库连接池配置太小并发查询的时候排队了。把连接池调大之后就好了。所以如果 Server 能启动但调用慢要检查 Server 内部的资源限制。5.3 模型调用 MCP 工具时参数传错这个问题通常是因为工具的参数描述不够清楚。模型不知道某个参数是必填还是可选、格式是什么、取值范围是什么就容易传错。解决办法是在工具定义里把参数描述写详细。比如不要只写user_id: string要写user_id: 用户唯一标识格式为 u_ 开头的字符串例如 u_12345。描述越具体模型传参的准确率越高。另外可以在 Skill 的执行步骤里加一些示例展示正确的调用方式。模型看到示例之后模仿的准确率会高很多。5.4 产出代码不符合项目规范这个问题一般不是 Skill 或 MCP 的锅而是 Skill 里写的规范不够具体。比如你写了“遵循项目组件规范”但模型不知道具体规范是什么就会按自己的理解来。解决办法是把规范写进 Skill 的参考文件里并在执行步骤里明确要求模型读取这个文件。比如在SKILL.md里写“生成组件前先读取references/component-conventions.md严格按照其中的命名、目录结构、样式方案执行。”我还会在参考文件里放几个正例和反例模型对照着看产出质量会明显提升。5.5 常见问题速查表问题现象可能原因排查动作Skill 不激活描述太窄或位置错误检查描述关键词和存放路径Skill 误激活描述太宽泛收窄触发条件增加排除说明MCP 连接失败命令错误或环境变量缺失查看日志核对配置MCP 调用超时Server 内部资源不足检查连接池、并发限制参数传错工具描述不清晰补充参数格式和示例产出不规范规范未写入参考文件把规范文档化并显式引用6. 我在这套工作流里踩过的坑和总结的经验6.1 不要试图一次做完所有 Skill我一开始雄心勃勃想把所有能想到的场景都做成 Skill。结果花了两天写了十几个实际用的时候发现大部分都不成熟激活混乱产出质量参差不齐。后来我改变策略只做最高频的两三个场景用熟一个再做下一个。这样每个 Skill 都经过充分打磨质量有保证。6.2 MCP Server 的权限要最小化文件系统 Server 我一开始配置的是项目根目录后来发现模型有时候会去读一些不该读的文件比如包含敏感配置的.env文件。后来我把访问范围缩小到具体的源码目录敏感文件排除在外。数据库 Server 也是只给只读权限避免误操作。6.3 Skill 的版本管理很重要Skill 是会不断迭代的今天改一版明天改一版。如果没有版本管理改坏了都回不去。我的做法是把.claude目录纳入 Git 管理每次修改都提交写清楚改了什么、为什么改。这样出问题的时候可以快速回滚。6.4 团队协作时统一配置比统一提示词更有效以前团队里每个人都有自己的提示词习惯产出风格五花八门。现在把 Skill 和 MCP 配置统一放在项目仓库里大家用的是同一套规范产出自然就一致了。新成员入职的时候克隆项目就能获得完整的 AI 开发环境上手速度也快了很多。6.5 定期回顾和清理Skill 和 MCP 配置会随着项目演进变得过时。我每个月会花半小时回顾一下哪些 Skill 还在用、哪些已经废弃、哪些需要更新。废弃的及时删掉避免干扰模型判断。MCP Server 也是不再使用的及时从配置里移除减少启动开销。这套工作流从搭建到稳定运行大概花了我两周时间但之后每个功能的开发效率提升非常明显。最直观的感受是以前我需要花大量时间在“跟 AI 解释需求”上现在更多时间花在“确认 AI 的产出是否符合预期”上。前者是消耗性的后者是增值性的。如果你也在用 Claude Code强烈建议从今天开始把你最常做的那件事做成一个 Skill体验一下从“裸用”到工程化的差别。