ClaudeSkillsAgent实战

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

AIHO 编辑部 · 2026-06-21

TL;DR

Skills 把 Agent 能力从「写代码注册 tool」降维到「写 Markdown 描述步骤」。我们写了 5 个生产级 Skill，总结出什么样的 SKILL.md 才能让 Claude 真正按你的预期执行。

我们写了哪 5 个 Skill

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

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: 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 自作主张

## 附带脚本和模板

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`

Skills vs .cursorrules vs MCP

维度	Skills	.cursorrules	MCP
本质	能力描述（按需加载）	全局 prompt（每次带）	工具接入协议
格式	Markdown + 脚本	纯文本	JSON + 代码
Context 占用	低（按需加载）	高（每次对话带）	低
适合	固化团队流程	项目规范	接外部 API
支持	Claude 系列	Cursor / Windsurf	Claude / Cursor

三者互补：.cursorrules 定项目规范，Skills 定操作流程，MCP 接外部工具。

效果数据

部署 Skill 上线两周后：

部署操作时间：15 min → 30 sec（Claude Code 执行 Skill）
部署错误率：2 次/周 → 0（Skill 里有前置检查）
新人上手：不需要看部署文档，直接说"部署"就行

结论

Skills 的核心价值不是「教 AI 新知识」，而是**「固化团队最佳实践」**。写好一个 Skill = 新人不用看文档也能按规范操作。

建议从高频、易出错的流程开始写 Skill——部署、迁移、审计这类。