Claude Code Skill开发实战：从创建到发布全流程

.claude/
├── CLAUDE.md                          # 项目级全局指令
├── skills/
│   ├── code-review/
│   │   ├── SKILL.md                   # Skill主文件
│   │   ├── templates/                 # 支撑资源
│   │   │   └── review-checklist.md
│   │   └── examples/
│   │       └── sample-review.md
│   ├── api-doc-generator/
│   │   ├── SKILL.md
│   │   └── resources/
│   │       └── openapi-template.yaml
│   └── deploy/
│       └── SKILL.md
├── commands/                          # 自定义命令（已逐渐融入Skill体系）
│   └── quick-fix.md
└── settings.json

---
name: api-doc-generator
description: >
  从Express/FastAPI路由代码自动生成OpenAPI 3.0规范文档。
  当用户提到"生成API文档"、"OpenAPI"、"Swagger规范"时触发。
  支持从JSDoc/Python type hints自动提取参数与响应类型。
trigger: |
  用户提到以下任一场景时触发：
  - 生成或更新OpenAPI/Swagger文档
  - 从代码提取API端点信息
  - API文档化、接口文档
  用户主动调用 /api-doc-generator 时直接加载。
allowed-tools:
  - Read
  - Write
  - Glob
  - Grep
  - Bash(npx swagger-cli validate *)
disabled: false
version: 1.2.0
author: your-team
---

---
name: api-doc-generator
description: 从路由代码生成OpenAPI 3.0规范文档
---

# API文档生成器

## 触发条件
当用户要求生成API文档、OpenAPI规范、Swagger文档时触发。

## 工作流程

### 第1步：发现路由文件
使用Glob定位所有路由定义文件：
- Express: `**/routes/**/*.{js,ts}` 或文件中包含 `router.(get|post|put|delete)`
- FastAPI: `**/*.py` 中包含 `@router` 或 `@app` 装饰器
- NestJS: `**/*.controller.ts`

### 第2步：提取端点信息
对每个路由文件，提取：
- HTTP方法和路径
- 请求参数（query/path/body）
- 认证要求
- 响应类型和状态码
- JSDoc/Python type hints中的描述

### 第3步：生成OpenAPI规范
输出完整的`openapi.yaml`文件，包含：
- `info`区块（从package.json读取项目名称和版本）
- `paths`区块（所有端点）
- `components/schemas`（复用类型定义）
- `securitySchemes`（如果检测到认证中间件）

### 第4步：验证
运行 `npx swagger-cli validate openapi.yaml` 确认规范正确。

## 输出格式
- 文件路径: `docs/openapi.yaml`
- 如已存在，增量更新而非覆盖

## 约束
- 不生成伪造的端点，只文档化实际存在的路由
- 响应schema必须与代码中的类型定义一致
- 遇到无法推断的类型时，标记为`object`并在注释中提醒用户

flowchart TB
    subgraph "第1层：元数据索引 (~100 tokens)"
        A["name + description"] --> B{匹配用户意图?}
    end
    B -->|否| C["跳过，不消耗更多token"]
    B -->|是| D["加载SKILL.md完整内容"]

    subgraph "第2层：核心指令 (500-2000 tokens)"
        D --> E["工作流程步骤"]
        E --> F["约束条件"]
        F --> G{需要参考资源?}
    end
    G -->|否| H["直接执行任务"]
    G -->|是| I["按需读取resources/"]

    subgraph "第3层：支撑资源 (按需加载)"
        I --> J["模板文件"]
        I --> K["示例文件"]
        I --> L["参考文档"]
    end

    J --> H
    K --> H
    L --> H

mkdir -p ~/.claude/skills/conventional-commit

---
name: conventional-commit
description: >
  Git提交规范化助手。根据暂存区的代码变更自动生成符合Conventional Commits规范的提交信息。
  当用户要求commit、提交代码、写commit message时触发。
  支持type自动推断、scope提取、breaking change检测。
trigger: |
  用户提到commit、提交、commit message、git commit时触发。
  不在用户讨论Git其他操作（push、pull、merge）时触发。
allowed-tools:
  - Bash(git status *)
  - Bash(git diff *)
  - Bash(git log *)
  - Bash(git add *)
  - Bash(git commit *)
---

# Conventional Commit 规范化助手

## 工作流程

### 第1步：分析变更
1. 运行 `git status` 查看暂存区和工作区状态
2. 运行 `git diff --cached` 查看已暂存的变更
3. 运行 `git diff` 查看未暂存的变更
4. 运行 `git log --oneline -10` 了解最近提交风格

### 第2步：推断type
根据变更内容推断commit type：
- `feat`: 新增功能、新增文件、新增路由/端点
- `fix`: 修复bug、修正错误行为、修复测试
- `docs`: 仅文档变更（README、注释、JSDoc）
- `style`: 代码格式调整，不影响逻辑（空格、分号、import排序）
- `refactor`: 重构，既非新功能也非修复（重命名、提取函数、移动文件）
- `perf`: 性能优化（缓存、惰性加载、查询优化）
- `test`: 新增或修改测试
- `ci`: CI/CD配置变更（GitHub Actions、Dockerfile）
- `chore`: 构建工具、依赖更新、配置文件

### 第3步：提取scope
- 从变更文件路径推断scope（如 `src/auth/` → scope为 `auth`）
- 如果涉及多个scope，选择影响最大的一个
- 如果无法确定，省略scope

### 第4步：检测Breaking Change
- 查找 `BREAKING CHANGE:` 或 `BREAKING-CHANGE:` 注释
- 检查是否删除了公开API、重命名了导出函数、修改了配置格式
- 如检测到，在type后加 `!` 并在footer中说明

### 第5步：生成提交信息
格式：

规则：
- 描述用祈使句（"add feature" 非 "added feature"）
- 描述不超过50字符
- 不以句号结尾
- 如有Co-Author-By信息，保留在footer

### 第6步：执行提交
- 使用HEREDOC格式传递commit message
- 提交后运行 `git status` 确认成功

## 约束
- 不自动 `git add`，只提交已暂存的文件
- 不自动push
- 如果暂存区为空，提醒用户先暂存文件
- 遵循项目已有的commit风格（从git log学习）

# Type推断示例

## feat
- 新增 `src/api/users.ts` 文件，包含用户CRUD端点
- 在 `index.ts` 中新增路由注册
- 添加新的环境变量配置项

## fix
- 修复 `validateToken` 在过期时间为null时的空指针异常
- 修正用户角色权限检查的逻辑错误
- 修复测试中的mock数据与实际schema不匹配

## refactor
- 将 `UserService` 拆分为 `UserQueryService` 和 `UserCommandService`
- 将公共工具函数从 `utils.ts` 提取到 `shared/utils.ts`
- 重命名 `getUserById` → `findUserById`

> /conventional-commit 帮我提交代码

> 请帮我commit当前的变更

.claude/skills/api-doc-generator/
├── SKILL.md                    # 核心指令
├── resources/
│   ├── openapi-template.yaml   # OpenAPI模板
│   ├── express-patterns.md     # Express路由识别模式
│   └── fastapi-patterns.md     # FastAPI路由识别模式
├── examples/
│   ├── sample-input.ts         # 示例输入代码
│   └── sample-output.yaml      # 示例输出文档
└── TROUBLESHOOTING.md          # 调试指南

### 第3步：生成规范
参考 `resources/openapi-template.yaml` 生成基础结构。
参照 `examples/sample-output.yaml` 的格式。

# 在Claude Code中使用skill-creator进行评估
> 使用skill-creator评估我的conventional-commit skill

flowchart LR
    A["编写Skill v1"] --> B["运行10次测试任务"]
    B --> C["记录触发率和输出质量"]
    C --> D["修改description/指令体 → v2"]
    D --> E["运行相同10次测试任务"]
    E --> F["对比v1 vs v2"]
    F --> G{v2更优?}
    G -->|是| H["采用v2"]
    G -->|否| I["回退v1，调整方向"]
    I --> D

flowchart TD
    A["Skill未触发"] --> B{"文件路径正确?"}
    B -->|否| C["修正路径:<br/>.claude/skills/name/SKILL.md"]
    B -->|是| D{"description足够具体?"}
    D -->|否| E["增加触发关键词<br/>和场景描述"]
    D -->|是| F{"与CLAUDE.md冲突?"}
    F -->|是| G["CLAUDE.md可能包含<br/>矛盾的指令"]
    F -->|否| H{"disabled: true?"}
    H -->|是| I["设为false"]
    H -->|否| J{"settings.json中<br/>被禁用?"}
    J -->|是| K["检查settings.json<br/>skills配置"]
    J -->|否| L{"与其他Skill冲突?"}
    L -->|是| M["合并或差异化<br/>description"]
    L -->|否| N["用斜杠命令手动测试<br/>/skill-name"]

# 检查Skill是否被识别
ls -la ~/.claude/skills/conventional-commit/SKILL.md

# 验证YAML语法
head -20 ~/.claude/skills/conventional-commit/SKILL.md

# 在Claude Code中强制触发
> /conventional-commit

# 查看Skill加载状态
> 你加载了哪些Skills？请列出所有已安装的Skill名称和描述

# 项目级Skill（跟随项目）
.claude/skills/conventional-commit/SKILL.md

# 全局Skill（跟随个人）
~/.claude/skills/conventional-commit/SKILL.md

# 发布到marketplace（使用publishing-a-claude-skill skill）
> 使用publishing-a-claude-skill发布我的conventional-commit skill

# 安装他人发布的Skill
claude skill install @author/conventional-commit

# 从GitHub仓库安装
git clone https://github.com/anthropics/skills.git /tmp/skills
cp -r /tmp/skills/conventional-commit ~/.claude/skills/

# 或使用社区工具
npx -y claude-skills-cli install conventional-commit

sequenceDiagram
    participant U as 用户
    participant CR as code-review Skill
    participant CC as conventional-commit Skill
    participant DP as deploy Skill

    U->>CR: /code-review 审查PR
    CR->>CR: 分析代码变更
    CR-->>U: 审查报告+修改建议
    U->>CC: /conventional-commit 提交
    CC->>CC: 分析暂存区
    CC-->>U: 生成规范commit
    U->>DP: /deploy 发布到staging
    DP->>DP: 执行部署流水线
    DP-->>U: 部署结果

---
name: scaffold
description: >
  代码脚手架生成器。根据指定类型和名称生成项目文件。
  支持类型: component, service, hook, util。
trigger: |
  用户提到"生成"、"创建"、"新建"并包含以下类型时触发：
  component、service、hook、util
  格式: /scaffold <type> <name>
---

~/.claude/skills/api-doc-generator/
├── SKILL.md
├── resources/
│   ├── openapi-skeleton.yaml
│   └── type-mapping.md
└── examples/
    └── sample-output.yaml

---
name: api-doc-generator
description: >
  从Express/FastAPI/NestJS路由代码自动生成OpenAPI 3.0规范文档。
  支持从JSDoc、Python type hints、TypeScript interface自动提取参数与响应类型。
  当用户提到生成API文档、OpenAPI、Swagger规范、接口文档时触发。
trigger: |
  触发场景：
  - 生成/更新OpenAPI文档或Swagger规范
  - 从代码提取API端点信息
  - API文档化
  排除：仅讨论API设计而不需要生成文档时不要触发。
allowed-tools:
  - Read
  - Write
  - Glob
  - Grep
  - Bash(npx swagger-cli validate *)
---

# API文档生成器

## 工作流程

### 第1步：识别框架
检测项目使用的后端框架：
- Express: 查找 `express` 依赖和 `app.get/post/put/delete` 调用
- FastAPI: 查找 `fastapi` 依赖和 `@app.get/post` 装饰器
- NestJS: 查找 `@nestjs/core` 依赖和 `@Controller` 装饰器

### 第2步：发现路由文件
根据框架使用Glob模式定位：
- Express: `**/routes/**/*.{js,ts}`, `**/router*.{js,ts}`
- FastAPI: `**/*.py`（过滤包含 `@router` 或 `@app` 的文件）
- NestJS: `**/*.controller.ts`

### 第3步：提取端点信息
对每个路由文件提取：
1. HTTP方法和路径（如 `GET /api/users/:id`）
2. 路径参数、查询参数、请求体
3. 认证/授权要求（从中间件推断）
4. 响应类型和状态码
5. JSDoc/TypeScript/Python中的描述文字

### 第4步：读取类型定义
使用Grep查找相关的interface/type/class定义：
- TypeScript: `interface User`, `type UserResponse`
- Python: `class User(BaseModel)`
将类型映射为OpenAPI schema。

### 第5步：生成OpenAPI规范
参考 `resources/openapi-skeleton.yaml` 生成基础结构。
参考 `examples/sample-output.yaml` 了解预期格式。

输出到 `docs/openapi.yaml`。如果文件已存在，增量合并而非覆盖。

### 第6步：验证
运行 `npx swagger-cli validate docs/openapi.yaml`。
如果验证失败，分析错误并修复。

## 输出规范
- OpenAPI版本: 3.0.3
- 所有端点必须有 `operationId`
- 所有响应必须有 `description`
- 复用类型放入 `components/schemas`
- 认证方案放入 `components/securitySchemes`

## 约束
- 只文档化实际存在的路由，不生成假设端点
- 无法推断类型时使用 `object` 并添加 `x-undocumented: true` 扩展字段
- 保持与项目现有OpenAPI文件的风格一致

openapi: "3.0.3"
info:
  title: ""        # 从package.json读取
  version: ""      # 从package.json读取
  description: ""

servers:
  - url: http://localhost:3000
    description: 开发环境

paths:
  # 自动生成的端点

components:
  schemas:
    # 自动生成的类型定义
  securitySchemes:
    # 自动生成的认证方案（如检测到）

# 创建目录
mkdir -p ~/.claude/skills/api-doc-generator/resources
mkdir -p ~/.claude/skills/api-doc-generator/examples

# 写入文件后测试
# 方式1：手动调用
# > /api-doc-generator 为我的项目生成API文档

# 方式2：自然语言触发
# > 帮我生成OpenAPI文档

# 方式3：在具体项目中测试
cd your-express-project
# > 分析路由代码，生成Swagger文档

mindmap
  root((Claude Code<br/>Skill生态))
    创建
      手动编写SKILL.md
      skill-creator Skill辅助生成
      Skill Factory批量生产
    测试
      手动场景测试
      skill-creator Evals
      A/B Benchmark
      Quality Analyzer
    分发
      Git仓库（项目内）
      Plugin Marketplace
      GitHub社区仓库
      npm包
    管理
      ~/.claude/skills/（全局）
      .claude/skills/（项目级）
      settings.json配置
      enabled/disabled控制