给 Skill 挂脚本：从零造一个 API 文档自动生成器

flowchart LR
    A["会话启动<br/>扫描所有 SKILL.md"] --> B["第0层<br/>只读 name+description<br/>约30-50 tokens/个"]
    B --> C{"语义匹配<br/>用户意图 vs 描述"}
    C -->|命中| D["第1层<br/>加载 SKILL.md 正文<br/>通常<5000 tokens"]
    C -->|未命中| E["保持休眠<br/>零开销"]
    D --> F["第2层<br/>按需读取 references/<br/>执行 scripts/<br/>脚本代码不进上下文"]

# 创建目录骨架
mkdir -p .claude/skills/openapi-doc-gen/scripts
mkdir -p .claude/skills/openapi-doc-gen/references

# 查看结构
tree .claude/skills/openapi-doc-gen

.claude/skills/openapi-doc-gen
├── SKILL.md          ← 必需：核心指令
├── scripts/          ← 可选：可执行脚本
└── references/       ← 可选：按需加载的参考资料

---
name: openapi-doc-gen
description: 把 OpenAPI/Swagger 规范文件（.json/.yaml）转成团队风格的中文 Markdown 接口文档。当用户提到"生成接口文档""转 OpenAPI""Swagger 转文档""整理 API 文档"或需要把 .openapi.json 输出成可读文档时使用此技能。
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
metadata:
  version: "1.0.0"
  author: "platform-team"
---

"帮我把这份 swagger 整理成文档"   ← 应触发
"这个 API 怎么调用，给我整理下"    ← 边界情况
"重命名这个变量"                  ← 不应触发

#!/usr/bin/env python3
"""openapi-doc-gen: Convert an OpenAPI 3.x spec to team-style Markdown.
Usage: python3 gen_doc.py <input.openapi.json|yaml> [output.md]
Only uses Python standard library — no pip install needed.
"""
import json, sys, os

def load_spec(path):
    with open(path, encoding="utf-8") as f:
        text = f.read()
    if path.endswith((".yaml", ".yml")):
        # yaml is not stdlib; do a tiny fallback if PyYAML missing
        try:
            import yaml
            return yaml.safe_load(text)
        except ImportError:
            raise SystemExit("ERROR: PyYAML not installed. Convert to JSON first.")
    return json.loads(text)

def render(spec):
    info = spec.get("info", {})
    out = [f"# {info.get('title','API')}", ""]
    out.append(f"> 版本：{info.get('version','—')}  ")
    if info.get("description"):
        out.append(f"> {info['description']}")
    out.append("\n## 接口列表\n")
    paths = spec.get("paths", {})
    for path, methods in paths.items():
        for method, op in methods.items():
            if method.lower() not in ("get","post","put","delete","patch"):
                continue
            tag = (op.get("tags") or ["默认"])[0]
            summary = op.get("summary", op.get("operationId","未命名"))
            out.append(f"### `{method.upper()} {path}`")
            out.append(f"- 标签：{tag}")
            out.append(f"- 说明：{summary}")
            params = op.get("parameters") or []
            if params:
                out.append("- 参数：")
                for p in params:
                    out.append(f"  - `{p['name']}` ({p.get('in','?')}, "
                               f"{'必填' if p.get('required') else '可选'}): "
                               f"{p.get('description','')}")
            out.append("")
    return "\n".join(out)

def main():
    if len(sys.argv) < 2:
        print(__doc__); sys.exit(1)
    spec = load_spec(sys.argv[1])
    md = render(spec)
    out_path = sys.argv[2] if len(sys.argv) > 2 else "API_DOC.md"
    with open(out_path, "w", encoding="utf-8") as f:
        f.write(md)
    print(f"OK -> {out_path} ({len(md)} chars)")

if __name__ == "__main__":
    main()

chmod +x .claude/skills/openapi-doc-gen/scripts/gen_doc.py

# 准备一份测试用规范
cat > /tmp/petstore.openapi.json <<'EOF'
{"openapi":"3.0.0","info":{"title":"Pet Store","version":"1.0.0"},
 "paths":{"/pets":{"get":{"tags":["宠物"],"summary":"列出所有宠物",
   "parameters":[{"name":"limit","in":"query","required":false,"description":"返回数量"}]},
   "post":{"summary":"新增宠物"}}}}
EOF

python3 .claude/skills/openapi-doc-gen/scripts/gen_doc.py /tmp/petstore.openapi.json /tmp/out.md
cat /tmp/out.md

OK -> /tmp/out.md (286 chars)
# Pet Store

> 版本：1.0.0  

## 接口列表

### `GET /pets`
- 标签：宠物
- 说明：列出所有宠物
- 参数：
  - `limit` (query, 可选): 返回数量

### `POST /pets`
- 标签：默认
- 说明：新增宠物

---
name: openapi-doc-gen
description: 把 OpenAPI/Swagger 规范文件（.json/.yaml）转成团队风格的中文 Markdown 接口文档。当用户提到"生成接口文档""转 OpenAPI""Swagger 转文档""整理 API 文档"或需要把 .openapi.json 输出成可读文档时使用此技能。
allowed-tools: [Bash, Read, Write, Edit]
metadata: {version: "1.0.0", author: "platform-team"}
---

# OpenAPI 接口文档生成

## 何时使用
当用户需要把 OpenAPI 3.x 规范（.json / .yaml / .yml，常含 "openapi" 或 "swagger" 字段）
转成可读 Markdown 文档时使用本技能。

## 操作步骤
1. 先用 Read 工具读取规范文件，确认是 OpenAPI 3.x（顶层有 `openapi` 或 `swagger` 字段）。
   - 若是更老的 Swagger 2.0，先告知用户并参考 references/swagger2-migration.md 做升级。
2. 用 Bash 执行本技能自带的转换脚本：
   `python3 scripts/gen_doc.py <规范文件路径> <输出.md>`
   脚本路径相对于本技能目录。脚本只用标准库，无需安装依赖。
3. 用 Read 检查生成结果。若用户要求"分组按 tag 排序""加示例""加鉴权说明"等增强，
   读取 references/doc-style-guide.md 获取团队风格规范，再二次加工。
4. 用 Write 写出最终文档，默认文件名 API_DOC.md，除非用户指定。

## 边界
- 规范里含 `$ref` 外部引用时，先提示用户需先内联（bundle），脚本不自动解析外部 ref。
- 单个文件超过 500 个接口时，分章节写入，避免单文件过大。

# 团队接口文档风格规范

## 标题层级
- 一级标题用接口名，如 `# Pet Store API`
- 每个接口用三级标题 `### METHOD path`
- 字段表格用 Markdown 表格，列：参数名 | 位置 | 类型 | 是否必填 | 说明

## 必须包含的段落
每个接口需含：用途说明、请求参数表、响应示例、错误码映射。
鉴权接口在标题后加 `🔒 需鉴权` 标记。

## 错误码表
| code | 含义 | 处理建议 |
|------|------|----------|
| 400 | 参数错误 | 检查必填项 |
| 401 | 未授权 | 刷新 token |

# 退出当前会话后重新进入项目目录
claude

/skills

帮我把 petstore.openapi.json 转成接口文档

.claude/skills/openapi-doc-gen/
├── SKILL.md
├── scripts/
│   └── gen_doc.py
└── references/
    ├── doc-style-guide.md
    └── swagger2-migration.md

用户：把 api/v1/openapi.json 转成接口文档，按咱们团队风格加上错误码说明

Claude（思考）：识别到"转成接口文档""团队风格"→ 触发 openapi-doc-gen
  1. Read api/v1/openapi.json → 确认 OpenAPI 3.0
  2. Bash: python3 scripts/gen_doc.py api/v1/openapi.json API_DOC.md
     → OK -> API_DOC.md (8421 chars)
  3. 因为要求"团队风格"，Read references/doc-style-guide.md
  4. Edit API_DOC.md：补错误码表、加 🔒 鉴权标记、统一标题层级
  5. Write 完成，输出 API_DOC.md

flowchart TD
    S[".claude/skills/<br/>本地验证"] -->|"成熟后"| P["plugin/skills/<br/>打包"]
    P --> M["插件市场<br/>/plugin install"]
    M --> T["团队成员<br/>一键复用"]
    S -.->|"日常迭代"| S