Claude Skills 实战：用 SKILL.md 让 Agent 学会部署 Nuxt 项目

TL;DR

Skills 把 Agent 能力从"写代码注册 tool"降维到"写 Markdown 描述步骤"。我们写了 5 个生产级 Skill，总结出什么样的 SKILL.md 才能让 Claude 真正按预期执行——核心结论：触发条件、前置检查、具体命令、错误处理、禁止事项，五件套缺一不可。

Skills 到底是什么

一句话：Skill 是一个目录，里面放一个 Markdown 文件（SKILL.md）描述"什么时候做、怎么做、别做什么"，外加可选的脚本和模板。 Agent 在需要时按需读取这个目录，按里面的步骤执行。

它和"训练模型""写插件"都不一样——你不需要写代码、不需要懂 API，会写步骤清单就能教会 Agent 一套操作。这是它最大的意义：把"团队里只有老员工知道的操作规范"变成 Agent 可执行的文本。

我们写了哪 5 个 Skill

这 5 个的共同点：高频、易出错、步骤固定。这正是最该写成 Skill 的那类活——一次写好，长期省心。

SKILL.md 怎么写才有效

反面教材（无效）

---
name: deploy-to-vercel
description: Deploy to Vercel
---

Deploy the project to Vercel.

Claude 看到这个会反问一堆：用什么命令？要不要 --prod？环境变量怎么配？——等于没教。

正面教材（有效）

---
name: deploy-to-vercel
description: Deploy a Nuxt/Vite/Next project to Vercel
---

## When to use

User says "部署" / "deploy" / "上线" or asks to deploy to Vercel.

## Prerequisites

1. Check `vercel.json` exists. If not, create one:
   ```json
   { "framework": "nuxt", "buildCommand": "pnpm run build" }

2. Check VERCEL_TOKEN env var is set. If not, ask user to provide it.

Steps

1. Run vercel build to verify build passes locally
2. Run vercel --prod --yes to deploy
3. Wait for deployment URL in output
4. Return the deployment URL to user

Error handling

• If build fails: show error, do NOT retry automatically
• If VERCEL_TOKEN missing: ask user to set it, do NOT guess
• If vercel CLI not installed: run npm i -g vercel first

Do NOT

• Do not deploy to preview without asking
• Do not modify nuxt.config during deploy

### 五件套（缺一不可）

1. **When to use** — 明确触发条件，避免 Claude 在不该用时瞎调，也避免该用时没认出来。
2. **Prerequisites** — 前置检查，缺什么先补，别带着错误的环境往下跑。
3. **Steps** — 具体到能直接执行的命令，不要写"部署项目"这种含糊指令。
4. **Error handling** — 出错了怎么办，尤其是"不要自动重试""不要瞎猜"这类边界。
5. **Do NOT** — 禁止事项，防止 Claude 自作主张（这是踩坑最多的一项）。

实测最容易被忽略、又最关键的是 **Do NOT 和 Error handling**。没有它们，Skill 在顺利路径上能跑，一遇异常就放飞——自动重试烧钱、瞎猜配置改坏环境，都是这么来的。

## 附带脚本和模板

Skill 目录可以放脚本和模板，Claude 按需读取：

deploy-to-vercel/ SKILL.md scripts/ check-env.sh # 检查环境变量 templates/ vercel.json # 默认配置模板 nuxt.vercel.json # Nuxt 专用配置

SKILL.md 里这样引用：

```markdown
## Steps

1. Run `bash scripts/check-env.sh` to verify prerequisites
2. If `vercel.json` missing, copy from `templates/nuxt.vercel.json`
3. Run `vercel --prod --yes`

好处：把"易变的逻辑"放进脚本，SKILL.md 只描述流程。脚本改了，Skill 不用动；模板更新了，所有用到的地方一起生效。

Skills vs .cursorrules vs MCP

三者经常被混淆，其实分工清晰：

记忆口诀：.cursorrules 定规矩（always-on 的约定），Skills 定流程（按需触发的操作手册），MCP 接工具（连外部系统）。 三者互补，不是替代关系。MCP 详见 什么是 MCP。

效果数据

部署 Skill 上线两周后：

• 部署操作时间：约 15 分钟手动 → 一行指令触发
• 部署出错率：之前偶有失误 → 接近 0（Skill 里有前置检查兜底）
• 新人上手：不用读部署文档，直接说"部署"就行

更重要的是隐性收益：操作规范从"老员工脑子里"变成"团队共享的文本"，人员流动不再带走关键知识。

写 Skill 的实战建议

1. 从高频易错流程开始——部署、迁移、审计这类做得多、错不起的活，回报最高。
2. 先把"成功路径"跑通，再补异常分支——别一开始就想覆盖所有情况，先能用再加固。
3. Do NOT 列表持续补——每次 Agent 自作主张干了不该干的事，就回头加一条禁止项。
4. 逻辑放脚本，流程放 Markdown——易变部分隔离到 scripts/，SKILL.md 保持稳定。
5. 触发词写全——中英文、近义词都列上（"部署/deploy/上线"），避免该触发时没认出。

2026-09-27 更新：Skills 已经进了 MCP 协议层

本文初稿写于 2026-06，当时 Skills 还是各家客户端自己的私有约定（Claude 的 SKILL.md、Cursor 的 .cursorrules，各自格式、各自加载）。三个月后这件事变了，值得单独记一笔。

MCP 当前正式规范（2026-07-28）把「Skills over MCP」列为官方扩展之一——与 Tasks（长耗时异步操作）、MCP Apps（对话内联 UI）并列（依据 modelcontextprotocol.io 官方规范页）。三个扩展都是 opt-in，需客户端与服务端同时支持并在初始化时协商。

对本文的实践含义有三条：

1. Skills 从「客户端特性」变成「协议能力」。 过去「写一个 Skill」意味着你锁定了某个客户端；现在它可以通过 MCP Server 暴露与分发，跨客户端复用第一次有了标准路径。
2. 「按需加载」这件事被协议化了。 本文强调的「Skills 占 context 低（用到才加载）」是 Claude 侧的实现，而 MCP 的 Skills 扩展把「发现 → 取回 → 校验」做成了协议动作，不再依赖各家自己发明目录扫描。
3. 但别急着迁移。 该扩展是 opt-in 且需双方协商支持，主流客户端与支持到哪个规范日期版本的实际覆盖情况，本站未做一手核实，属待确认项。现有 SKILL.md 继续可用，本文下面「写 Skill 的实战建议」五条一条都不需要改。

另一条同期相关的协议变化：MCP 的远程传输已换成 Streamable HTTP，旧 HTTP+SSE 被弃用。Skill 里若内嵌了「调某个远程 MCP Server」的步骤，请确认该 Server 是否已迁移。

五个常见误区

误区一：「Skill 写得越详细越好」。 反了。Skill 的核心机制是按需加载，写得太长会在触发时一次性吃掉大量 context，等于把 .cursorrules 的缺点搬了回来。正确做法是流程放 Markdown、逻辑放 scripts/（见建议第 4 条），SKILL.md 只保留决策路径与禁止项。

误区二：「有了 Skill 就不用写文档了」。 本文「效果数据」里写的是新人不用读部署文档就能操作，前提是那个文档的内容已经被正确固化进 Skill。Skill 不是文档的替代品，是文档的一种可执行形态——文档不更新，Skill 一样会过时，而且过时得更隐蔽（因为它跑起来「看起来是对的」）。

误区三：「Do NOT 列表写一次就够」。 本文建议第 3 条说的是持续补——每次 Agent 自作主张干了不该干的事，就回头加一条。这是 Skills 里唯一必须长期维护的部分，也是最容易在半年后失效的部分。

误区四：「触发词列一两个就行」。 漏掉近义词的代价是「该触发时没触发」，而这类失败是静默的——用户不会知道有个 Skill 本该生效。中英文与常见说法都要列（"部署 / deploy / 上线 / 发布"）。

误区五：「Skills、.cursorrules、MCP 三选一」。 不是替代关系。记忆口诀仍然成立：.cursorrules 定规矩（always-on）、Skills 定流程（按需触发）、MCP 接工具（连外部系统）。三者同时存在是常态。

FAQ

Skill 和 MCP 现在是什么关系？ 分层不同：MCP 解决「Agent 怎么调外部工具」，Skills 解决「拿到工具之后按什么流程组合」。2026-07-28 版 MCP 规范新增 Skills over MCP 扩展后，Skills 有了通过 MCP 暴露与发现的标准路径，但原来的 SKILL.md 形态依然有效。

必须迁移到 Skills over MCP 吗？ 不需要。扩展是 opt-in，现有 Skill 继续可用。迁移的收益是跨客户端复用，代价是要依赖 Server 端与客户端双方支持。建议先观望支持覆盖度（待确认项）。

Skill 里能直接调脚本吗？ 能，而且应该。本文的建议就是把易变逻辑隔离到 scripts/，SKILL.md 保持稳定。反过来把 shell 命令全写进 Markdown，是最常见的坏味道。

一个项目该写几个 Skill？ 按高频 + 错不起筛，不按数量。本文的建议是从部署、迁移、审计这类流程起步——做得多、错了代价大，回报最高。

结论

Skills 的核心价值不是"教 AI 新知识"，而是**"固化团队最佳实践"**。写好一个 Skill = 新人不用看文档也能按规范操作。建议从高频、易出错的流程开始——部署、迁移、审计这类，投入产出比最高。

放到 2026-09 再看，这句话还多了一层含义：当 Skills 被写进 MCP 协议层之后，「固化最佳实践」第一次有了跨客户端、可分发的载体。所以现在写 Skill 的回报不只是「本项目省时间」，还在于这份流程知识将来能被搬走——前提是你已经把规则写成了文本，而不是留在某个人的操作习惯里。

延伸阅读

• Claude Skills 工具卡
• Claude Code 深度评测 — Skills 的主要运行环境
• MCP 生态实测 — Skill 接外部工具时配合 MCP 用