ClaudeSkillsAgent实战

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

AIHO 编辑部 · 2026-06-21

TL;DR

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

Skills 到底是什么

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

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

我们写了哪 5 个 Skill

Skill	场景	效果
deploy-to-vercel	部署 Nuxt 项目到 Vercel	从 15 分钟手动操作 → 一行指令
audit-deps	审计 package.json 依赖安全	每周自动跑，输出安全报告
gen-sitemap	生成 sitemap.xml	改路由后自动更新，不用手动跑脚本
db-migration	数据库 schema 迁移	生成迁移文件 + 回滚脚本
gen-api-docs	从代码生成 API 文档	提交 PR 时自动更新文档

这 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" }

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

Steps

Run vercel build to verify build passes locally
Run vercel --prod --yes to deploy
Wait for deployment URL in output
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

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

维度	Skills	.cursorrules	MCP
本质	能力描述（按需加载）	全局 prompt（每次带）	工具接入协议
格式	Markdown + 脚本	纯文本	JSON + 代码
Context 占用	低（用到才加载）	高（每次对话都带）	低
适合	固化操作流程	项目通用规范	接外部 API
典型内容	"怎么部署""怎么迁移"	"用 pnpm""中文注释"	GitHub / Slack / DB 工具

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

效果数据

部署 Skill 上线两周后：

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

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

写 Skill 的实战建议

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

结论

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