Claude Code Skills 开发实战：从零创建可复用的自定义 Skill

你: /deploy
Claude: 使用 vercel-deploy skill 部署到 Vercel...
        ✓ 检测到 Next.js 项目
        ✓ 正在打包...
        ✓ 部署成功！
        Preview URL: https://my-app-abc123.vercel.app

my-skill/
├── SKILL.md              # 核心：Skill 定义文件（必需）
├── scripts/              # 可执行脚本
│   ├── deploy.sh
│   ├── fetch_data.py
│   └── utils/
│       └── helpers.sh
├── references/           # 参考文档（被 Skill 引用时自动加载到上下文）
│   ├── api-spec.md
│   ├── style-guide.md
│   └── templates/
│       └── config.yaml
└── assets/               # 静态资源
    ├── icons/
    └── examples/

---
name: my-deploy-tool
description: |
  一键部署应用到云平台。支持 Vercel、Netlify、Cloudflare Pages。
  触发场景：(1) 用户说"部署"、"上线"、"发布" (2) 用户要求部署到特定平台
  (3) 用户说 /my-deploy-tool
  即使用户没有明确提到此技能名称，只要涉及部署操作，都应触发此技能。
metadata:
  short-description: 一键部署应用到云平台
---

# ❌ 模糊——Claude 可能不知道何时该用
description: "部署工具"

# ✅ 精确——Claude 知道在什么场景下激活
description: |
  一键部署应用到 Vercel。触发场景：(1) 用户说"部署"、"deploy"、"上线"
  (2) 用户想获取预览 URL (3) 用户说 /vercel-deploy

# Skill 标题

简短概述此 Skill 做什么。

## 前提条件

- 列出执行前需要检查的环境和依赖

## 工作流程

### Step 1: 检查环境
- 具体操作指令
- 命令示例

### Step 2: 执行核心逻辑
- 分步骤的操作说明

### Step 3: 处理输出
- 如何呈现结果

## 注意事项

- 错误处理策略
- 兼容性说明

## 故障排除

| 问题 | 解决方案 |
|------|---------|
| ... | ... |

# 全局 Skill 目录
mkdir -p ~/.claude/skills/code-review-helper/{scripts,references}

---
name: code-review-helper
description: |
  自动化代码审查工具。分析 Git 变更，生成结构化审查报告，涵盖安全漏洞、
  性能问题、代码风格、架构建议。
  触发场景：(1) 用户说"审查代码"、"review"、"代码检查"、"review PR"
  (2) 用户想在提交前检查代码质量 (3) 用户说 /code-review-helper
  (4) 用户完成了功能开发，请求代码审查
  即使用户没有明确提到此技能名称，只要涉及代码审查和质量检查，都应触发此技能。
metadata:
  short-description: 自动化代码审查与质量分析
---

# Code Review Helper

对当前分支的 Git 变更进行结构化代码审查，输出安全、性能、架构多维度分析报告。

## 工作流程

### Step 1: 确定审查范围

首先确认当前分支和变更文件：

```bash
git branch --show-current
git diff --name-status main...HEAD
git diff --stat main...HEAD

# 获取完整 diff（排除二进制文件和 lock 文件）
git diff main...HEAD -- ':!*.lock' ':!*.binary' ':!package-lock.json'

## 代码审查报告

**分支**: `branch-name`
**变更**: X 个文件, +Y/-Z 行
**审查结果**: 🟢 通过 / 🟡 建议修改 / 🔴 必须修改

### 🔴 必须修改 (N 项)

| # | 文件 | 行号 | 问题 | 严重性 |
|---|------|------|------|--------|
| 1 | src/api.ts | L42 | SQL 拼接导致注入风险 | Critical |

### 🟡 建议修改 (N 项)

| # | 文件 | 行号 | 建议 | 类别 |
|---|------|------|------|------|
| 1 | src/utils.ts | L15 | 可用 Map 替代 Object 查找 | Performance |

### 💡 架构建议 (N 项)

- 建议 1
- 建议 2

### ✅ 亮点

- 良好的实践 1
- 良好的实践 2

### Step 3: 创建参考文件

`references/review-checklist.md`：

```markdown
# 代码审查检查清单

## 安全检查项

- [ ] 输入验证：所有外部输入是否经过验证和清洗？
- [ ] SQL 参数化：是否使用参数化查询而非字符串拼接？
- [ ] XSS 防护：用户输入在渲染前是否转义？
- [ ] 认证授权：API 端点是否有适当的权限检查？
- [ ] 敏感数据：密码、密钥是否使用环境变量或密钥管理服务？
- [ ] CSRF 防护：表单提交是否有 CSRF token？
- [ ] 文件上传：上传文件类型和大小是否有限制？

## 性能检查项

- [ ] 数据库查询：是否有 N+1 查询？
- [ ] 缓存：热点数据是否有缓存策略？
- [ ] 异步处理：耗时操作是否使用异步？
- [ ] 分页：列表查询是否有分页？
- [ ] 内存管理：大对象是否及时释放？

## 代码质量检查项

- [ ] 单一职责：函数是否只做一件事？
- [ ] 命名：变量/函数名是否清晰表达意图？
- [ ] 复杂度：函数是否过长或嵌套过深？
- [ ] 错误处理：异常是否被正确捕获和处理？
- [ ] 类型安全：Typeany 类型是否被滥用？

## 架构检查项

- [ ] 分层：是否遵循项目的分层架构？
- [ ] 依赖方向：依赖是否指向正确的方向？
- [ ] 接口抽象：是否通过接口解耦？
- [ ] 循环依赖：模块间是否存在循环依赖？

# 确认文件结构正确
ls -la ~/.claude/skills/code-review-helper/
ls -la ~/.claude/skills/code-review-helper/references/

# 输出应显示：
# SKILL.md
# references/
# references/review-checklist.md
# scripts/

cd your-project
claude

/review
审查一下我的代码
帮我 review 这个分支

# Level 1: 基础——依赖名称匹配
description: "代码审查工具"

# Level 2: 标准——列举关键词
description: |
  代码审查工具。触发场景：用户说"review"、"代码审查"、"review PR"

# Level 3: 精确——定义完整语义匹配
description: |
  自动化代码审查工具。分析 Git 变更，生成安全/性能/架构多维报告。
  触发场景：
  (1) 用户说"审查代码"、"review"、"代码检查"、"review PR"
  (2) 用户想在提交前检查代码质量
  (3) 用户说 /code-review-helper
  (4) 用户完成了功能开发，请求代码审查
  即使用户没有明确提到此技能名称，只要涉及代码审查和质量检查，都应触发此技能。

# ❌ 过于宽泛——任何编码任务都可能触发
description: |
  帮助用户写代码。触发场景：(1) 用户写代码 (2) 用户打开编辑器

# ✅ 聚焦特定工作流
description: |
  生成 Express.js REST API 脚手架。触发场景：
  (1) 用户说"创建 API"、"新建接口"、"scaffold API"
  (2) 用户需要 Express.js 项目初始化

## 执行审查

按照 references/review-checklist.md 中的检查清单逐项审查。
- 如果是前端项目，额外参考 references/frontend-rules.md
- 如果是后端 API 项目，额外参考 references/api-patterns.md

## Step 2: 选择模板

根据项目类型读取对应模板：
- React 项目 → references/templates/react-component.md
- Vue 项目 → references/templates/vue-component.md
- 纯 HTML → references/templates/vanilla-html.md

3gpp-5g-specs/
├── SKILL.md
└── references/
    ├── 23002-i00.md    # 3GPP TS 23.002 网络架构
    ├── 23502-i00.md    # 3GPP TS 23.502 5G流程
    ├── 23501-i00.md    # 3GPP TS 23.501 5G系统
    └── ...（1300+ 规范文档）

# SKILL.md 中的指令示例

## 部署

执行部署脚本：

```bash
bash scripts/deploy.sh [path]

**脚本设计最佳实践**：

1. **脚本应自包含**——不依赖外部环境变量，所需的参数通过命令行传入
2. **提供清晰的输出**——Claude 需要解析脚本输出来决定下一步操作
3. **结构化输出优先**——JSON 输出比纯文本更易解析

```bash
# ✅ 好的脚本输出——结构化且有状态
#!/bin/bash
echo '{"status":"success","url":"https://example.com","id":"abc123"}'

# ❌ 差的脚本输出——难以解析
#!/bin/bash
echo "It worked! Your site is live at https://example.com"

# 1. 确认文件结构
find ~/.claude/skills/your-skill -type f

# 2. 验证 YAML frontmatter 语法
# 在 Claude Code 中启动新会话，检查 Skill 是否出现在可用列表
claude
# 输入: /your-skill-name

# 3. 测试触发词
# 在 Claude Code 中尝试不同的触发表达
"帮我审查代码"   → 应触发 code-review-helper
"检查一下代码质量" → 应触发 code-review-helper
"审查 PR"       → 应触发 code-review-helper

创建 Skill → 测试触发 → 观察行为 → 调整指令 → 再次测试

## 注意事项

- **不要**修改未提及的文件
- **不要**自动执行 git commit（除非用户明确要求）
- **不要**跳过错误检查步骤

# 1. 初始化 Skill 仓库
cd ~/.claude/skills
git init
git remote add origin [email protected]:your-org/team-skills.git

# 2. 团队成员克隆
git clone [email protected]:your-org/team-skills.git ~/.claude/skills

# 3. 日常同步（可以做成 Skill！）
cd ~/.claude/skills && git pull

# 将共享 Skills 作为 submodule 嵌入项目
git submodule add [email protected]:your-org/team-skills.git .claude/skills

my-plugin/
├── plugin.json            # 插件清单（必需）
├── skills/
│   └── my-skill/
│       └── SKILL.md
├── agents/                # 可选：子代理定义
│   └── my-agent.md
├── commands/              # 可选：自定义命令
├── hooks/                 # 可选：生命周期钩子
└── README.md

{
  "name": "my-team-tools",
  "version": "1.0.0",
  "description": "团队共享的开发工具集",
  "author": "your-name",
  "skills": ["skills/my-skill"],
  "marketplace": {
    "source": "git",
    "url": "https://github.com/your-org/my-plugin"
  }
}

{
  "name": "@your-scope/claude-plugin-my-tools",
  "version": "1.0.0",
  "description": "Claude Code plugin for ...",
  "main": "plugin.json",
  "files": ["skills/**", "scripts/**", "references/**", "plugin.json"]
}

api-docs-generator/
├── SKILL.md
├── scripts/
│   └── parse-openapi.py
└── references/
    └── output-template.md

---
name: api-docs-generator
description: |
  从 OpenAPI/Swagger 规范文件自动生成 API 文档和 TypeScript 接口定义。
  触发场景：(1) 用户说"生成API文档"、"解析Swagger"、"OpenAPI文档"
  (2) 用户提供了 openapi.yaml/swagger.json 文件
  (3) 用户想从 API 规范生成代码 (4) 用户说 /api-docs-generator
metadata:
  short-description: OpenAPI/Swagger 文档和代码生成
---

# API Docs Generator

从 OpenAPI 3.x / Swagger 2.x 规范文件生成结构化文档和 TypeScript 类型定义。

## Step 1: 定位规范文件

在项目根目录搜索规范文件：

```bash
find . -maxdepth 3 -type f \( -name "openapi.yaml" -o -name "openapi.yml" -o -name "swagger.yaml" -o -name "swagger.json" -o -name "openapi.json" \) 2>/dev/null

// 从 OpenAPI schema:
//   User:
//     type: object
//     properties:
//       id: { type: string, format: uuid }
//       name: { type: string }
//       email: { type: string, format: email }

// 生成:
export interface User {
  id: string;
  name: string;
  email: string;
}

### references/output-template.md

```markdown
# API 文档输出模板

## 文档头部

```markdown
# {api_title} API 文档

> 版本: {version} | Base URL: {server_url}

## 认证

{auth_type}: {auth_description}

---

## 端点总览

| 方法 | 路径 | 描述 | 标签 |
|------|------|------|------|
| GET | /users | 获取用户列表 | Users |
| POST | /users | 创建用户 | Users |

### {METHOD} {path}

{description}

**请求参数**

| 参数 | 位置 | 类型 | 必需 | 描述 |
|------|------|------|------|------|
| id | path | string | 是 | 用户ID |

**请求体**

```json
{
  "name": "string",
  "email": "string"
}