AI Skills 技能系统与扩展实践

AI Skills 技能系统与扩展实践

1. Skill 的核心定义

Skill 是封装特定能力的可复用指令集。它不是一次性 Prompt，而是给 AI 写的 SOP。每次遇到同类任务时，AI 都可以按同一套流程、规范和参考资料执行。

对比：

维度	单次 Prompt	Skill
使用方式	每次临时写	可复用
输出稳定性	依赖当次表达	按固定流程执行
维护方式	用完即弃	可版本管理
团队共享	不方便	可以放入项目仓库
本质类比	口头交代	标准操作手册

Skill 的意义是把"个人经验"变成"项目资产"。例如代码审查、Git 提交、API 生成、组件生成、安全审计，这些都是重复出现且有固定标准的任务，非常适合 Skill 化。

---

2. 一个完整 Skill 的目录结构

Skill 不一定只是一个 Markdown 文件，完整结构可以是：

skill-xxx/
├── SKILL.md
├── scripts/
├── resources/
├── references/
└── requirements.txt

各部分作用：

组成	作用
SKILL.md	核心说明书，写触发条件、步骤、输出标准
scripts/	辅助脚本，适合验证、批处理、格式转换
resources/	模板、示例、配置等生成材料
references/	规范、标准、文档等参考资料
requirements.txt	声明脚本依赖

SKILL.md 可以包含 Frontmatter：

---
name: react-component-generator
version: 1.0
description: 根据需求生成符合项目规范的 React 组件文件集
trigger: ["创建组件", "新建React组件", "生成组件"]
tools: ["typescript", "react"]
---

Frontmatter 的价值在于让 Agent 先读取元数据，只有任务匹配时再加载完整指令。这就是文档提到的"渐进式披露"：不把所有细节一次性塞进上下文，而是需要时再读。

---

3. Skill 结构如何选择

不是所有 Skill 都需要全套目录。文档给出的选择原则是"够用就好"。

场景	推荐结构
Git 提交规范、命名规范	只需要 SKILL.md
组件生成、页面生成	SKILL.md + resources/template
数据处理、批量转换	SKILL.md + scripts + resources/config
安全审计、代码审查	SKILL.md + references + resources/examples
完整工程流程	全套目录

不要为了"看起来高级"而过度设计。Skill 的好坏不在目录复杂，而在任务标准是否清楚、触发条件是否明确、输出格式是否稳定。

---

4. 官方与社区 Skill 资源

文档推荐优先从官方和高质量社区资源开始：

Anthropic 官方 Skill 库

覆盖文档处理、创意设计、前端设计、MCP 构建、Web 测试、skill-creator 等。

安装示例：

npx skills add anthropics/skills -g
npx skills add anthropics/skills@frontend-design -g
npx skills add anthropics/skills@skill-creator -g

Vercel Skill 库

面向 React、Next.js、AI SDK、部署、UI、浏览器自动化等生态。Next.js 项目特别适合参考。

npx skills add vercel-labs/skills -g
npx skills add vercel-labs/skills@find-skills -g -y

Vercel Skills CLI 可以理解为 Skill 世界的 npm：

npx skills find "react testing"
npx skills add <owner/repo>
npx skills add <owner/repo>@<name>
npx skills add <owner/repo> -g
npx skills list
npx skills init

社区 Skill 很多，但质量参差不齐，不能盲目安装。

---

5. 第三方 Skill 的安全评估

Skill 本质上是给 AI 的操作指令，有些还包含脚本。如果来历不明，可能引导 AI 执行危险命令或泄露敏感信息。

安装前至少检查：

维度	检查点
安全性	是否有 rm -rf、上传数据、读取密钥等危险行为
维护状态	是否长期无人维护
文档质量	SKILL.md 是否清楚，有无示例
兼容性	是否适配当前 AI 工具
来源可信度	官方、知名组织、高 Star 优先

安全顺序建议：

官方库 > 知名组织高 Star 仓库 > 个人仓库

安装前要读 SKILL.md；如果有 scripts/，也要检查脚本代码。不要把未知 Skill 直接用于正式项目。

---

6. 四类典型 Skill 实战

文档通过四个例子说明不同目录组件的用法。

6.1 React 组件生成 Skill

适合完整 Skill 包：

SKILL.md + scripts/ + resources/template/

它的任务是根据组件名、功能描述、Props、状态需求，生成标准组件目录、类型文件和测试文件。scripts/validate.js 可以用来检查生成的目录结构是否完整，resources/template/ 提供组件代码模板。

价值：保证组件结构、命名和测试习惯稳定，不靠每次临时描述。

---

6.2 API 端点生成 Skill

适合中等结构：

SKILL.md + resources/config/

它可以根据数据模型生成标准 CRUD API，例如：

GET /api/{modelName}s
POST /api/{modelName}s
GET /api/{modelName}s/[id]
PUT /api/{modelName}s/[id]
DELETE /api/{modelName}s/[id]

统一响应格式放在 resources/config/response-format.json 中。这样以后修改 API 返回结构时，只改配置文件，不必改整份 Skill 指令。

---

6.3 Git 提交规范化 Skill

这是最简 Skill，只需要 SKILL.md。流程是：

1. 读取 git diff --staged。
2. 判断变更类型，如 feat、fix、refactor、style、docs、test、chore。
3. 生成 Conventional Commits 格式。
4. 展示给用户确认后执行提交。

格式示例：

feat(auth): add login API
fix(Header): 修复移动端导航溢出
style(BookmarkCard): 优化书签卡片响应式布局

这种 Skill 很适合初学者练手，因为它结构简单、反馈直接、可马上使用。

---

6.4 安全审计 Skill

适合使用 references/：

SKILL.md + references/ + resources/examples/

它会读取 OWASP Top 10、安全编码规范等参考文档，再按示例格式输出审计报告。审计报告应包含：

• 文件路径。
• 行号。
• 问题描述。
• 严重等级。
• 修复建议。
• 安全评分。

references/ 的价值在于让 AI 不只依赖通用经验，而是按照你提供的标准审查。团队安全规范变了，只需要更新参考文档。

---

7. Skill 与 Claude Code / Cursor 的集成

在 Claude Code 中，最推荐的方式是在 CLAUDE.md 中注册项目 Skills：

## 项目 Skills
- `.claude/skills/react-component/` - React 组件生成规范
- `.claude/skills/api-endpoint/` - API 端点生成规范
- `.claude/skills/git-commit/` - Git 提交规范
- `.claude/skills/security-audit/` - 代码安全审计

执行相关任务时，请先阅读对应 Skill 目录下的 SKILL.md 并严格遵循。

也可以通过自定义 Slash Commands，把常用 Skill 变成 /new-component、/security-check 之类命令。

在 Cursor 中，可以把 Skill 的核心规则迁移到 .cursor/rules/*.mdc，让编辑器 Agent 也遵守同样规范。

---

8. Skill 的迭代与版本管理

Skill 不是一次写完就永远正确。每次使用后都要根据结果优化：

• 哪些地方 AI 做得好？保留。
• 哪些地方做得差？补充更明确的步骤。
• 哪些边界情况漏了？写进错误处理。
• 输出格式不稳定？增加示例文件。
• 团队规范变了？更新 references 或 resources。

用 Git 管理 Skill：

git add .claude/skills/react-component/
git commit -m "feat(skills): 新增 React 组件生成 Skill v1.0"

git add .claude/skills/react-component/SKILL.md
git commit -m "chore(skills): 升级 React 组件 Skill 至 v1.1"

把 Skill 放进项目仓库后，团队成员 pull 代码即可共享同一套 AI 工作流。

---

9. Superpowers 与 MCP

Superpowers 是一类社区增强插件 / Skills 集合，本质是把成熟工作流封装成可复用方法论，例如头脑风暴、计划编写、执行计划、TDD、系统化调试、代码审查、完成前验证等。

它不是初学者必装项。建议先熟悉 Claude Code 基础操作，再考虑安装。日常开发和团队项目中，它可以提高流程稳定性。

安装示例：

cd /your/project
npx superpowers
npx superpowers-zh

MCP（Model Context Protocol） 是连接外部服务和数据源的协议。Skill 规定"怎么做"，MCP 扩展"能做什么"。例如：

• GitHub MCP：读 PR、Issue、CI 日志。
• Database MCP：查询数据库。
• Browser MCP：浏览器自动化测试。
• Jira / Linear MCP：读取任务卡。
• Sentry / Datadog MCP：查看错误告警。

初学者优先掌握 Skill；MCP 属于进阶扩展。

---

10. 本笔记复盘问题

1. Skill 和单次 Prompt 的区别是什么？
2. 什么情况下只需要 SKILL.md，什么情况下需要 scripts/ 或 references/？
3. 为什么安装第三方 Skill 前必须检查脚本？
4. 如何把自定义 Skill 注册到 Claude Code？
5. Skill 与 MCP 分别解决什么问题？

---

总复习：第 0-4 部分的学习主线

第 0-4 部分可以按一条主线理解：

先搭环境
→ 建立 AI 编程认知
→ 选择工具和模型
→ 掌握 Claude Code 工作流
→ 用 Skills 把经验沉淀为可复用能力

其中最重要的不是某个命令，而是三组能力：

1. 安全控制能力 ：Git 存档、权限配置、Plan Mode、.gitignore、.claudeignore。
2. 上下文管理能力 ：CLAUDE.md、Auto Memory、参考文档、@文件、/compact、/clear。
3. 流程沉淀能力：PRD/SPEC、Explore→Plan→Implement→Commit、Skills、代码审查、安全审计。

如果能做到以下几点，就已经具备进入第五部分实战项目的基础：

• 能打开终端并创建项目目录。
• 能安装并启动 Claude Code。
• 知道如何选择模型和配置 API。
• 会写最小可用的 CLAUDE.md。
• 会用 /plan、/review、/compact、/clear、/cost。
• 每次大改前会 Git commit。
• 能创建一个简单的 Git commit Skill 或代码审查 Skill。