mkdir -p .claude/skills/sql-index-doctor/{scripts,templates}
cd .claude/skills/sql-index-doctor
touch SKILL.md scripts/explain_scan.py templates/report.md reference.md

.claude/skills/sql-index-doctor/
├── SKILL.md              # 必需，总入口
├── reference.md          # 可选，反模式手册（按需读取）
├── scripts/
│   └── explain_scan.py   # 可选，EXPLAIN 解析器
└── templates/
    └── report.md         # 可选，输出模板

---
name: sql-index-doctor
description: |
  MySQL/PostgreSQL 慢查询索引优化顾问。当用户做以下事情时使用本 Skill：
  (1) 粘贴一段 SQL 问「为什么慢」「怎么优化」；(2) 提供 EXPLAIN 执行计划要解读；
  (3) 排查索引缺失、回表过多、全表扫描；(4) 需要 CREATE INDEX 的可执行 DDL；
  (5) 优化 WHERE / JOIN / ORDER BY / GROUP BY 的查询性能。
  输出包含：命中反模式清单、EXPLAIN 关键字段判读、建议索引（含字段顺序与理由）、
  覆盖索引机会、可执行 DDL、回滚方案。
allowed-tools: Read, Grep, Glob, Bash(mysql:*), Bash(psql:*)
---

# SQL 索引医生

## 分析流程（严格按序执行）

1. **提取谓词**：从 WHERE / JOIN ON / ORDER BY / GROUP BY 中
   抽出所有参与过滤、连接、排序、分组的列。
2. **识别反模式**：对照 reference.md 的反模式清单逐条扫描，
   命中即记录（见下方「必须告警的反模式」）。
3. **判读执行计划**：若用户提供了 EXPLAIN，优先读取；
   否则用 Bash 跑 `mysql -e "EXPLAIN <sql>"` 获取。
   重点看 type/access_method、key、rows、Extra 四列。
4. **设计索引**：按「等值列在前、范围列在后、排序列收尾」
   的原则组合联合索引，并判断能否做成覆盖索引。
5. **输出 DDL**：给出带注释的 CREATE INDEX 语句，
   并说明每列为何在这个位置。

## 必须告警的反模式（命中即写入报告「风险」段）

- 隐式类型转换：varchar 列与数字比较（`where phone = 13800138000`）
- 左模糊：`where name like '%张'` 无法走索引
- 函数包裹列：`where date(create_time) = '2026-07-11'`
- OR 跨列短路：`where a=1 or b=2` 两列无索引则全表扫
- 深度分页：`limit 1000000, 20`
- 回表过多：SELECT * 但索引无法覆盖

## EXPLAIN 关键字段判读表

| 字段 | 危险值 | 含义 |
|---|---|---|
| type / access | ALL、index | 全表扫或全索引扫 |
| key | NULL | 没用上任何索引 |
| rows | 远大于实际结果集 | 估算扫描行过多 |
| Extra | Using filesort、Using temporary | 需额外排序/临时表 |

## 输出格式

严格按 templates/report.md 的结构输出，不要自由发挥段落顺序。

# 索引反模式详解（reference.md）

## 反模式 1：隐式类型转换
**现象**：列是 varchar，查询写成数字字面量。
**示例**：`SELECT * FROM users WHERE phone = 13800138000`
**危害**：MySQL 会对 phone 列逐行套用类型转换函数，
       索引失效，退化为全表扫描。
**修复**：`WHERE phone = '13800138000'`（加引号）

## 反模式 2：函数包裹索引列
**现象**：对列施加函数后比较。
**示例**：`WHERE DATE(create_time) = '2026-07-11'`
**修复**：改为范围 `WHERE create_time >= '2026-07-11'
        AND create_time < '2026-07-12'`

## 反模式 3：左模糊
**现象**：`LIKE '%关键词'`
**说明**：B+Tree 索引按左前缀排序，左模糊无法定位。
       若必须全文检索，建议引入全文索引或 ES。

## 反模式 4：OR 跨无索引列
**修复**：为 OR 两侧列各建单列索引，优化器会用
       index_merge；或改写为 UNION ALL。

## 反模式 5：深度分页
**现象**：`LIMIT 1000000, 20`
**修复**：游标分页 `WHERE id > ? ORDER BY id LIMIT 20`

# scripts/explain_scan.py
# 用法: mysql -e "EXPLAIN <sql>" -B | python3 explain_scan.py
import sys, csv, json

RISKY_TYPE = {"ALL", "index"}          # 全表扫 / 全索引扫
RISKY_EXTRA = ["Using filesort", "Using temporary"]

rows = list(csv.DictReader(sys.stdin, delimiter="\t"))
findings = []
total_rows = 0
for r in rows:
    access = r.get("type") or r.get("access_method") or ""
    key = (r.get("key") or "").strip()
    est = int(r.get("rows", 0) or 0)
    extra = r.get("Extra", "")
    total_rows += est
    if access in RISKY_TYPE:
        findings.append(f"行{r.get('id')}: 访问方式 {access}（疑似全扫）")
    if not key and access not in ("const", "system"):
        findings.append(f"行{r.get('id')}: 未命中任何索引")
    for kw in RISKY_EXTRA:
        if kw in extra:
            findings.append(f"行{r.get('id')}: {kw}")

print(json.dumps({
    "estimated_total_rows": total_rows,
    "risk_count": len(findings),
    "risks": findings or ["未发现明显执行计划风险"]
}, ensure_ascii=False, indent=2))

当用户提供了 EXPLAIN 原始输出（TSV/表格）时，
先把它存为临时文件，再执行：
    python3 scripts/explain_scan.py < explain.tsv
拿到结构化风险摘要后，再结合反模式给出索引建议。

<!-- templates/report.md -->
## 🩺 索引诊断报告

### 1. 查询概要
- 数据库类型：MySQL / PostgreSQL
- 涉及表：
- 扫描行数（EXPLAIN 估算）：

### 2. 命中反模式
| 反模式 | 位置 | 严重度 | 修复建议 |
|---|---|---|---|

### 3. 索引方案
```sql
-- 建议索引（等值列 → 范围列 → 排序列）
CREATE INDEX idx_xxx ON tbl (col_a, col_b, col_c);

**操作说明**：在 SKILL.md 正文末尾加一句「输出格式严格遵循 templates/report.md」。这样 Claude 会先读模板再填空，而不是自由发挥。

### 第 7 步：测试、调优、上线

Skill 不是写完就灵，要像调 prompt 一样迭代 `description`。

**正向测试**（应当触发）：
- 「这条 SQL 跑了 6 秒，`SELECT * FROM orders WHERE user_id=88 AND status=1 ORDER BY create_time DESC`」
- 「帮我看看这个 EXPLAIN，rows 怎么这么大」

**负向测试**（不应误触发）：
- 「帮我写一个建表语句」——这是建表，不是优化，应触发建表类 Skill 而非本 Skill
- 「解释一下 B+Tree 原理」——这是科普，不需要出 DDL

**调优动作**：若负向误触发，在 `description` 里加**排除条件**，例如「仅用于已存在的查询的性能优化，不用于新建表结构设计」。

**预期结果**：正向命中、负向不命中，`/cost` 显示本 Skill 仅在相关对话被加载。

---

## 完整的 SKILL.md 总览

把上面几步拼起来，最终文件如下（可直接复制使用）：

````markdown
---
name: sql-index-doctor
description: |
  MySQL/PostgreSQL 慢查询索引优化顾问。当用户做以下事情时使用本 Skill：
  (1) 粘贴一段 SQL 问「为什么慢」「怎么优化」；(2) 提供 EXPLAIN 执行计划要解读；
  (3) 排查索引缺失、回表过多、全表扫描；(4) 需要 CREATE INDEX 的可执行 DDL；
  (5) 优化 WHERE / JOIN / ORDER BY / GROUP BY 的查询性能。
  不用于新建表结构设计。输出包含反模式清单、EXPLAIN 判读、建议索引、覆盖索引机会、DDL、回滚方案。
allowed-tools: Read, Grep, Glob, Bash(mysql:*), Bash(psql:*)
---

# SQL 索引医生

## 分析流程（严格按序）
1. 提取谓词：WHERE / JOIN ON / ORDER BY / GROUP BY 的列
2. 识别反模式：对照 reference.md 逐条扫描
3. 判读执行计划：用户提供则读，否则 `mysql -e "EXPLAIN <sql>"`；
   有 TSV 原始输出时先跑 `python3 scripts/explain_scan.py < explain.tsv`
4. 设计索引：等值列在前、范围列在后、排序列收尾
5. 输出 DDL：带注释的 CREATE INDEX + 列顺序理由

## 必须告警的反模式
隐式类型转换 / 左模糊 / 函数包裹列 / OR 跨列短路 / 深度分页 / 回表过多

## EXPLAIN 判读
- type/access 为 ALL/index → 全扫风险
- key 为 NULL → 未命中索引
- rows 远大于结果集 → 扫描过多
- Extra 含 Using filesort/Using temporary → 额外排序

## 输出格式
严格遵循 templates/report.md。细节判断依据见 reference.md。
````

---

## 实战案例：救活一条 6 秒的订单查询

### 现场还原

某电商后台一条订单查询，数据量 800 万行，稳定跑 6 秒：

```sql
SELECT id, order_no, user_id, amount, status, create_time
FROM orders
WHERE user_id = 88
  AND status = 1
  AND DATE(create_time) = '2026-07-11'
ORDER BY create_time DESC
LIMIT 20;

WHERE user_id = 88 AND status = 1
  AND create_time >= '2026-07-11 00:00:00'
  AND create_time <  '2026-07-12 00:00:00'

-- 联合索引：等值列(user_id, status) 在前，
-- 范围列(create_time) 在后，同时支撑 ORDER BY，避免 filesort
CREATE INDEX idx_uid_status_time ON orders (user_id, status, create_time);

DROP INDEX idx_uid_status_time ON orders;

flowchart TD
    A[用户粘贴慢SQL/EXPLAIN] --> B{Claude语义匹配<br/>description?}
    B -->|命中| C[加载 SKILL.md 全文]
    B -->|不命中| Z[走普通对话]
    C --> D[allowed-tools 收口权限]
    D --> E[1.提取谓词]
    E --> F[2.对照 reference.md 扫反模式]
    F --> G{用户提供EXPLAIN?}
    G -->|是| H[跑 scripts/explain_scan.py]
    G -->|否| I[Bash: mysql -e EXPLAIN]
    H --> J[3.结构化风险摘要]
    I --> J
    J --> K[4.设计联合索引<br/>等值→范围→排序]
    K --> L[5.评估覆盖索引]
    L --> M[按 templates/report.md 输出]
    M --> N[给出DDL + 验证 + 回滚]