Skills 深度实战指南

一、理解 Skills 的本质

Skills 不是插件，是 Prompt 模板

很多人的误解：Skills 是给 Claude Code 添加新功能的插件。

真相：Skills 是预定义的 Prompt + 流程模板，它不改变 Claude 的能力，而是改变 Claude 的行为方式。

没有 Skill：Claude 用通用方式处理你的请求
有了 Skill：Claude 用专家方式处理特定类型的任务

类比

MCP = 给一个人一把新锤子（新能力）
Skill = 教一个人怎么当木匠（新行为模式）

二、内置 Skills 深度解析

/simplify — 代码简化

/simplify src/utils/helpers.ts

它做什么：

1. 读取文件
2. 分析每段代码的复杂度
3. 找出可以简化的部分
4. 重构但保持行为不变

技巧：结合约束使用

/simplify src/services/order.ts
约束：不要改变任何公开 API 签名

/review — 代码审查

/review src/api/auth.ts

技巧：指定审查重点

/review src/api/auth.ts
重点：安全性，特别是 SQL 注入和认证绕过

/test — 测试生成

/test src/services/userService.ts

技巧：指定测试风格

/test src/services/userService.ts
使用 Vitest，mock 数据库，覆盖边界条件

三、自定义 Skill 实战

Skill 文件结构

.claude/
  skills/
    api-endpoint.md      # API 接口生成器
    db-migration.md      # 数据库迁移助手
    security-scan.md     # 安全扫描
    performance.md       # 性能分析
    refactor-plan.md     # 重构规划

实战 Skill 1：API 接口生成器

---
name: api-endpoint
description: 根据数据模型生成完整的 RESTful API 接口
tools: [Read, Write, Edit, Glob, Grep]
---

# 角色

你是一个后端 API 开发专家，擅长设计清晰、安全、高性能的 RESTful 接口。

# 任务

当用户要求创建 API 接口时，按以下流程执行：

## 步骤 1：理解需求

问用户（如果不够清楚）：
- 资源名称和字段
- 需要哪些 CRUD 操作
- 认证/授权要求
- 分页/排序/筛选需求

## 步骤 2：设计接口

输出接口设计（不要直接写代码）：

POST /api/{resource} — 创建
GET /api/{resource} — 列表（支持分页）
GET /api/{resource}/:id — 详情
PUT /api/{resource}/:id — 更新
DELETE /api/{resource}/:id — 删除

## 步骤 3：实现代码

按以下结构生成文件：

1. **类型定义** `src/types/{resource}.ts`
   - 请求类型
   - 响应类型
   - 查询参数类型

2. **验证 Schema** `src/validators/{resource}.ts`
   - 用 zod 定义请求验证

3. **Service 层** `src/services/{resource}.ts`
   - 业务逻辑
   - 数据库操作
   - 错误处理

4. **Route 层** `src/app/api/{resource}/route.ts`
   - 参数验证
   - 调用 Service
   - 格式化响应

5. **测试** `src/services/{resource}.test.ts`
   - 单元测试 Service 层
   - Mock 数据库

## 代码规范

- 所有函数必须有类型注解
- 请求参数必须用 zod 验证
- 错误用 AppError 类抛出
- 返回格式：`{ data: T, error: string | null, meta?: object }`
- 列表接口默认分页，每页 20 条
- 敏感字段（password 等）永远不返回

## 依赖检查

在生成代码前，先检查：
- 项目中是否已有类似的 API，保持风格一致
- 是否有已有的工具函数可以复用
- package.json 中是否有需要的依赖

实战 Skill 2：数据库迁移助手

---
name: db-migration
description: 安全地进行数据库 schema 迁移
tools: [Read, Write, Edit, Bash, Grep]
---

# 角色

你是一个资深 DBA，擅长数据库迁移和性能优化。

# 任务

当用户需要修改数据库 schema 时，按以下流程执行：

## 步骤 1：分析当前状态

- 读取 prisma/schema.prisma（或对应的 schema 文件）
- 理解当前表结构
- 检查已有的 migration 文件

## 步骤 2：评估影响

对每个变更分析：
1. 是否需要锁表？
2. 是否会导致数据丢失？
3. 是否需要数据迁移？
4. 对现有查询的性能影响？
5. 是否可以在线执行？

## 步骤 3：生成迁移

生成以下文件：

1. **Migration SQL**
   - UP：执行变更
   - DOWN：回滚变更
   - 每个步骤有注释说明

2. **数据迁移脚本**（如果需要）
   - 处理已有数据的转换
   - 分批处理大量数据
   - 有进度显示

3. **验证脚本**
   - 检查迁移是否成功
   - 验证数据完整性

## 安全规则

- 不允许 DROP TABLE（除非用户明确要求）
- 不允许删除有数据的列
- ALTER TABLE 添加列必须有默认值
- 大表迁移必须分批执行
- 必须提供回滚方案
- 生成执行前的备份命令

## 输出格式

```markdown
## 迁移计划

### 变更内容
[描述变更]

### 风险评估
- 🔴 高风险：[说明]
- 🟡 中风险：[说明]
- 🟢 低风险：[说明]

### 执行步骤
1. [步骤 1]
2. [步骤 2]

### 回滚方案
[怎么回滚]

### 预计时间
[预估执行时间]

### 实战 Skill 3：安全扫描器

```markdown
---
name: security-scan
description: 扫描代码中的安全漏洞
tools: [Read, Grep, Glob]
---

# 角色

你是一个安全工程师，擅长 OWASP Top 10 漏洞检测。

# 任务

扫描指定目录的代码，检查以下安全问题：

## 检查清单

### 1. 注入漏洞
- SQL 注入：检查原始 SQL 拼接
- NoSQL 注入：检查 MongoDB 查询拼接
- 命令注入：检查 exec/spawn 调用
- LDAP 注入：检查 LDAP 查询拼接

### 2. 认证问题
- 密码是否明文存储
- Session 配置是否安全
- JWT 密钥是否硬编码
- 是否有默认密码
- 登录是否有暴力破解防护

### 3. 授权问题
- API 是否有权限校验
- 是否有越权访问风险
- IDOR（不安全的直接对象引用）

### 4. 敏感数据
- API Key / Secret 是否硬编码
- 日志中是否打印敏感信息
- 错误信息是否泄露内部细节
- .env 文件是否在 .gitignore 中

### 5. 安全配置
- CORS 是否过于宽松
- CSP 是否配置
- HTTPS 是否强制
- Cookie 是否设置了 HttpOnly、Secure

### 6. 依赖安全
- 是否有已知漏洞的依赖
- 是否锁定了依赖版本

## 输出格式

```markdown
# 安全扫描报告

## 扫描范围
[目录和文件列表]

## 发现的问题

### 🔴 高危
[问题描述]
- 文件：[路径]
- 行号：[行号]
- 说明：[为什么危险]
- 修复：[怎么修]

### 🟡 中危
[同上]

### 🟢 低危
[同上]

## 建议
[整体安全建议]

### 实战 Skill 4：性能分析器

```markdown
---
name: perf-analyze
description: 分析代码性能瓶颈并给出优化建议
tools: [Read, Grep, Glob, Bash]
---

# 角色

你是一个性能工程师，擅长代码性能分析和优化。

# 任务

分析指定代码的性能问题：

## 分析维度

### 1. 时间复杂度
- 循环嵌套
- 递归调用
- 不必要的重复计算

### 2. 空间复杂度
- 大对象持有
- 闭包内存泄漏
- 缓存策略

### 3. IO 操作
- 数据库查询 N+1
- 同步 IO 阻塞
- 不必要的网络请求
- 缺少缓存

### 4. 并发
- 锁粒度过大
- 竞态条件
- 线程池配置

### 5. 算法选择
- 数据结构是否合适
- 是否有更优的算法
- 是否可以用内置优化函数

## 输出格式

```markdown
# 性能分析报告

## 热点函数
1. [函数名] — [预估耗时占比]
2. ...

## 瓶颈分析

### 瓶颈 1：[描述]
- 位置：[文件:行号]
- 当前复杂度：O(?)
- 优化后复杂度：O(?)
- 预估提升：X 倍
- 优化方案：[具体方案]
- 代码示例：[优化后的代码]

### 瓶颈 2：...

## 优化路线图
1. [优先级最高] — [预计收益]
2. [次优先级] — [预计收益]
3. ...

## Benchmark 建议
[如何测量优化效果]

---

## 四、Skill 组合使用

### 场景：新功能开发流程

```bash
# 1. 设计接口
/api-endpoint
"创建订单管理的 CRUD 接口"

# 2. 安全检查
/security-scan src/api/orders/

# 3. 性能检查
/perf-analyze src/services/order.ts

# 4. 生成测试
/test src/services/order.ts

场景：代码质量提升

# 1. 简化代码
/simplify src/utils/

# 2. 安全扫描
/security-scan src/

# 3. 性能分析
/perf-analyze src/services/

# 4. 代码审查
/review src/

场景：数据库变更

# 1. 设计变更
/db-migration
"给 orders 表添加 status 字段"

# 2. 生成 API
/api-endpoint
"添加订单状态更新接口"

# 3. 测试
/test src/services/order.ts

五、Skill 管理最佳实践

版本控制

# Skill 文件提交到 Git
git add .claude/skills/
git commit -m "feat: add custom skills"

# 团队成员 pull 后即可使用

Skill 文档化

在项目 README 中说明有哪些 Skill：

## 自定义 Skills

- `/api-endpoint` — 生成 RESTful API 接口
- `/db-migration` — 安全的数据库迁移
- `/security-scan` — 安全漏洞扫描
- `/perf-analyze` — 性能分析

使用方式：在 Claude Code 中输入 `/skill-name`

Skill 迭代

# 使用后发现 Skill 有问题
# 直接编辑 .claude/skills/xxx.md
# 下次使用自动生效

不要过度封装

# 差：封装太死
一个 Skill 试图做所有事

# 好：职责单一
/api-endpoint — 只做 API
/db-migration — 只做迁移
/security-scan — 只做扫描

六、Skill vs MCP vs Hooks 的正确选择

七、实战常见问题与处理

问题：Skill 不生效（输入 /skill-name 没反应）

症状：在 Claude Code 中输入 /api-endpoint 没有任何反应

原因：
1. Skill 文件放错位置
2. 文件名和调用名不一致
3. frontmatter 格式错误

# 排查：
# 1. 检查文件位置
# 项目级：.claude/skills/api-endpoint.md
# 用户级：~/.claude/skills/api-endpoint.md

# 2. 检查文件名
# 调用 /api-endpoint → 文件必须是 api-endpoint.md
# 大小写敏感！

# 3. 检查 frontmatter 格式
# 必须有 --- 开头和结尾
---
name: api-endpoint    # 这个 name 要和文件名一致
description: 生成 API 接口
---
# content here...

# 4. 重启 Claude Code 后再试

问题：Skill 执行结果和预期不符

症状：Skill 触发了，但 Claude 的行为不是你想要的

原因：
1. Skill 的 prompt 写得不够具体
2. 和 CLAUDE.md 中的指令冲突
3. 上下文中有干扰信息

# 解决：
# 1. 在 Skill 中用更明确的指令
# 差："生成一个 API 接口"
# 好："生成一个 RESTful API 路由文件，使用 Express.js + TypeScript，
#     包含请求验证（zod）、错误处理（AppError）、日志记录（winston）"

# 2. 检查 CLAUDE.md 是否有冲突的指令
# 如果 CLAUDE.md 说"用 Fastify"，但 Skill 说"用 Express"，会冲突

# 3. 在 Skill 中指定工具限制
---
name: api-endpoint
tools: [Read, Write, Edit]   # 只允许这些工具
---

问题：多个 Skill 之间互相干扰

症状：用了一个 Skill 后，再用另一个 Skill，行为异常

原因：两个 Skill 有矛盾的指令

# 解决：
# 1. 确保 Skill 职责单一
# /api-endpoint 只管生成 API
# /db-migration 只管数据库迁移
# 不要让一个 Skill 同时做两件事

# 2. 如果需要组合使用，分步执行
/api-endpoint
"创建用户接口"
# 等完成
/security-scan src/api/users/
# 等完成
/test src/api/users/

# 3. 不要同时触发多个 Skill

问题：Skill 在不同项目间不通用

症状：在项目 A 写的 Skill，在项目 B 中不好用

原因：Skill 中硬编码了项目特定的信息

# 解决：
# 1. Skill 只写通用流程，项目特定信息放 CLAUDE.md
# Skill（通用）："生成 API 接口，遵循项目的技术栈和规范"
# CLAUDE.md（项目特定）："用 Express.js + Prisma + PostgreSQL"

# 2. 用变量代替硬编码
# 差："生成 Express.js 路由"
# 好："生成项目使用的框架的路由（参考 CLAUDE.md 中的技术栈）"

# 3. 用户级 Skill 放 ~/.claude/skills/
# 项目级 Skill 放 .claude/skills/
# 区分清楚

问题：Skill 执行太慢

症状：触发 Skill 后等很久才有响应

原因：
1. Skill 让 Claude 读取了太多文件
2. Skill 的流程太复杂
3. 让 Claude 做了多余的事

# 解决：
# 1. 在 Skill 中限制读取范围
---
name: security-scan
tools: [Read, Grep, Glob]   # 不允许 Bash，避免执行耗时命令
---

# 2. 简化 Skill 流程
# 差：一个 Skill 做扫描 + 修复 + 测试 + 提交
# 好：一个 Skill 只做扫描，修复另起一步

# 3. 在 Skill 中明确"不要做"
# "不要自动修复，只报告问题"
# "不要运行测试，只生成代码"