┌─────────────────────────────────────────────┐
│  Skill 两种形态对比                          │
├──────────────────┬──────────────────────────┤
│ 纯指令型         │ 计算型（本教程）          │
├──────────────────┼──────────────────────────┤
│ 只有 SKILL.md    │ SKILL.md + scripts/*.py   │
│ 模型全程推理      │ 脚本精确计算，模型解读    │
│ 适合规则/规范     │ 适合统计/转换/生成        │
│ 计算易出错        │ 结果可复现                │
└──────────────────┴──────────────────────────┘

csv-profiler/
├── SKILL.md              # 入口：导航 + 触发说明（必填）
├── scripts/
│   └── profile.py        # 核心计算脚本（执行的，不是读进上下文的）
├── reference/
│   └── metrics.md        # 各指标详细定义（按需加载）
└── examples/
    └── sample-report.md  # 期望输出的样例

---
name: csv-profiler
description: Profile a CSV file and produce a per-column data quality report.
  Use when the user asks to inspect, profile, audit, or understand a CSV
  dataset, or wants column stats, null rates, cardinality, or distributions.
  Triggers on phrases like "看看这个表", "数据画像", "字段体检", "missing rate".
argument-hint: [path-to-csv]
arguments: [file]
allowed-tools: Bash(python3 *)
disable-model-invocation: false
user-invocable: true
---

#!/usr/bin/env python3
"""CSV 列级数据画像：类型推断、空值率、基数、数值统计、高频值。"""
import csv
import sys
from collections import Counter
from pathlib import Path

def infer_type(values):
    nums, non_empty = 0, 0
    for v in values:
        if v == "" or v is None:
            continue
        non_empty += 1
        try:
            float(v); nums += 1
        except ValueError:
            pass
    if non_empty == 0:
        return "empty"
    return "numeric" if nums / non_empty > 0.8 else "text"

def profile(path):
    rows = list(csv.DictReader(open(path, encoding="utf-8-sig")))
    if not rows:
        return "## 报告\n\n（文件为空或无数据行）"
    cols = rows[0].keys()
    lines = [f"## 数据画像：`{Path(path).name}`\n",
             f"- 总行数：**{len(rows)}**，列数：**{len(list(cols))}**\n",
             "| 列 | 类型 | 空值率 | 基数 | 高频值 / 范围 |",
             "|---|---|---|---|---|"]
    for c in rows[0].keys():
        vals = [r[c] for r in rows]
        n = len(vals)
        missing = sum(1 for v in vals if v == "" or v is None)
        non_empty = [v for v in vals if v != "" and v is not None]
        ctype = infer_type(vals)
        card = len(set(non_empty))
        top = Counter(non_empty).most_common(3)
        if ctype == "numeric":
            nums = sorted(float(v) for v in non_empty)
            scope = f"min {nums[0]:g} / max {nums[-1]:g}"
        else:
            scope = "; ".join(f"{k}({ct})" for k, ct in top)
        lines.append(f"| `{c}` | {ctype} | {missing/n:.1%} | {card} | {scope} |")
    return "\n".join(lines)

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("用法: profile.py <csv路径>"); sys.exit(1)
    print(profile(sys.argv[1]))

## 任务

对用户给出的 CSV（路径在 $file，若未提供则先问用户要路径）生成列级数据画像。

## 步骤

1. 跑画像脚本，拿到结构化报告：
   ```bash
   python3 ${CLAUDE_SKILL_DIR}/scripts/profile.py "$file"
   ```
2. 把脚本输出的表格原样呈现给用户。
3. 针对**异常列**追加自然语言点评：空值率 >50% 的列提示"考虑删除或补全"；
   基数=1 的常量列提示"无信息量"；文本列基数接近行数提示"可能是 ID"。

## 何时不该用

- 文件不是 CSV（xlsx/json）→ 先转 CSV 或换工具
- 列数 >500 → 提醒用户可能需采样

## 附加资源
- 各指标精确定义见 [reference/metrics.md](reference/metrics.md)
- 期望输出样例见 [examples/sample-report.md](examples/sample-report.md)

/plugin install skill-creator@claude-plugins-official
/reload-plugins
evaluate my csv-profiler skill with skill-creator

order_id,customer,amount,status,note
1,张三,99.5,paid,
2,李四,,pending,
3,张三,250.0,paid,VIP
4,,12.0,paid,
5,王五,12.0,paid,

flowchart TD
    A[用户: 帮我体检这个CSV] --> B{description 匹配?}
    B -- 是 --> C[加载 SKILL.md 正文进上下文]
    B -- 否 --> Z[不触发本Skill]
    C --> D[模型读导航层<br/>决定跑哪个脚本]
    D --> E["执行 python3<br/>${CLAUDE_SKILL_DIR}/scripts/profile.py<br/>(allowed-tools 免审批)"]
    E --> F[脚本输出结构化表格]
    F --> G[模型: 表格原样呈现<br/>+ 异常列自然语言点评]
    G --> H[用户拿到数据画像报告]
    I[skill-creator 评测] -.基准对比.-> B
    I -.A/B盲测.-> D