api-contract-doc/
├── SKILL.md              # 唯一必需：入口文件
├── scripts/              # 可选：可执行脚本
│   └── extract-endpoints.js
└── reference/            # 可选：按需加载的详细资料
    ├── openapi-conventions.md
    └── team-api-style.md

flowchart TD
    A[Claude Code 启动] --> B[扫描三个位置的 skills 目录]
    B --> C[只读每个 SKILL.md 的<br/>frontmatter + 正文摘要]
    C --> D{当前任务是否匹配某 Skill?}
    D -->|否| E[跳过该 Skill 不占上下文]
    D -->|是| F[加载完整 SKILL.md 正文]
    F --> G{需要更深细节?}
    G -->|是| H[按需 Read reference 文件]
    G -->|需要执行确定性操作| I[Bash 调用 scripts 脚本]
    H --> J[按规范产出结果]
    I --> J

/skill-creator 帮我创建一个叫 api-contract-doc 的 skill，
功能是扫描项目路由代码生成 OpenAPI 3.0 接口文档

mkdir -p ~/.claude/skills/api-contract-doc/scripts
mkdir -p ~/.claude/skills/api-contract-doc/reference
touch ~/.claude/skills/api-contract-doc/SKILL.md

---
name: api-contract-doc
description: 扫描项目路由或控制器源码，反向工程生成符合 OpenAPI 3.0 规范的接口契约文档（YAML/JSON）。当用户要"生成接口文档""出 API 文档""补接口说明""把代码转成 OpenAPI/Swagger""整理接口契约"时使用。支持 Express/Koa/Fastify 风格路由。
---

# 接口契约文档生成

## 何时使用
当用户希望从现有路由/控制器代码反向生成接口文档时激活本 Skill。

## 工作流程

1. **定位路由**：先用 Grep/Glob 找到项目的路由定义文件。
   - Express：搜索 `app\.(get|post|put|delete|patch)\(` 或 `router\.(get|post)`
   - Koa：搜索 `router\.(get|post)` 或 `\.ctx\.`
   - 若用户指定了目录，优先扫该目录。

2. **粗扫出端点清单**：调用本 Skill 的脚本生成机器可读草稿：
   ```bash
   node ~/.claude/skills/api-contract-doc/scripts/extract-endpoints.js <路由文件或目录>
   ```
   脚本会输出 JSON 数组，每项含 method、path、handlerName。

3. **补全语义信息**：脚本只能给出骨架，请求/响应 schema、描述、示例需要你阅读
   handler 函数体与相关 model 定义后补全。

4. **套用团队规范**：补全时务必遵循 reference/team-api-style.md 的命名与错误码约定；
   OpenAPI 字段写法遵循 reference/openapi-conventions.md。

5. **产出**：默认输出 openapi.yaml 到项目根目录，并打印一段摘要给用户确认。

## 注意
- 路径参数（如 /users/:id）要转成 OpenAPI 的 {id} 写法。
- 遇到无法静态推断的字段，标注 TODO 而非编造。

# OpenAPI 3.0 字段约定

- paths 下每个操作必填：summary、operationId、responses
- operationId 用 camelCase，全局唯一
- 响应体统一走 components/schemas 复用，避免内联
- 错误响应统一引用 ProblemDetails（RFC 7807）结构
- 字段 description 必填，用中文，一句话讲清用途

# 团队接口风格

- URL 一律小写，单词用连字符分隔：/user-profiles 而非 /userProfiles
- 列表接口必须支持 page、pageSize 分页参数
- 时间字段用 ISO 8601 字符串，字段名以 At 结尾：createdAt、updatedAt
- 业务错误码 5 位数字，前两位标识模块

#!/usr/bin/env node
// 从 Express/Koa 路由文件中静态提取端点骨架，输出 JSON
const fs = require('fs');
const path = require('path');

const target = process.argv[2];
if (!target) {
  console.error('用法: extract-endpoints.js <文件或目录>');
  process.exit(1);
}

const files = [];
function collect(p) {
  const stat = fs.statSync(p);
  if (stat.isFile() && /\.(js|ts)$/.test(p)) files.push(p);
  else if (stat.isDirectory()) {
    for (const f of fs.readdirSync(p)) collect(path.join(p, f));
  }
}
collect(path.resolve(target));

// 匹配 app.get('/x', ...) / router.post('/y', ...)
const routeRe = /\.(get|post|put|delete|patch)\(\s*['"`]([^'"`]+)['"`]/g;
const paramRe = /:([A-Za-z_]\w*)/g;

const endpoints = [];
for (const file of files) {
  const src = fs.readFileSync(file, 'utf8');
  let m;
  while ((m = routeRe.exec(src)) !== null) {
    const method = m[1].toUpperCase();
    const rawPath = m[2];
    // Express :id -> OpenAPI {id}
    const openapiPath = rawPath.replace(paramRe, '{$1}');
    endpoints.push({
      method,
      path: openapiPath,
      sourceFile: path.relative(process.cwd(), file),
      handlerName: null, // 由模型阅读函数体补全
    });
  }
}

console.log(JSON.stringify({ count: endpoints.length, endpoints }, null, 2));

chmod +x ~/.claude/skills/api-contract-doc/scripts/extract-endpoints.js

{
  "count": 2,
  "endpoints": [
    { "method": "GET", "path": "/users/{id}", "sourceFile": "routes/users.js", "handlerName": null },
    { "method": "POST", "path": "/orders", "sourceFile": "routes/orders.js", "handlerName": null }
  ]
}

const router = require('express').Router();

// 创建订单
router.post('/orders', (req, res) => {
  const { userId, amount } = req.body;
  res.json({ id: 1001, userId, amount, createdAt: '2026-07-12T08:00:00Z' });
});

// 查询订单详情
router.get('/orders/:id', (req, res) => {
  res.json({ id: req.params.id, status: 'paid' });
});

module.exports = router;

openapi: 3.0.3
info:
  title: Mini Shop API
  version: 1.0.0
paths:
  /orders:
    post:
      summary: 创建订单
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId: { type: integer, description: 下单用户ID }
                amount: { type: number, description: 订单金额（元） }
      responses:
        '200':
          description: 创建成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: integer }
                  userId: { type: integer }
                  amount: { type: number }
                  createdAt: { type: string, format: date-time, description: 创建时间 }
  /orders/{id}:
    get:
      summary: 查询订单详情
      operationId: getOrderById
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: integer }
                  status: { type: string, description: 订单状态 }