Skills 入门：封装你的第一个 AI 能力

周一早上：
你：「Claude，帮我审查这段代码，注意安全、性能、规范...」
Claude：「好的，我来检查...」

周二下午：
你：「Claude，帮我审查这段代码，注意安全、性能、规范...」
Claude：「好的，我来检查...」

周三晚上：
你：「Claude，帮我审查这段代码，注意安全、性能、规范...」
Claude：「好的，我来检查...」

你心里：我为什么要重复说三遍？！

你：「审查一下这个函数。」
Claude：「检查完毕，没有问题。」
你：「等等！你怎么没检查 SQL 注入？上次明明说了要检查的！」

# 个人 Skill 目录（所有项目可用）
mkdir -p ~/.claude/skills/explain-code

---
name: explain-code
description: 用可视化图表和类比来解释代码。当用户问"这段代码怎么工作"或需要讲解代码时使用。
---

# 代码解释器

解释代码时，始终包含以下内容：

1. **类比开头**：把代码比作日常生活中的事物
2. **画个图**：用 ASCII 图展示流程、结构或关系
3. **逐步走读**：解释每一步发生了什么
4. **提示陷阱**：常见的错误或误解是什么

保持解释的对话感。对于复杂概念，使用多个类比。

> 这段代码是怎么工作的？

> /explain-code src/auth/login.ts

explain-code/
├── SKILL.md           # 主文件（必需）
├── examples.md        # 示例（可选）
├── reference.md       # 参考文档（可选）
└── scripts/           # 脚本（可选）
    └── helper.py

---
# YAML 前置元数据（在 —— 之间）
name: my-skill
description: 这个 Skill 做什么
---

# Markdown 内容
这里是给 Claude 的具体指令...

---
name: my-skill                    # Skill 名称，用于 /my-skill 调用
description: 这个 Skill 的作用    # Claude 用它判断何时自动加载
argument-hint: [文件名]           # 自动完成时的参数提示
disable-model-invocation: true    # 禁止 Claude 自动调用（只能手动触发）
user-invocable: false             # 从 / 菜单隐藏
allowed-tools: Read, Grep         # 限制可用的工具
context: fork                     # 在子代理中运行
agent: Explore                    # 指定子代理类型
---

# ✅ 好的命名
name: code-review
name: gen-commit-msg
name: api-docs

# ❌ 不好的命名
name: CodeReview     # 有大写
name: code_review    # 有下划线

# ❌ 太笼统
description: 帮助写代码

# ✅ 具体明确
description: 审查代码的安全性、性能和规范性。当用户请求代码审查、Code Review 或检查代码质量时使用。

# 部署 Skill - 不希望 Claude 自动部署！
---
name: deploy
description: 部署应用到生产环境
disable-model-invocation: true
---

部署 $ARGUMENTS 到生产环境：
1. 运行测试
2. 构建应用
3. 推送到部署目标

---
name: safe-reader
description: 安全地读取文件，不做任何修改
allowed-tools: Read, Grep, Glob
---

只使用读取工具来分析文件...

---
name: api-conventions
description: 本项目的 API 设计规范
---

编写 API 端点时：
- 使用 RESTful 命名
- 返回统一的错误格式
- 包含请求验证
- 添加 OpenAPI 注释

---
name: deploy
description: 部署应用到生产环境
disable-model-invocation: true
---

部署步骤：
1. 运行 `npm test` 确保测试通过
2. 运行 `npm run build` 构建
3. 检查构建产物
4. 执行部署命令
5. 验证部署结果

---
name: fix-issue
description: 修复 GitHub Issue
disable-model-invocation: true
---

修复 GitHub Issue $ARGUMENTS：

1. 使用 `gh issue view` 读取 Issue 描述
2. 理解需求
3. 实现修复
4. 编写测试
5. 创建 commit

> /fix-issue 123

code-review/
├── SKILL.md           # 主文件（概览）
├── security.md        # 安全检查清单
├── performance.md     # 性能检查清单
└── style.md           # 代码风格指南

---
name: code-review
description: 全面的代码审查
---

# 代码审查

## 检查清单

### 安全性
详见 [security.md](security.md)

### 性能
详见 [performance.md](performance.md)

### 代码风格
详见 [style.md](style.md)

monorepo/
├── .claude/skills/           # 根目录 Skill
│   └── review/
├── packages/
│   └── frontend/
│       └── .claude/skills/   # 前端包专属 Skill
│           └── component/

---
name: code-review
description: 审查代码的安全性、性能和规范性。当请求代码审查或 Code Review 时使用。
allowed-tools: Read, Grep, Glob
---

# 代码审查清单

## 安全性检查
- [ ] SQL 注入：参数化查询？
- [ ] XSS：用户输入转义？
- [ ] 硬编码密钥：没有敏感信息？
- [ ] 权限检查：访问控制到位？

## 性能检查
- [ ] N+1 查询：循环中没有数据库调用？
- [ ] 缓存：热点数据有缓存？
- [ ] 索引：查询用了索引？
- [ ] 内存：没有内存泄漏？

## 代码规范
- [ ] 命名：清晰有意义？
- [ ] 复杂度：函数不超过 50 行？
- [ ] 注释：复杂逻辑有说明？
- [ ] 测试：有对应的测试？

## 输出格式

### 发现的问题
| 类型 | 文件 | 行号 | 描述 | 严重程度 |
|------|------|------|------|----------|
| 安全 | xxx | 10 | xxx | 高 |

### 建议修改
[具体修改建议]

---
name: commit
description: 生成符合规范的 Git commit message
disable-model-invocation: true
---

# Commit Message 生成器

根据代码变更生成 commit message，格式如下：

feat(auth): 添加记住登录功能

- 新增 rememberMe 参数到 login API
- 更新 token 有效期逻辑
- 添加相关单元测试

Closes #123

### 6.3 API 文档生成器

```markdown
---
name: api-docs
description: 为 API 端点生成文档。当需要生成或更新 API 文档时使用。
argument-hint: [文件路径]
---

# API 文档生成器

为指定的 API 文件生成 Markdown 文档。

## 文档模板

```markdown
## 端点名称

**URL**: `METHOD /path/to/endpoint`

### 描述
[API 功能描述]

### 请求参数

| 参数名 | 类型 | 必需 | 描述 |
|--------|------|------|------|
| xxx | string | 是 | xxx |

### 请求示例

```json
{
  "key": "value"
}

{
  "code": 200,
  "data": {}
}

## 生成步骤

1. 读取 $ARGUMENTS 指定的文件
2. 解析 API 端点定义
3. 提取参数和返回值
4. 按模板生成文档
5. 输出到 docs/api/ 目录

---
name: pr-summary
description: 总结 PR 变更
allowed-tools: Bash(gh:*)
---

## Pull Request 摘要

- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## 任务
基于以上信息，总结这个 PR 的主要变更...

---
name: deep-research
description: 深入研究一个主题
context: fork
agent: Explore
---

深入研究 $ARGUMENTS：

1. 使用 Glob 和 Grep 找到相关文件
2. 阅读并分析代码
3. 带有具体文件引用的总结发现

---
name: session-logger
description: 记录会话活动
---

将以下内容记录到 logs/${CLAUDE_SESSION_ID}.log：

$ARGUMENTS

disable-model-invocation: true

user-invocable: false

# 默认就是两者都可以，不需要额外配置

# ❌ 太笼统
description: 帮助写代码

# ✅ 具体明确
description: 审查代码的安全性、性能和代码规范。当用户请求 Code Review 或代码检查时使用。

export SLASH_COMMAND_TOOL_CHAR_BUDGET=20000

.claude/skills/
├── my-skill/
│   ├── SKILL.md           # 必需
│   ├── reference.md       # 可选
│   ├── examples.md        # 可选
│   └── scripts/           # 可选
│       └── helper.py

# 1. 创建目录
mkdir -p ~/.claude/skills/complexity-check

# 2. 创建 SKILL.md（复制以下内容）

---
name: complexity-check
description: 分析代码的复杂度，包括圈复杂度、嵌套深度、函数长度。当用户问代码复杂度或代码质量时使用。
---

# 代码复杂度分析

分析代码时，检查以下指标：

## 圈复杂度（Cyclomatic Complexity）
- 计算分支数量（if/else/switch/for/while）
- 复杂度 > 10：需要拆分
- 复杂度 > 20：必须重构

## 嵌套深度
- 最大嵌套层级
- 深度 > 4：需要提取函数

## 函数长度
- 行数统计
- 超过 50 行：考虑拆分

## 输出格式
| 指标 | 值 | 评估 |
|------|-----|------|
| 圈复杂度 | X | 高/中/低 |
| 最大嵌套 | X | 深/中/浅 |
| 函数行数 | X | 长/中/短 |

## 建议
[具体改进建议]

> /complexity-check src/utils/parser.ts

---
name: my-skill
description: 描述这个 Skill 做什么
---

# Skill 标题

具体指令...

---
name: my-skill
description: 详细描述何时使用这个 Skill
argument-hint: [参数提示]
disable-model-invocation: false
user-invocable: true
allowed-tools: Read, Grep, Glob
---

# Skill 标题

## 概述
这个 Skill 的用途...

## 步骤
1. 第一步
2. 第二步
3. 第三步

## 输出格式
期望的输出格式...

## 参考
- [reference.md](reference.md) 详细参考
- [examples.md](examples.md) 使用示例