从零造假数据工厂：Claude Code Skill 开发入门实战

mkdir -p ~/.claude/skills/hello-skill
cat > ~/.claude/skills/hello-skill/SKILL.md <<'EOF'
---
description: 问候并报告当前所在 git 分支。当用户说"打个招呼"或问当前分支时使用。
---
对用户说一句简短问候，然后用下面的信息说明当前仓库状态：

当前分支：!`git branch --show-current 2>/dev/null || echo "非 git 仓库"`
EOF

## 当前环境
```!
node --version
npm --version
git status --short

这是"预处理"，不是 Claude 自己执行——Claude 只看到最终结果。若要全局禁用（如受管环境），设 `"disableSkillShellExecution": true`，注入会被替换成 `[shell command execution disabled by policy]`。

---

## 五、字符串替换：$ARGUMENTS 与路径变量

调用 `/skill foo bar` 时，参数通过占位符进入正文：

| 变量 | 含义 |
|:--|:--|
| `$ARGUMENTS` | 全部参数原样字符串 |
| `$ARGUMENTS[0]` / `$0` | 第一个参数（0 起始），引号可传多词 |
| `$name` | frontmatter `arguments` 声明的具名参数 |
| `${CLAUDE_SKILL_DIR}` | 当前 `SKILL.md` 所在目录——**引用捆绑脚本用这个**，无论装在哪都正确 |
| `${CLAUDE_PROJECT_DIR}` | 项目根（v2.1.196+） |
| `${CLAUDE_SESSION_ID}` | 会话 ID，可做日志/临时文件命名 |

写脚本调用时务必用 `${CLAUDE_SKILL_DIR}/scripts/xxx.py`，不要写死 `~/.claude/skills/...`——后者在项目级或插件级安装时会失效。

---

## 六、实战案例：造假数据工厂 Skill（完整可运行）

### 需求

测试和演示经常需要一堆"像样"的数据：注册接口要 50 条用户、数据库要 200 行种子、前端原型要 CSV。手写费时、固定样例又太假。我们做一个 Skill：输入一个 JSON 样例，按字段名语义自动生成批量数据，支持 JSON/CSV/SQL 三种格式，纯标准库、零依赖。

### 目录结构

```text
~/.claude/skills/mock-data-factory/
├── SKILL.md                       # 主指令（第二层）
├── references/
│   └── data-conventions.md        # 字段语义规则（第三层，按需读）
└── scripts/
    └── generate.py                # 生成脚本（被执行，不进上下文）

---
name: mock-data-factory
description: 从一个 JSON 样例或字段描述，批量生成逼真的假数据（JSON/CSV/SQL）。用于造测试数据、种子数据、mock 接口返回、数据库填充、演示样例。
when_to_use: 出现"造数据/假数据/mock 数据/测试数据/种子数据/seed data/fake data/生成 N 条用户"等请求，或需要为接口/数据库/前端填充真实感数据时。
argument-hint: [count] [format=json|csv|sql] [table=users]
allowed-tools: Bash(python3 *)
---
# 假数据工厂

你是假数据生成助手，目标是产出语义逼真、可即用的数据。

## 工作流
1. 取得目标字段：用户给了 JSON 对象样例就用它做模板；只描述字段就先帮他构造一个样例对象。
2. 解析 $ARGUMENTS：第一个整数作为 count（默认 10）；json/csv/sql 任一作为 format（默认 json）；table= 后作为表名（默认 mock_data）。
3. 把样例写到临时文件，再执行生成器：
   ```bash
   python3 ${CLAUDE_SKILL_DIR}/scripts/generate.py \
     --template /tmp/mock-tpl.json --count <count> --format <fmt> --table <table>
   ```
4. 字段语义规则（手机号/邮箱/姓名/金额等如何造）见 [data-conventions.md](references/data-conventions.md)，需要时再读取。
5. 输出格式：json 用 ```json 代码块，csv/sql 用对应代码块；超过 30 行时只展示前若干行并说明完整写入了哪个文件。

## 约束
- 始终用 ${CLAUDE_SKILL_DIR} 定位脚本，不要硬编码安装路径。
- 新增字段规则时优先扩展 data-conventions.md，而不是把规则堆进本文件。

# 字段语义约定
generate.py 依据字段名（小写）推断语义。新增规则在此追加。

| 关键字 | 生成规则 |
|:--|:--|
| id / *_id | 自增整数（1, 2, 3…） |
| email / mail | user{n}@example.com |
| phone / mobile | 中国大陆手机号 1[3-9] + 9 位 |
| name / username | 中文姓名池随机 |
| age | 18–65 整数 |
| price/amount/salary/money/fee | 两位小数金额 |
| *date* / *_at / *_ts | ISO8601 日期（2024 起） |
| is_*/has_*/*bool* | 布尔 |
| province/city/region | 省份池 |

样例值无法推断时，按样例的 Python 类型回退：bool→随机布尔，int→0–1000，float→两位小数，str→"字段名_序号"。

#!/usr/bin/env python3
"""假数据工厂生成器，仅用标准库。
用法: generate.py --template sample.json --count 50 --format json|csv|sql --table users [--out file]
"""
import argparse, csv, io, json, random, sys, datetime

NAMES = ["张伟","王芳","李娜","刘洋","陈静","杨磊","赵敏","黄强","周杰","吴婷",
         "徐明","孙丽","马超","朱琳","胡涛","林燕","郭峰","何萍","高翔","罗静"]
DOMAINS = ["example.com","test.cn","mock.io","demo.org"]
PROVINCES = ["北京","上海","广东","浙江","江苏","四川","湖北","陕西"]

def fake_value(key, idx):
    k = key.lower()
    if k == "id" or k.endswith("_id") or k.endswith("id"):
        return idx
    if "email" in k or k.endswith("mail"):
        return f"user{idx}{random.randint(0,99)}@{random.choice(DOMAINS)}"
    if "phone" in k or "mobile" in k:
        return f"1{random.choice('35789')}{random.randint(100000000,999999999)}"
    if "name" in k:
        return random.choice(NAMES)
    if k == "age" or "age" in k:
        return random.randint(18, 65)
    if any(w in k for w in ("price","amount","salary","money","fee")):
        return round(random.uniform(10, 9999), 2)
    if "count" in k or "num" in k or k.startswith("qty"):
        return random.randint(1, 1000)
    if any(w in k for w in ("date","time","at")) or k.endswith("_ts"):
        return (datetime.date(2024,1,1) + datetime.timedelta(days=random.randint(0,500))).isoformat()
    if any(w in k for w in ("province","city","region")):
        return random.choice(PROVINCES)
    if "url" in k or "link" in k:
        return f"https://{random.choice(DOMAINS)}/{key}/{idx}"
    if k.startswith("is_") or k.startswith("has_") or "bool" in k:
        return random.choice([True, False])
    return None  # 回退到按样例类型推断

def gen_rows(sample, count):
    rows = []
    for i in range(1, count + 1):
        row = {}
        for key, val in sample.items():
            v = fake_value(key, i)
            if v is None:
                if isinstance(val, bool):   v = random.choice([True, False])
                elif isinstance(val, int):  v = random.randint(0, 1000)
                elif isinstance(val, float):v = round(random.uniform(0, 1000), 2)
                elif isinstance(val, str):  v = f"{key}_{i}"
                else:                        v = val
            row[key] = v
        rows.append(row)
    return rows

def to_sql(rows, table):
    cols = list(rows[0].keys())
    out = [f"CREATE TABLE IF NOT EXISTS {table} ({', '.join(cols)});"]
    for r in rows:
        vals = ["'%s'" % v if isinstance(v, str) else str(v) for v in r.values()]
        out.append(f"INSERT INTO {table} ({', '.join(cols)}) VALUES ({', '.join(vals)});")
    return "\n".join(out)

def to_csv(rows):
    buf = io.StringIO()
    w = csv.DictWriter(buf, fieldnames=list(rows[0].keys()))
    w.writeheader(); w.writerows(rows)
    return buf.getvalue()

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--template", required=True)
    ap.add_argument("--count", type=int, default=10)
    ap.add_argument("--format", default="json", choices=["json","csv","sql"])
    ap.add_argument("--table", default="mock_data")
    ap.add_argument("--out", default=None)
    a = ap.parse_args()

    with open(a.template, encoding="utf-8") as f:
        sample = json.load(f)
    if not isinstance(sample, dict):
        sys.exit("template 必须是 JSON 对象（字段 -> 样例值）")

    random.seed(42)  # 可复现
    rows = gen_rows(sample, a.count)
    if a.format == "json": text = json.dumps(rows, ensure_ascii=False, indent=2)
    elif a.format == "csv": text = to_csv(rows)
    else:                   text = to_sql(rows, a.table)

    if a.out:
        open(a.out, "w", encoding="utf-8").write(text)
        print(f"wrote {a.count} rows -> {a.out}", file=sys.stderr)
    else:
        print(text)

if __name__ == "__main__":
    main()

帮我造 20 条用户数据，JSON 格式，字段像这样：{"id":0,"name":"","email":"","phone":"","age":0,"province":"","created_at":""}

---
name: mock-data-factory
description: ...
context: fork
agent: general-purpose
allowed-tools: Bash(python3 *)
---

/plugin install skill-creator@claude-plugins-official
/reload-plugins

flowchart TD
    U["用户提问：造 20 条用户 JSON<br/>或 /mock-data-factory 20 json"] --> M{"命中触发？"}
    M -->|"description/when_to_use 命中<br/>或手动 /name"| L1["第一层 frontmatter 常驻"]
    M -->|"未命中且非手动"| X["不加载，零成本"]
    L1 --> L2["第二层：SKILL.md 正文进会话"]
    L2 --> SUB["$ARGUMENTS / ${CLAUDE_SKILL_DIR} 字符串替换"]
    SUB --> INJ["动态注入 !`git/python` 执行并内联输出"]
    INJ --> L3{"正文引用支撑文件？"}
    L3 -->|"是"| REF["第三层：按需读 references/*.md"]
    L3 -->|"否"| RUN["直接进入指令"]
    REF --> RUN
    RUN --> SCRIPT["执行 scripts/generate.py"]
    SCRIPT --> OUT["输出 JSON/CSV/SQL"]
    OUT --> KEEP["正文常驻至会话结束；fork 模式则只回传摘要"]
    style L1 fill:#e8f5e9
    style L2 fill:#fff3e0
    style REF fill:#e3f2fd