Claude Code Skill 可执行脚本封装开发实战：从零构建 schema-forge

flowchart TD
    A["第 0 层：所有 Skill 的 frontmatter<br/>~100 tokens / 个 · 始终在上下文"] --> B{"description 是否<br/>匹配当前任务？"}
    B -- 否 --> Z["该 Skill 完全不加载<br/>零 token 成本"]
    B -- 是 --> C["第 1 层：SKILL.md 主体<br/>完整指令 · 仅激活时加载<br/>建议 < 500 行 / < 5000 tokens"]
    C --> D{"是否需要确定性计算<br/>或精确执行？"}
    D -- 是 --> E["第 2 层：scripts/*.py 等<br/>按需执行 · 100% 确定性输出"]
    D -- 否 --> F{"是否需要深层参考资料？"}
    F -- 是 --> G["第 2 层：references/*.md<br/>按需读取 · 仅相关章节进上下文"]
    F -- 否 --> H["直接按主体指令完成任务"]
    E --> H
    G --> H
    style A fill:#e8f5e9
    style Z fill:#ffebee
    style E fill:#fff3e0
    style G fill:#e3f2fd

mkdir -p ~/.claude/skills/schema-forge/scripts
mkdir -p ~/.claude/skills/schema-forge/references

~/.claude/skills/schema-forge/
├── SKILL.md                       # 必需：frontmatter + 主体指令
├── scripts/
│   └── generate_schema.py         # 可执行脚本：确定性推理核心
└── references/
    ├── type-mapping.md            # JSON→Schema 类型映射详解
    └── merging-strategy.md        # 多样本合并策略详解

# ❌ 反面案例 A：太抽象
description: 一个数据相关的工具

# ❌ 反面案例 B：太宽泛，会和别的 Skill 抢触发
description: 用于处理 JSON 和代码生成任务

# ✅ 正面案例：具体、可匹配、有优先级
description: 从 JSON 样本数据推断并生成 JSON Schema (Draft 2020-12)。当用户提供 JSON 数据、API 响应样本、配置文件示例，要求生成对应的 JSON Schema、校验规则、类型定义，或在编写数据校验/接口契约时使用。优先调用内置的 generate_schema.py 脚本进行确定性推理，避免凭空手写 schema。

# schema-forge
（一句话定位）

## 何时使用
（2–4 个触发场景）

## 如何使用
（调用脚本的具体命令，含基本用法/内联用法/多样本用法）

## 规则
（必须遵守的硬性约束，编号列出，便于模型遵循）

## 详细类型映射
（一句话提示："见 references/type-mapping.md"，触发渐进披露）

---
name: schema-forge
description: 从 JSON 样本数据推断并生成 JSON Schema (Draft 2020-12)。当用户提供 JSON 数据、API 响应样本、配置文件示例，要求生成对应的 JSON Schema、校验规则、类型定义，或在编写数据校验/接口契约时使用。优先调用内置的 generate_schema.py 脚本进行确定性推理，避免凭空手写 schema。
---

# schema-forge

把 JSON 样本转换为符合 Draft 2020-12 规范的 JSON Schema。

## 何时使用
- 用户给出 JSON 示例，要求"生成 schema / 生成校验规则 / 推断类型"
- 需要为 API 响应、配置文件、数据契约编写 JSON Schema
- 需要把多个样本合并成一份统一的 schema

## 如何使用

脚本位于本 Skill 的 `scripts/generate_schema.py`，纯标准库实现，无需安装任何依赖。

### 基本用法（单文件）
\`\`\`bash
python3 ~/.claude/skills/schema-forge/scripts/generate_schema.py sample.json --root-title "User"
\`\`\`

### 从 stdin 内联（适合粘贴在对话里的 JSON）
\`\`\`bash
echo '{"id":1,"name":"ada","active":true}' | python3 ~/.claude/skills/schema-forge/scripts/generate_schema.py
\`\`\`

### 合并多个样本（显著提升推理准确度）
\`\`\`bash
python3 ~/.claude/skills/schema-forge/scripts/generate_schema.py a.json --merge b.json c.json
\`\`\`

## 规则
1. **优先调用脚本**，不要手动编写 schema。脚本输出是确定性的，比手写更可靠。
2. 脚本默认输出 Draft 2020-12 格式；若用户要求 Draft-07，告知其把输出的 `$schema` 改为 draft-07 的 URL 即可（数组/联合类型语义略有差异）。
3. 优先用多样本合并，对象 `required` 字段与联合类型的准确度会随样本数提升。
4. 输出 schema 后，简要提示可增强的方向（`format`、`pattern`、`enum`、`additionalProperties`），但不擅自改动脚本输出。

## 详细类型映射
完整的 JSON 值 → Schema 关键字映射，见 `references/type-mapping.md`。仅在用户追问某个具体类型的生成逻辑时才查阅。

#!/usr/bin/env python3
"""schema_forge: 从 JSON 样本推断 JSON Schema (Draft 2020-12)。纯标准库实现。"""
import json, sys, argparse
from collections import OrderedDict

# Python 类型 -> JSON Schema 基本类型
def infer_schema(value):
    if value is None:
        return {"type": "null"}
    if isinstance(value, bool):                      # 注意：bool 必须在 int 之前判断
        return {"type": "boolean"}
    if isinstance(value, int):
        return {"type": "integer"}
    if isinstance(value, float):
        return {"type": "number"}
    if isinstance(value, str):
        return {"type": "string"}
    if isinstance(value, list):
        if not value:
            return {"type": "array"}
        # 数组合并：把每个元素的 schema 合并成统一的 items
        return {"type": "array", "items": merge_many([infer_schema(v) for v in value])}
    if isinstance(value, dict):
        props, required = OrderedDict(), []
        for k, v in value.items():
            props[k] = infer_schema(v)
            required.append(k)
        schema = {"type": "object"}
        if props:
            schema["properties"] = props
            schema["required"] = required
        return schema
    return {}

def merge_two(a, b):
    ta, tb = a.get("type"), b.get("type")
    if ta == tb:
        if ta == "object":                           # 同为对象：合并 properties 与 required
            props = dict(a.get("properties", {}))
            req = list(dict.fromkeys(a.get("required", []) + b.get("required", [])))
            for k, v in b.get("properties", {}).items():
                props[k] = merge_two(props[k], v) if k in props else v
            return {"type": "object", "properties": props, "required": req}
        if ta == "array":
            return {"type": "array", "items": merge_two(a.get("items", {}), b.get("items", {}))}
        return a
    # 类型不同：升级为联合类型（type 数组）
    return {"type": sorted({ta, tb})}

def merge_many(schemas):
    out = schemas[0]
    for s in schemas[1:]:
        out = merge_two(out, s)
    return out

def main():
    ap = argparse.ArgumentParser(description="从 JSON 样本生成 JSON Schema")
    ap.add_argument("input", nargs="?", help="JSON 文件路径，省略则读 stdin")
    ap.add_argument("--merge", nargs="*", default=[], help="额外样本文件，合并推理")
    ap.add_argument("--root-title", default="", help="根 schema 的 title 字段")
    args = ap.parse_args()

    # 收集所有输入源：主输入 + --merge 列表
    sources = ([args.input] if args.input else []) + list(args.merge)
    raw = sys.stdin.read() if (not args.input and not sys.stdin.isatty()) else None

    schemas = []
    if raw is not None:
        schemas.append(infer_schema(json.loads(raw)))
    for path in sources:
        with open(path, encoding="utf-8") as f:
            schemas.append(infer_schema(json.load(f)))

    if not schemas:
        ap.error("需要提供 JSON 输入（文件参数或 stdin）")

    final = merge_many(schemas)
    out = {"$schema": "https://json-schema.org/draft/2020-12/schema"}
    if args.root_title:
        out["title"] = args.root_title
    out.update(final)
    print(json.dumps(out, indent=2, ensure_ascii=False))

if __name__ == "__main__":
    main()

chmod +x ~/.claude/skills/schema-forge/scripts/generate_schema.py

# JSON → Schema 类型映射详解

| JSON 值 | 生成关键字 | 备注 |
|---------|-----------|------|
| `null` | `"type": "null"` | |
| `true/false` | `"type": "boolean"` | Python 中 bool 是 int 子类，须先判 bool |
| `42` | `"type": "integer"` | |
| `3.14` | `"type": "number"` | |
| `"ada"` | `"type": "string"` | 可后续建议追加 `format: date-time` 等 |
| `[]` | `"type": "array"` | 空数组无法推断 items |
| `[...]` | `"type":"array","items":{...}` | 元素 schema 经 merge_many 合并 |
| `{...}` | `"type":"object","properties":{...},"required":[...]` | 全部键默认 required |

## 联合类型
当多个样本里同一字段出现不同类型，merge_two 会把 `type` 升级为数组：
`{"type": ["integer", "string"]}`。

flowchart LR
    A["1. 明确能力边界<br/>确定输入/输出"] --> B["2. 建目录骨架<br/>SKILL.md + scripts/ + references/"]
    B --> C["3. 写 frontmatter<br/>打磨 description（触发核心）"]
    C --> D["4. 写主体指令<br/>何时用/如何用/规则/<500行"]
    D --> E{"需要确定性计算？"}
    E -- 是 --> F["5. 封装 scripts/*.py<br/>零依赖 + 纯函数契约"]
    E -- 否 --> G["6. 下沉深层知识到 references/"]
    F --> G
    G --> H["7. 触发测试<br/>正例激活 / 反例不激活"]
    H --> I{"测试通过？"}
    I -- 否 --> J["8a. 回去调 description<br/>或主体规则"]
    J --> C
    I -- 是 --> K["8b. 发布<br/>个人级 / 项目级 / 插件市场"]
    style C fill:#fff3e0
    style F fill:#e8f5e9
    style H fill:#e3f2fd

{"id": 101, "name": "ada", "email": "[email protected]", "roles": ["admin"], "active": true}

{"id": 102, "name": "bob", "email": null, "roles": ["admin", "user"], "active": false, "last_login": "2026-06-01"}

python3 ~/.claude/skills/schema-forge/scripts/generate_schema.py a.json --merge b.json --root-title "User"

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "User",
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "name": { "type": "string" },
    "email": { "type": ["string", "null"] },
    "roles": { "type": "array", "items": { "type": "string" } },
    "active": { "type": "boolean" },
    "last_login": { "type": "string" }
  },
  "required": ["id", "name", "email", "roles", "active", "last_login"]
}