一份纯 Markdown 文档，凭什么能驱动一次真实的打包部署？
引子：一个让我重新思考的现象
接手一个 Maven 多模块项目（fm-platform）时，我在 .cursor/skills/deploy-staging/ 目录里发现了两个文件：SKILL.md 和 reference.md。翻遍整个目录------没有 .sh 脚本，没有部署工具，没有一行可执行代码，只有两篇 Markdown 文档。
但 Cursor 的 Agent 确实能靠着它们把「跑测试 → 打包 JAR → 上传服务器 → 重启进程 → 健康检查」一条龙真实执行完。
这让我把 AI Agent 体系里最容易混淆的三个概念彻底想明白了：Skill、Tool、MCP------到底谁在真正干活？
一句话区分
| 概念 | 一句话 | 回答的问题 |
|---|---|---|
| Skill | 说明书 | "怎么做才对？" |
| Tool | 双手 | "能做什么动作？" |
| MCP | 插座标准 | "外部能力怎么接进来？" |
三者不冲突，是协同关系。下面逐一展开。
一、三者本质对比
| 维度 | Skill 技能 | Tool 工具 | MCP 协议 |
|---|---|---|---|
| 本质 | 指令/知识文档（SKILL.md） | 可执行函数（有输入输出 schema） | 开放接入标准（协议） |
| 是否执行代码 | 不执行，指导 Agent 干活 | 调用即真实执行 | 本身不执行，由 MCP Server 执行 |
| 形态 | .cursor/skills/、~/.workbuddy/skills/ 等目录 |
内置函数或 MCP Server 暴露的函数 | MCP Server（stdio / HTTP / SSE） |
| 触发方式 | 自动发现 + /技能名 手动调用 |
Agent 按需 function-calling | 配置连接后即插即用 |
| 例子 | deploy-staging、python 语法检查 | Terminal、ReadFile、WebSearch | GitHub MCP、腾讯文档 MCP、邮箱 MCP |
补充一个容易忽略的点：MCP 世界里其实包含三类东西------Tools（工具）、Resources（数据资源）、Prompts（提示模板）。所以 MCP 不只是"工具"，它是一整套外部能力的接入标准。
二、灵魂拷问：纯 Markdown 怎么驱动真实部署？
这是当时最困惑我的问题。拆开看，执行链路是这样：
关键认知：工具不在文件里，而在 Agent 运行时里。
- 上下文注入：Agent 发现任务匹配技能后，把 SKILL.md（以及按需读取的 reference.md）当作提示词的一部分读进模型上下文。对模型来说，这是一份权威的"任务说明书"。
- LLM 翻译 ：模型不是复制粘贴文档，而是理解 步骤后用函数调用（function calling）发起真实动作。文档里的
mvn test这行字，会变成对 Terminal 工具的一次调用，参数就是这条命令。
- 工具闭环 ：工具返回真实结果（日志、退出码、HTTP 响应），模型对照文档里的"通过标准"做判断，决定继续下一步、停止还是回滚------形成"读文档 → 执行 → 校验 → 决策"的循环。
所以：Skill 提供"知识"，Tool 提供"执行力"，LLM 是中间的"翻译官" 。一份纯 Markdown 文档足以驱动真实部署，靠的就是这三者协作。
三、SKILL.md 的本质：结构化提示词
再进一步，SKILL.md 从机制上讲就是一段提示词------但它是"结构化、可复用、带元数据"的提示词。它管的事正好是两件：
frontmatter（YAML 头部）→ 管"边界和使用条件"
| 字段 | 作用 |
|---|---|
name |
调用标识，决定 /技能名 能否被找到 |
description |
使用条件，模型靠它判断何时自动加载技能 |
paths（可选） |
作用边界，限定只对匹配的文件生效 |
disable-model-invocation（可选） |
禁止自动触发，只允许手动调用 |
正文（Markdown）→ 管"步骤和约束"
以 deploy-staging 为例，正文里最值钱的是几类约束：
- 硬性护栏："测试失败则停止，不进入构建"（fail-fast）
- 通过标准 ：每步都写了判据------
BUILD SUCCESS、JAR 时间戳为本次构建、{"status":"UP"}
- 能力边界："仓库内无自动化部署脚本，按飞书文档执行"------防止模型自作主张乱部署
- 权限约束："紧急热修需用户明确授权"
与普通提示词的区别：普通提示词一次性、跟着聊天输入走；SKILL.md 靠元数据被自动发现、按需加载、可复用、可提交 Git 团队共享。它是带"索引和自述"的提示词，所以能自动生效而不占每条对话的上下文。
四、Skill 目录结构：哪些文件必需？
只有 SKILL.md 是必需的 ------技能 = 包含 SKILL.md 的文件夹，其他都是可选加装：
为什么要拆 reference.md？ 核心动机是省上下文：
- SKILL.md 每次触发都会完整注入上下文，所以应该精简，只放高频主线（测试→构建→部署→验证）；
- reference.md 平时不注入，只有 SKILL.md 里写了"服务与 profile 细节见 reference.md"时，模型才按需去读。
这就是社区常说的渐进披露（progressive disclosure） 。判断标准一句话：主线放得下就单文件；有"低频但必要"的细节表才拆 。注意 reference.md 不是规定名字，任意文件名都行，只要 SKILL.md 里用相对路径引用。
五、最容易混淆的两个点
- Skill ≠ MCP 的 Prompts：MCP 的 prompts 是服务端写死的提示模板，随连接提供；Skill 是用户侧的、可复用的技能包。形态类似，但来源和灵活度完全不同。
- Skill 不能当 Tool 用：Skill 是给 Agent 看的文档，如果它需要"做事"，必须借助 Tool（含 MCP 接入的工具）来执行------这正是三者互补而非替代的体现。
六、实战建议
- 什么时候写 Skill：有固定流程、多步骤、需要规范约束的任务（部署、代码审查规范、项目初始化）。把"怎么做得对"沉淀成可复用资产。
- 什么时候接 MCP：需要外部系统能力或数据（GitHub、文档协作、邮箱、行情、数据库）。接上后，新工具会动态加入工具池，Agent 就"多了一双手"。
-
设计 Skill 的三原则：
- 主线精简------SKILL.md 只放高频步骤；
- 按需披露------细节表放 reference，需要时再读；
- 通过标准必须明确------这是让 Agent 能"自我校验、失败即停"的关键，也是最容易被新手忽略的。
结语
回到开头的问题：纯 Markdown 文档为什么能驱动真实部署？
因为 Skill 提供知识（怎么做得对），Tool 提供执行力（能干什么），MCP 扩展接入（外部能力怎么连），LLM 是中间的翻译官（把文档变成动作） 。下次你再看到一份只有几篇 Markdown 的 skill 目录，就不会觉得"魔法"了------它只是把该说的都说清楚了，剩下的交给工具和模型。