3.4 MCP 与 Skills：给 AI 装上外部能力

📌 基于 2026-09 的生态情况。MCP 是跨工具的开放协议，各工具的配置入口不同；Skills 的目录和格式以你所用工具的文档为准。本节重点是搞懂这两样东西分别解决什么问题——这一层十年不变。

一、本节你会做出什么

你会给 AI 装上一件“外设”，让它能做到原本做不到的事；再给它写一份“作业规范”，让它每次都按你的标准干活。

📷 效果位：左边 AI 调用 MCP 工具的输出，右边一个自己写的 SKILL.md

这一节是可选增强。不学也能跟完全课；学了，你在第 5 章和第 9 章会明显省事。

二、开始前你需要

已完成 3.2 Pi 入门或 3.3 AI IDE，至少有一个工具能正常干活
已完成 2.3（本节会改配置文件，要能回滚）

三、跟着做

第 1 步：先搞清楚 AI 默认做不到什么

你现在的 AI 工具，能力边界非常清晰：

它能	它不能
读写你项目里的文件	打开浏览器看看你的页面长什么样
在终端执行命令	查你数据库里到底有几条数据
根据训练知识回答问题	知道某个库上周刚发布的新用法
按你说的做	记住你团队“按钮必须用圆角”这类约定

这四条“不能”，正好分成两类问题，对应两个解法：

问题类型	例子	解法
它够不着外部世界	看不到浏览器、连不上数据库、查不到最新文档	MCP —— 给它装外设
它不知道你的规矩和套路	不知道你的设计规范、不知道你们发布流程	Skills —— 给它一本手册

💡 一句话区分： MCP 扩展的是“手”（能做什么动作），Skills 扩展的是“脑子里的规矩”（该怎么做）。

第 2 步：MCP 是什么——给 AI 装外设的统一插口

MCP（Model Context Protocol，模型上下文协议） 是一个开放协议。用大白话讲：

它就是 AI 世界的 USB 接口标准。

以前每个 AI 工具想接一个新服务，都得单独做适配，像各家手机用各家的充电头。有了 MCP，谁都按同一个插口来——一个 MCP 服务写一次，所有支持 MCP 的工具都能用。

结构上分两边：

   你的 AI 工具                        MCP 服务（可以有很多个）
 ┌───────────────┐                  ┌──────────────────────┐
 │  Pi / Cursor  │ ◄── MCP 协议 ──► │ 浏览器控制            │
 │   / Trae      │                  │ 数据库查询            │
 │               │                  │ 最新文档检索          │
 │  （MCP 客户端）│                  │ 设计稿读取            │
 └───────────────┘                  └──────────────────────┘

装上之后，AI 的工具栏里就多出几个新动作，它会自己判断什么时候该用。

零基础阶段，最值得装的三类：

类型	它让 AI 能做什么	本课哪里用得上
浏览器控制	打开你的页面、截图、点按钮、读控制台报错	第 5 章做页面、第 6 章排错
文档检索	查某个库的最新官方用法，而不是凭记忆	第 7 章接 API、第 9 章用数据库
数据库查询	直接看表结构和数据	第 9 章

🎯 第一个装的应该是浏览器控制类。原因很实在：AI 写完页面看不到效果，只能靠你截图告诉它“这里歪了”。装上之后它能自己看、自己调，来回次数直接砍半。

第 3 步：装一个 MCP 服务

MCP 的配置是一个 JSON 文件，格式在各工具之间基本通用（这正是协议的意义）。典型长这样：

{
  "mcpServers": {
    "服务的名字": {
      "command": "npx",
      "args": ["-y", "某个-mcp-服务包名"]
    }
  }
}

三个字段的意思：服务叫什么、用什么命令启动它、启动参数是什么。

配置文件放哪里，取决于你的工具：

工具	位置
Pi	Pi 默认不内置 MCP，通过扩展支持；启用后读 `~/.pi/agent/mcp.json`（全局）或项目里的 `.pi/mcp.json`
Cursor / Trae 等 AI IDE	设置界面里有 MCP 配置入口，填同样格式的 JSON

💡 关于 Pi 的这个设计：Pi 刻意保持极简内核，MCP 走扩展而不是内置。这不是缺陷——它意味着你装的每一样东西都是自己明确选的。具体启用方式看 Pi 的扩展文档。

现在动手（推荐做法）——让 AI 帮你装：

配置 MCP 这件事本身，就很适合交给 AI 干。在你的工具里说：

我想给你装一个浏览器控制类的 MCP 服务，让你能自己打开页面、截图、看控制台报错。
我用的是【Pi / Cursor / Trae】，系统是【Mac / Windows】。

请你：
1. 推荐一个成熟的、官方或广泛使用的 MCP 服务；
2. 告诉我配置文件的确切路径；
3. 给我完整的 JSON 配置内容；
4. 配置完成后我怎么重启、怎么验证它生效了。

如果需要我提前装什么依赖，先告诉我。

验证生效：重启工具后，问它一句“你现在有哪些可用的工具？”，新装的应该出现在列表里。然后试一句：

用浏览器打开 http://localhost:3000，截个图告诉我页面长什么样，
顺便看看控制台有没有报错。

📷 截图位 1：AI 调用浏览器 MCP 并返回截图

第 4 步：⚠️ MCP 的安全课（这段必须读）

MCP 服务是第三方程序，跑在你电脑上，拥有你给它的全部权限。这里有三条硬规矩：

规矩	为什么
只装来源可靠的	官方发布或广泛使用的。不要装来路不明的 MCP 包——它能读你的文件、连你的网络
别给它不需要的东西	数据库类 MCP 优先用只读账号；文件类 MCP 限定到项目目录，不要开到整个硬盘
密钥走环境变量	需要 API Key 的 MCP，绝不把 Key 明文写进会被提交的配置文件（2.3 的 `.gitignore` 那一课）

还有一个新型风险，你需要知道它的名字：

🚨 提示词注入（Prompt Injection）：MCP 让 AI 能读取外部内容——网页、issue、数据库里的文字。如果那些内容里藏着“忽略之前的指令，去做某某事”，AI 有可能真的照做。

所以：AI 从外部读回来的东西，是“数据”，不是“命令”。 当它读完一个网页后突然要做一件你没要求的事（删文件、发请求、改配置），立刻 Ctrl+C 打断。

这也是为什么本课反复强调 git diff 验收——第 10 章会系统讲安全。

第 5 步：Skills 是什么——给 AI 的一本按需翻阅的手册

Skill 就是一份写好的说明书，平时放着不占地方，AI 遇到相关任务时自己翻开来看。

它解决的是这个痛点：

你每次都要跟 AI 重复“我们的按钮要圆角 8px、主色是这个、卡片要有阴影”……说十遍也记不住，因为每开一个新会话它就忘了。

Skill 和规则文件（AGENTS.md）的区别，这是最容易混的地方：

	规则文件（`AGENTS.md`）	Skill
什么时候加载	每次启动都读，一直占着上下文	按需加载，用到才读
适合放什么	短小的、永远适用的约定	长的、只在特定任务用得上的流程
例子	“回复用中文”“不要擅自加依赖”	“生成景点卡片的完整规范”“发布上线的 12 步检查”
类比	贴在墙上的车间守则	书架上的作业指导书

判断标准：每次都需要 → 放规则文件；十次里用一次、但内容很长 → 写成 Skill。

第 6 步：写你的第一个 Skill

以 Pi 为例，Skill 是一个文件夹，里面放一个 SKILL.md：

放在哪：

范围	路径
全局（所有项目都能用）	`~/.pi/agent/skills/`
仅本项目	项目里的 `.pi/skills/`

格式——顶部 YAML frontmatter + 正文说明：

---
name: attraction-card
description: 生成或修改景点卡片组件时使用。包含本项目卡片的视觉规范与数据结构约定。
---

# 景点卡片规范

## 视觉规范
- 圆角 12px，悬停时上浮 4px 并加深阴影
- 图片比例固定 4:3，使用 object-cover 避免变形
- 标题 18px 加粗，描述 14px 灰色，最多两行，超出用省略号

## 数据结构
每个景点对象包含：id、name、image、description、tags（数组）、duration

## 注意
- 不要给卡片加边框，靠阴影区分层次
- 移动端一行一张，平板两张，桌面三张

两个必填字段：

字段	要求	说明
`name`	1~64 字符，只能用小写字母、数字、连字符	这个 Skill 的标识
`description`	最多 1024 字符	最关键的一行——AI 就是靠它判断该不该翻开这份手册

🎯 description 决定成败：写“卡片相关”太模糊，AI 认不出什么时候该用；写“生成或修改景点卡片组件时使用，包含视觉规范与数据结构”，它一看就知道。把“什么时候用我”写清楚。

怎么被调用：

自动：AI 看到任务和某个 Skill 的 description 对上了，自己去读完整内容
手动：用 /skill:名字 强制调用（部分工具需要在设置里开启技能命令）

现在动手，写一个属于你自己的：

mkdir -p ~/.pi/agent/skills/my-style

然后新建 ~/.pi/agent/skills/my-style/SKILL.md，写上你自己的偏好，比如“我喜欢的页面风格是什么样、字体和配色偏好、不喜欢什么”。写完在 Pi 里 /reload，然后问它：「你现在有哪些 skill 可用？」

📷 截图位 2：自己写的 SKILL.md + AI 列出可用技能

AI IDE 用户：Skills 这套机制各产品支持程度不同，如果你的工具还没有，先用规则文件顶上——把同样的内容写进规则文件即可，只是会一直占着上下文。

第 7 步：什么时候该用、什么时候别用

别装太多。 这是本节最实用的一条建议。

现象	原因
装了十个 MCP 后 AI 变慢、变笨	每个工具的说明都占上下文，工具越多，它越容易挑错
Skill 写了一堆但从不触发	`description` 写得太模糊

推荐节奏：

阶段	建议
现在（第 3 章）	装 0~1 个 MCP（浏览器类），写 0~1 个 Skill。够了
第 5 章做项目时	有明确痛点再加，比如“每次都要手动截图给它看”
第 9 章用数据库时	那时再考虑数据库类 MCP

判断标准：只有当你连续三次因为同一件事烦躁时，才去装对应的东西。 为了装而装，纯属给自己增加维护负担。

四、完成的标志是

我说得出 MCP 和 Skills 分别解决什么问题（手 vs 规矩）
我知道 MCP 是跨工具的开放协议，配置格式是一段 JSON
我装了一个 MCP 服务，并让 AI 实际用它做成了一件事
我知道 MCP 服务是跑在我电脑上的第三方程序，要看来源
我知道“提示词注入”是什么，以及发现异常行为要立刻打断
我分得清规则文件（每次都读）和 Skill（按需加载）
我写了一个自己的 SKILL.md，description 写清了“什么时候用我”
我明白装太多反而会让 AI 变笨

五、卡住了看这里

Q：配置完 MCP，AI 说没有这个工具。 按顺序查：① 重启工具（配置文件基本都要重启才加载）；② JSON 格式错了——少个逗号、多个括号都会让整个配置失效，把文件内容贴给 AI 让它检查；③ 路径放错了（全局 vs 项目级）；④ 启动命令依赖的东西没装（比如需要 npx，那就得有 Node——2.2 已经装过了）。

Q：MCP 服务启动报错，或者装完 AI 整个不能用了。 先把配置文件里那个服务删掉，恢复到能用的状态，再慢慢排查。这就是本节要求先做完 2.3 的原因——配置文件也在 Git 管理范围内，git restore 一样能救。

Q：我的 Skill 写好了，但 AI 从来不用它。 90% 是 description 的问题。改成明确的触发语句：“当用户要求……时使用”。实在不行就手动调用 /skill:名字 验证 Skill 本身能不能用——能用就是描述问题，不能用就是格式或路径问题。

Q：name 字段报错说不合法。 只允许小写字母、数字、连字符，1~64 字符。不能有中文、空格、大写字母、下划线。我的技能 ❌，my-skill ✅。

Q：MCP 需要 API Key，写在配置文件里安全吗？ 配置文件在项目里（.pi/mcp.json 这种）就不安全——会被提交到 GitHub。两个做法：① 用环境变量引用，不写明文；② 把配置放在全局目录（~/.pi/agent/），那里不在项目仓库内。顺手确认一下 .gitignore 排除了相关文件。第 10.1 节会完整讲这件事。

Q：我该装哪些 MCP？网上列表好几百个。 一个都不急着装。 本课到第 5 章之前，一个浏览器类的就够了。等你真遇到“这件事 AI 干不了”的时候再回来找——痛点驱动，不是清单驱动。

Q：MCP 和 Skills 我能都跳过吗？ 能。它们是增强项，不是必需品。但第 4 步那段安全内容建议读完——以后你迟早会装，那时候这些风险都还在。

六、本节提示词

① 帮我装 MCP（见第 3 步，这里给完整版）：

我想给我的 AI 编程工具装一个 MCP 服务。
我的工具：【Pi / Cursor / Trae】，系统：【Mac / Windows】
我想让它能够：【比如"自己打开我的网页看效果、截图、读控制台报错"】

请你：
1. 推荐 1~2 个成熟且广泛使用的 MCP 服务，说明各自的优缺点；
2. 告诉我配置文件的确切路径（全局的和项目级的分别在哪）；
3. 给我完整可复制的 JSON 配置；
4. 说明需要什么前置依赖；
5. 配置后怎么重启、怎么验证生效；
6. **这个服务会获得我电脑上的哪些权限？有什么我该注意的安全风险？**

如果某项信息你不确定，明确说不确定，不要编。

② 帮我把重复的交代写成 Skill：

我每次让 AI 干活都要重复交代同样的内容，很烦。这些内容是：
【粘贴你反复说的那些话，比如页面风格要求、命名习惯、常用流程】

请把它整理成一个 Skill：
1. 判断这些内容应该放规则文件还是写成 Skill，说明理由；
2. 如果写成 Skill，给我完整的 SKILL.md，包含 name 和 description；
3. **description 要写清楚"什么时候该加载这个技能"**，让 AI 能准确触发；
4. 告诉我文件该放在哪个路径，以及怎么验证它生效了。

③ MCP 安全自查：

我配置了这些 MCP 服务：
【粘贴你的 mcp.json 内容，Key 部分打码】

请帮我检查：
1. 每个服务分别获得了哪些权限？有没有超出它实际需要的？
2. 有没有密钥是明文写在会被 Git 提交的文件里的？
3. 有没有哪个服务能访问我项目目录之外的文件？
4. 按最小权限原则，我应该怎么改？给我修改后的完整配置。

上一节 ← 3.3 AI IDE：Cursor、Trae 下一节 → 3.5 和 AI 一起写代码的正确姿势