Claude Code Skill 开发实战：从零创建一个自定义 Skill

my-skill/
├── SKILL.md           ← 必需，包含元数据 + 指令
└── (可选资源)
    ├── scripts/       ← 可执行脚本
    ├── references/    ← 参考文档
    └── assets/        ← 模板、图标等资源

# 注册官方 Skill 市场
claude /plugin marketplace add anthropics/skills

# 安装 example-skills 插件（包含 skill-creator）
claude /plugin install example-skills@anthropic-agent-skills

---
name: template-skill
description: Replace with description of the skill and when Claude should use it.
---

# Insert instructions below

description: 如何构建一个简单的仪表盘。

description: |
  如何构建高质量的交互式仪表盘和数据可视化界面。
  当用户提到仪表盘、dashboard、数据可视化、监控面板、
  指标展示、metrics board，或者想要展示任何类型的结构化数据时，
  都应使用此 Skill，即使用户没有明确提到"仪表盘"这个词。

---
name: my-skill
description: 技能描述...
license: Apache-2.0           # 许可证
compatibility:                 # 兼容性说明
  tools: [Bash, Read, Write]   # 所需工具
  dependencies: [node>=18]     # 运行依赖
---

# 在项目根目录创建 Skill
mkdir -p .claude/skills/smart-commit

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

---
name: smart-commit
description: |
  智能生成符合 Conventional Commits 规范的 Git 提交信息。
  当用户需要提交代码、写 commit message、暂存文件、
  创建 git commit，或者提到"提交"、"commit"、"保存进度"时，
  都应使用此 Skill。即使用户只说了"提交一下"这样模糊的指令也应触发。
---

# Smart Commit

生成高质量、规范化的 Git 提交信息，遵循 Conventional Commits 标准。

## 工作流程

### 第一步：分析变更

1. 运行 `git status` 查看所有变更文件
2. 运行 `git diff --staged` 查看已暂存的变更
3. 运行 `git diff` 查看未暂存的变更
4. 运行 `git log --oneline -10` 了解最近的提交风格

### 第二步：分类变更

根据变更内容确定 commit 类型：

| 类型 | 说明 | 示例 |
|------|------|------|
| feat | 新功能 | 新增用户注册接口 |
| fix | Bug 修复 | 修复登录超时问题 |
| docs | 文档变更 | 更新 API 文档 |
| style | 格式调整（不影响逻辑） | 修正缩进、空格 |
| refactor | 重构（非新功能、非修复） | 提取公共方法 |
| perf | 性能优化 | 优化列表查询速度 |
| test | 测试相关 | 新增用户模块单元测试 |
| chore | 构建或辅助工具 | 升级依赖版本 |

### 第三步：生成提交信息

格式要求：

**示例 1：**
Input: 新增了用户登录的 JWT 认证功能，包含 token 签发和验证
Output: `feat(auth): implement JWT-based user authentication`

**示例 2：**
Input: 修复了当用户名为空时系统崩溃的问题
Output: `fix(user): handle empty username to prevent crash`

**示例 3：**
Input: 把 utils.js 里的重复代码提取成了独立函数
Output: `refactor(utils): extract shared helper functions`

### 第四步：确认与提交

1. 展示生成的 commit message 给用户确认
2. 用户确认后，执行 `git add`（只添加相关文件，不使用 `git add -A`）
3. 执行 `git commit`，使用 HEREDOC 格式传递 message

## 约束

- 绝不自动 push 到远程仓库
- 绝不提交 .env、credentials、secrets 等敏感文件
- 不使用 `--no-verify` 跳过 hooks
- 优先让用户确认后再执行 git 操作
- 如果有 pre-commit hook 失败，修复问题后创建新 commit，不使用 amend

mkdir -p .claude/skills/smart-commit/references

# Scope 命名指南

## 常用 scope 对照表

| 目录 | 推荐 scope |
|------|-----------|
| src/auth/ | auth |
| src/api/ | api |
| src/components/ | ui |
| src/utils/ | utils |
| tests/ | test |
| docs/ | docs |
| config/ | config |

## 多 scope 处理

当变更涉及多个模块时：
- 主要变更决定 scope
- 如果两个模块同等重要，用 `/` 分隔：`feat(auth/api): ...`
- 超过两个模块时省略 scope：`feat: ...`

## 参考
- 当不确定 scope 命名时，参考 `references/scopes-guide.md`

你: 帮我提交一下当前的代码

（Claude 应该触发 smart-commit Skill，分析变更并生成规范的 commit message）

{
  "skill_name": "smart-commit",
  "evals": [
    {
      "id": 1,
      "prompt": "帮我提交一下，我刚改了登录模块的 bug",
      "expected_output": "生成 fix(auth): ... 格式的 commit message",
      "files": [],
      "assertions": [
        {
          "text": "commit message 以 fix( 开头",
          "check": "output_matches",
          "pattern": "^fix\\("
        },
        {
          "text": "不包含敏感文件",
          "check": "output_not_contains",
          "pattern": "\\.env|credentials"
        }
      ]
    },
    {
      "id": 2,
      "prompt": "I added a new REST API endpoint for user registration",
      "expected_output": "生成 feat(api): ... 格式的 commit message",
      "files": []
    }
  ]
}

smart-commit/              ← Skill 目录
smart-commit-workspace/    ← 测试工作空间
├── evals/
│   └── evals.json
├── iteration-1/
│   ├── descriptive-name/
│   │   ├── eval_metadata.json
│   │   ├── with_skill/
│   │   │   ├── outputs/
│   │   │   └── timing.json
│   │   └── without_skill/
│   │       ├── outputs/
│   │       └── timing.json
│   └── grading.json
└── iteration-2/
    └── ...

cloud-deploy/
├── SKILL.md              ← 主入口，包含工作流和选择逻辑
└── references/
    ├── aws.md            ← AWS 部署细节
    ├── gcp.md            ← GCP 部署细节
    └── azure.md          ← Azure 部署细节

## 部署指南

根据用户指定的云平台，读取对应的参考文件：

- AWS → 读取 `references/aws.md`
- GCP → 读取 `references/gcp.md`
- Azure → 读取 `references/azure.md`

如果用户未指定平台，询问他们的偏好。

# 创建 marketplace
claude /plugin marketplace add your-org/your-skills-repo

# 团队成员安装
claude /plugin install your-skill-set@your-marketplace

your-skills-repo/
├── plugin.json           ← 插件配置
├── skills/
│   ├── smart-commit/
│   │   └── SKILL.md
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── ...
└── README.md

{
  "name": "team-workflow-skills",
  "description": "团队工作流 Skill 集合",
  "skills": [
    {
      "name": "smart-commit",
      "path": "skills/smart-commit"
    },
    {
      "name": "code-reviewer",
      "path": "skills/code-reviewer"
    }
  ]
}

python -m scripts.package_skill ./smart-commit/
# 输出: smart-commit.skill

ALWAYS 确保生成的 commit message 不超过 72 个字符。
NEVER 使用过去时态。

commit message 的首行应控制在 72 字符以内，因为 Git 默认截断超过此长度的信息。
使用祈使句（如 "add feature" 而非 "added feature"），与 Git 自身的 merge message 风格保持一致。

**示例：**
Input: 修复了当并发请求数超过 100 时连接池耗尽的问题
Output: fix(pool): prevent connection exhaustion under high concurrency

---
name: api-doc-generator
description: |
  从源代码自动生成 OpenAPI 3.0 规范文档。
  当用户需要生成 API 文档、创建 OpenAPI/Swagger 规范、
  从代码提取接口定义、编写 API 描述文件，
  或者提到"接口文档"、"API 文档"、"swagger"、"openapi"时使用。
  即使用户只说"帮我整理一下接口"也应触发此 Skill。
---

# API 文档生成器

从项目源代码中提取 API 端点信息，生成标准 OpenAPI 3.0 YAML/JSON 规范文件。

## 工作流程

### 第一步：项目分析

1. 确定项目使用的框架（Express/Fastify/Django/FastAPI/Spring Boot 等）
2. 识别路由定义文件的位置
3. 检查是否已存在 OpenAPI/Swagger 配置

运行以下命令定位路由文件：
- Express: 搜索 `app.get|app.post|router.get|router.post`
- FastAPI: 搜索 `@app.get|@app.post|@router.get`
- Spring: 搜索 `@GetMapping|@PostMapping|@RequestMapping`

### 第二步：端点提取

对每个路由端点，提取：

- HTTP 方法和路径
- 请求参数（query/path/body）
- 请求体 Schema
- 响应格式和状态码
- 认证要求
- 描述信息（从注释中提取）

### 第三步：生成 OpenAPI 文档

输出完整的 `openapi.yaml` 文件，结构如下：

**示例输出：**
```yaml
openapi: '3.0.3'
info:
  title: User Service API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: Paginated user list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'