Skill 模板库

技能是「按需展开的抽屉」——平时只露一行 description，Claude 判断要用时才拉开。这一篇摆出 8 个实战技能模板，复制到 .claude/skills/<name>/SKILL.md 即可。每个含完整 SKILL.md（frontmatter + 正文）+ 支持文件结构说明。

技能原理与字段含义见 Skills 深入。字段以官方 docs.claude.com/skills 文档为准。

1. commit-messages（提交信息规范）

目录结构：

.claude/skills/commit-messages/
└── SKILL.md

SKILL.md：

---
name: commit-messages
description: 当用户要求生成、改写 git commit message，或说「帮我写提交信息」「这次改了啥」时使用。读取 staged diff，按 Conventional Commits 规范生成中文 commit。
allowed-tools: Read, Bash
argument-hint: "[可选：提交范围，如 HEAD~3]"
---

# Commit Messages 技能

## 何时触发
- 用户说「帮我写 commit」「生成提交信息」「这次改了啥」
- 用户要求改写已有 commit message
- 用户要按某个范围生成提交历史摘要

## 步骤
1. 运行 `git diff --cached` 读取暂存区改动；若暂存区为空，提示用户先 `git add`
2. 若用户给了范围参数（如 `HEAD~3`），运行 `git log <range> --oneline` 汇总
3. 按改动判断 type：
   - `feat` 新功能
   - `fix` 修复 bug
   - `refactor` 重构（行为不变）
   - `perf` 性能优化
   - `docs` 文档
   - `test` 测试
   - `chore` 构建/工具/依赖
4. 生成格式：

(): <一行简短摘要，不超过 50 字符>

<空行>

<详细说明 1>
<详细说明 2>

5. 涉及 issue 加尾注：`Closes #123`
6. 询问用户是否直接执行 `git commit -m "..."`

## 规范
- 摘要用动宾结构：「修复登录页空指针」而非「关于登录页的修复」
- scope 用模块名：`api`、`ui`、`auth`、`db`
- 详细说明每条改动占一行，以 `- ` 开头，说清「为什么改」不只说「改了什么」
- 不写「修复了一些问题」这种空话

## 禁忌
- 不要为「让历史好看」而拆分或合并提交，按实际改动生成
- 不要在没有用户确认时直接 `git commit`

说明：description 写清「何时触发」，Claude 才不会乱用。allowed-tools 限 Read + Bash（要读 diff）。argument-hint 让用户知道能传范围。

2. code-review-standards（团队审查标准）

.claude/skills/code-review-standards/
└── SKILL.md

---
name: code-review-standards
description: 当用户请求代码审查、检查 PR、查找代码异味或安全问题时使用。按团队规范逐项检查，只读不改。
allowed-tools: Read, Grep, Glob
---

# 团队代码审查标准

## 审查清单

### 必查项（不通过即阻塞）
1. **测试**：新功能有测试，测试覆盖关键路径且能通过
2. **错误处理**：async 有 try/catch 或全局过滤器，错误有用户可读的信息
3. **权限**：涉及资源的接口有鉴权 + 越权校验
4. **密钥**：无硬编码 token / 密码 / API key
5. **SQL**：用参数化查询，无字符串拼接

### 建议项（影响质量不阻塞）
6. **命名**：变量名达意，函数名是动词，类名是名词
7. **函数长度**：单函数不超过 80 行，圈复杂度不超过 10
8. **重复**：相似逻辑超过 3 处应提取
9. **注释**：复杂逻辑有「为什么」的注释，不写「做了什么」的废话注释

### 可选项（锦上添花）
10. **性能**：无明显 N+1、无全量加载、无死循环风险
11. **可读性**：嵌套不超过 3 层，用早返回压平
12. **一致性**：沿用现有风格，不引入新依赖除非必要

## 输出格式
按严重程度分档：

- 🔴 阻塞：必须修复才能合（必查项不过）
- 🟡 建议：影响质量，建议本次或下次修
- 🟢 可选：可改可不改

每条：`文件:行号 — 问题 — 建议`。

## 约束
- 只读，不改代码
- 同类问题只指出一次，附上所有出现位置
- 代码已经很好就明说「无阻塞问题」

说明：审查类技能用 allowed-tools: Read, Grep, Glob 限死只读。审查清单分三档，主代理按优先级处理。

3. pdf-processing（PDF 处理，带 scripts/）

.claude/skills/pdf-processing/
├── SKILL.md
├── SECURITY.md
├── PERFORMANCE.md
└── scripts/
    ├── extract.py
    └── compress.py

SKILL.md：

---
name: pdf-processing
description: 当用户请求处理 PDF——提取文本、压缩、合并、拆分、转图片时使用。处理前必读 SECURITY.md，大文件必读 PERFORMANCE.md。
allowed-tools: Read, Write, Bash
---

# PDF 处理技能

## 何时触发
用户说「提取 PDF 文字」「压缩 PDF」「合并 PDF」「PDF 转图片」等。

## 安全前提
**处理任何用户上传的 PDF 前，必须先阅读 SECURITY.md。**要点：
- PDF 可含恶意 JS 或外部引用，解析时禁用网络与 JS 引擎
- 用 pdfplumber / PyPDF2 等只解析内容的库，不用会执行脚本的引擎
- 大文件先采样，不要整文件加载到内存

## 性能前提
**文件超过 50MB 或页数超过 500 时，先阅读 PERFORMANCE.md。**要点：
- 分页处理，不要一次性 load 全文
- 提取文本用流式，内存占用控制在 200MB 内
- 图片导出控制 DPI，避免 OOM

## 步骤
1. 确认任务类型：提取 / 压缩 / 合并 / 拆分 / 转图
2. 读 SECURITY.md 和（若文件大）PERFORMANCE.md
3. 调用 scripts/ 下对应脚本：
   - 提取文本：`python scripts/extract.py <file>`
   - 压缩：`python scripts/compress.py <file> -o <out>`
4. 输出结果文件路径 + 摘要（页数、字符数、压缩比）

## 约束
- 不执行 PDF 内嵌的任何脚本
- 不联网下载外部资源
- 失败时给出明确原因，不要静默跳过

scripts/extract.py（示意）：

"""提取 PDF 文本，分页流式处理。"""
import sys
import pdfplumber

def extract(path: str) -> None:
    with pdfplumber.open(path) as pdf:
        for i, page in enumerate(pdf.pages):
            text = page.extract_text() or ""
            print(f"--- page {i+1} ---")
            print(text)

if __name__ == "__main__":
    extract(sys.argv[1])

说明：这是「带弹药库的复合技能」——SKILL.md 是入口，SECURITY.md / PERFORMANCE.md / scripts/ 是按需读取的支持文件。Claude 在需要时才读它们，平时只占 ~100 token。

4. data-analysis（数据分析，带参考文档）

.claude/skills/data-analysis/
├── SKILL.md
├── METRICS.md      # 指标定义
└── examples/
    └── funnel.md   # 漏斗分析示例

SKILL.md：

---
name: data-analysis
description: 当用户请求分析数据、算指标、跑统计、做数据探索时使用。分析前必读 METRICS.md 确认指标定义。
allowed-tools: Read, Write, Bash
---

# 数据分析技能

## 何时触发
用户说「分析这份数据」「算转化率」「最近一周留存怎样」「跑个统计」等。

## 第一步：对齐指标
分析前**必读 METRICS.md**，确认要算的指标在本项目的精确定义：
- 「活跃用户」是登录还是产生行为？
- 「转化」算到下单还是支付成功？
- 「留存」是次日还是 7 日？

定义不一致的结论毫无意义。

## 步骤
1. 复述业务问题，确认要回答什么
2. 读 METRICS.md 对齐指标定义
3. 数据摸底：schema、规模、缺失、异常
4. 写分析脚本到 `analysis/`，可复跑
5. 跑出结果，用业务语言讲结论
6. 标注置信度和局限性

## 输出
- `analysis/<task>.py` 分析脚本
- markdown 报告：问题 → 方法 → 结果 → 结论 → 局限

## 约束
- 不在主数据源上写，先复制 sample
- 大查询先 EXPLAIN
- 相关性不等于因果，结论带不确定性
- 涉及用户数据遵守最小化原则

METRICS.md（示意）：

# 指标定义

## 活跃用户 DAU
当日产生至少一次有效行为（非爬虫）的去重用户数。

## 转化率
下单成功用户数 / 访问商品详情页用户数。
注：取消订单不计入分子。

## 次日留存
注册次日仍产生有效行为的用户 / 注册当日新增用户。

说明：数据分析最大的坑是「各人定义不同」。METRICS.md 把定义固化，每次分析前先对齐。examples/ 放历史分析模板供参考。

5. documentation-style（文档风格指南）

.claude/skills/documentation-style/
└── SKILL.md

---
name: documentation-style
description: 当用户请求写文档、改文档、生成 README 或用户指南时使用。统一团队文档风格。
allowed-tools: Read, Write, Glob
---

# 文档风格指南

## 何时触发
用户说「写 README」「补文档」「整理这份笔记成文档」等。

## 风格规范

### 语气
- 用「你」不用「您」，平视读者
- 短句优先，一句话一个观点
- 不写营销话术：「强大的」「革命性的」「一站式」全部删掉

### 结构
- 标题不超过四级（# ## ### ####）
- 每节开头一句话点明本节讲什么
- 代码块带语言标签
- 命令前加注释说明用途

### 示例
- 配「最小可运行示例」，不要「示意片段」
- 命令示例可复制粘贴即跑
- 输出示意用注释标注，不用真实数据

### 命令文档
- 装某东西：写明前置条件（版本、平台）
- 跑某命令：写明在哪个目录、需要什么环境变量
- 失败处理：给常见报错和修法

### 链接与引用
- 引用其它文档用相对路径
- 外部链接给标题，不要裸 URL
- 引用官方文档标注「以官方为准」

## 禁忌
- 不写「本文档可能过时」这种免责，改成「最后更新于 YYYY-MM-DD」
- 不写「未来计划」凑字数
- 不编造代码里没有的功能
- 不在文档里贴密钥、内网地址

## 输出检查
写完自检：
1. 每句话能在代码里找到依据吗？
2. 代码示例能跑吗？
3. 有没有营销话术？
4. 标题层级清晰吗？

说明：documentation-style 是「软规范」——Claude 写文档时自动套用团队语气。重点是禁营销话术、禁编造功能。

6. database-query-patterns（数据库查询模式）

.claude/skills/database-query-patterns/
├── SKILL.md
└── ANTI-PATTERNS.md   # 反模式清单

SKILL.md：

---
name: database-query-patterns
description: 当用户请求写 SQL、优化查询、设计数据访问层时使用。遵循团队查询模式，避免反模式。
allowed-tools: Read, Write, Bash
---

# 数据库查询模式

## 何时触发
用户说「写个查询」「这条 SQL 慢」「加个索引」等。

## 团队模式

### 必须遵守
1. **参数化查询**：永远用占位符，禁止字符串拼接 user input
   - 好：`WHERE id = $1`
   - 坏：`WHERE id = ` + userId
2. **分页用游标**：不用 OFFSET 分页（深翻慢）
   - 游标：`WHERE created_at < $1 ORDER BY created_at DESC LIMIT 20`
3. **N+1 检查**：循环里不查库，用 JOIN 或批量 IN
4. **显式列名**：不用 `SELECT *`，列出要的列
5. **事务最小化**：事务里不放外部调用（HTTP、文件 IO）

### 索引
- WHERE / JOIN / ORDER BY 的列才建索引
- 复合索引按区分度从高到低排
- 写多读少的表少建索引

### 迁移
- schema 变更走迁移脚本，不手改
- 破坏性变更分两步：先兼容（加新列），下版再删旧列
- 大表加索引用 `CREATE INDEX CONCURRENTLY`

## 优化流程
1. 先 `EXPLAIN ANALYZE` 看执行计划
2. 看 Seq Scan（全表扫描）、Nested Loop（可能 N+1）、Sort 排序开销
3. 估算返回行数，对比实际
4. 优化前先读 ANTI-PATTERNS.md 避坑

## 输出
- 查询 SQL（带参数占位符）
- 索引建议（如有）
- 执行计划分析
- 风险提示

ANTI-PATTERNS.md（示意）：

# 查询反模式

- OR 导致索引失效 → 改 UNION ALL
- 函数包裹索引列 → `WHERE DATE(col) = ...` 不走索引，改范围
- 隐式类型转换 → 字符串列用数字查
- LIKE '%xxx' 前导通配符 → 全表扫
- 多次小查询代替一次 JOIN

说明：把反模式单独成文件，按需读取。Claude 写 SQL 前先扫一遍避坑，比堆在 SKILL.md 里更省 token。

7. api-doc-format（API 文档格式）

.claude/skills/api-doc-format/
└── SKILL.md

---
name: api-doc-format
description: 当用户请求生成 API 文档、写接口说明、整理端点清单时使用。统一 API 文档格式。
allowed-tools: Read, Write, Glob
---

# API 文档格式

## 何时触发
用户说「生成 API 文档」「写接口说明」「整理端点」等。

## 每个端点的标准格式

````markdown
### POST /api/v1/users

创建新用户。

**权限**：`admin`

**请求体**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| email | string | 是 | 邮箱，需合法 |
| name | string | 是 | 1-50 字符 |

**请求示例**
```json
{ "email": "a@b.com", "name": "张三" }

响应

201 创建成功，返回 user 对象
400 参数错误
401 未认证
409 邮箱已存在

响应示例

{ "id": 1, "email": "a@b.com", "name": "张三" }

## 规范
- 按资源分组，资源内按方法（GET / POST / PUT / DELETE）排
- 字段表三列起：类型、必填、说明
- 状态码列出所有可能，含错误码
- 示例可复制即用
- 从代码实际签名生成，不编造字段

## 禁忌
- 不写「通常返回 200」这种模糊话，列全状态码
- 不省略错误响应
- 不写「详见源码」让读者自己找
```

**说明**：api-doc-format 把端点文档格式固化。每个端点都按同一模板，读者形成预期。

## 8. meeting-notes（会议纪要模板）

```
.claude/skills/meeting-notes/
└── SKILL.md
```

```markdown
---
name: meeting-notes
description: 当用户提供会议录音转写、会议笔记，请求整理成纪要时使用。输出结构化会议纪要。
allowed-tools: Read, Write
---

# 会议纪要技能

## 何时触发
用户说「整理一下这次会议」「把这录音转写做成纪要」「总结会议要点」等。

## 输出模板

```markdown
# 会议纪要：<主题>
**时间**：YYYY-MM-DD HH:MM
**参会**：A、B、C
**缺席**：D（请假）

## 议题与讨论
### 议题 1：xxx
- 背景：一句话
- 讨论：要点（按发言人归纳观点，不按时间流水账）
- 结论：达成什么共识 / 未决

### 议题 2：xxx
...

## 决议
- [决] xxx（负责人：A，截止：MM-DD）
- [决] xxx（负责人：B，截止：MM-DD）

## 待办
- [ ] xxx — A — MM-DD
- [ ] xxx — B — MM-DD

## 遗留问题
- xxx 未定，下次讨论
```

## 处理规则
1. 通读输入，识别议题切换点
2. 每个议题归纳「讨论要点」和「结论」
3. 明确的下一步提炼成「待办」，标注负责人和截止
4. 区分「决议」（已拍板）和「待办」（待执行）
5. 未达成共识的放「遗留问题」

## 约束
- 客观记录，不夹带整理者观点
- 发言归纳按「观点」而非「谁说了什么」——除非观点归属重要
- 待办必须可执行（有动作、有负责人、有截止）
- 没明确结论的不要硬凑
```

**说明**：meeting-notes 把会议纪要格式固化。关键是「待办必须可执行」——有动作、负责人、截止，否则不算待办。

## 怎么用这些技能

### 放对位置

```bash
# 项目级（团队共享，进 git）
.claude/skills/<name>/SKILL.md

# 用户级（跨项目，个人）
~/.claude/skills/<name>/SKILL.md
```

### 自动发现

放进去即可，下次会话自动扫描。不用注册、不用声明。

### 渐进式披露

启动时只加载每个技能的 `name` + `description`（约 100 token/个）。Claude 判断需要时才读完整 SKILL.md，需要支持文件时才读 SECURITY.md / scripts/。

### 控制触发

- 自动触发：默认行为，Claude 看 description 自己判断
- 只显式调用：`disable-model-invocation: true`，必须 `/skill-name` 调

```yaml
disable-model-invocation: true
```

## 一句话总结

> **技能是按需展开的抽屉——SKILL.md 写能力，frontmatter 贴标签（description 决定何时触发），支持文件随用随取。能限工具就限（审查类只给读），重逻辑单独成文件按需读，description 写「何时触发」不写「用于什么」。**

---

模板照抄改几个字就能用。配套的 [Subagent 模板库](/resources/subagent-templates/) 看子代理怎么写，[配置文件模板](/resources/templates/) 看 settings.json 怎么挂技能。🚀