Skills：扩展 AI 能力

目标：使用 Skills 扩展 Claude 的能力，创建自定义命令
预计时间：30 分钟
对应官方文档：Skills

什么是 Skills？

Skills 是 Claude Code 的插件系统，让你可以：

添加自定义斜杠命令（如 /deploy）
封装常用工作流
集成内部工具和 API

使用内置 Skills

Claude Code 自带一些常用 Skills：

> /skills list

Built-in skills:
  - git              Git 操作增强
  - github           GitHub 集成
  - web              网页搜索和抓取

启用 Skill

> /skills enable github

使用 Skill 命令

> /github create-pr "修复登录bug"

创建自定义 Skill

基本结构

在 .claude/skills/ 目录创建：

# .claude/skills/deploy.yaml
name: deploy
version: 1.0.0
description: 部署应用到生产环境
 
commands:
  - name: staging
    description: 部署到预发布环境
    prompt: |
      执行以下部署流程：
      1. 运行测试：pytest tests/ -x
      2. 构建 Docker 镜像：docker build -t app:staging .
      3. 推送到仓库：docker push registry/app:staging
      4. 更新 K8s：kubectl set image deployment/app app=registry/app:staging
      5. 等待就绪：kubectl rollout status deployment/app
      
      如果任何步骤失败，立即停止并报告错误。
 
  - name: production
    description: 部署到生产环境（需要确认）
    prompt: |
      ⚠️ 生产环境部署
      
      请先确认：
      - [ ] 所有测试通过
      - [ ] 已通知团队
      - [ ] 有回滚方案
      
      确认后执行：
      1. 打标签：git tag -a v$(date +%Y%m%d) -m "Release"
      2. 构建生产镜像
      3. 滚动更新（每次 25%）
      4. 监控 5 分钟

使用自定义 Skill

> /skills enable deploy
> /deploy staging

Skill 高级功能

带参数的 Skill

# .claude/skills/db.yaml
name: db
commands:
  - name: migrate
    description: 执行数据库迁移
    args:
      - name: env
        description: 环境
        default: development
        enum: [development, staging, production]
    prompt: |
      在 {{env}} 环境执行数据库迁移：
      
      1. 检查当前版本：alembic current
      2. 检查待执行迁移：alembic history --revrange current:head
      3. {{#if (eq env "production")}}
         ⚠️ 生产环境！先备份数据库
         {{/if}}
      4. 执行迁移：alembic upgrade head
      5. 验证：alembic current

使用：

> /db migrate --env production

条件逻辑

使用 Handlebars 模板语法：

prompt: |
  {{#if dry_run}}
  【模拟运行模式】以下操作不会实际执行：
  {{/if}}
  
  {{#each targets}}
  - 部署到 {{name}}: {{command}}
  {{/each}}

分享 Skills

导出 Skill

# 打包为 .zip
zip -r my-skills.zip .claude/skills/

安装他人分享的 Skill

> /skills install https://github.com/team/claude-skills/archive/main.zip

通过 Marketplace 分发

参考 Plugin Marketplaces，创建团队内部的 Skills 市场。

最佳实践

✅ 推荐	❌ 避免
命令名简短有意义	过长或容易混淆的名字
添加详细描述	没有文档的 Skill
包含错误处理	假设总是成功
支持 dry-run 模式	直接执行危险操作
版本控制 Skills	散落在各处

补充：Skill 架构详解与实战

Skill 执行流程与架构

高级 Skill 配置示例

示例 1：带预检查的生产部署 Skill（完整可运行配置）

创建 .claude/skills/deploy.yaml：

name: deploy
version: 2.0.0
description: 安全的生产环境部署流程，含预检查和回滚
 
commands:
  - name: staging
    description: 部署到预发布环境
    prompt: |
      ## 预发布环境部署
      
      1. 代码检查
         ```bash
         git diff --stat HEAD~1

确认本次部署的变更范围。

运行测试（任一失败则停止）
```
pytest tests/ -x -q
```

构建镜像

docker build -t registry/app:staging-$(git rev-parse --short HEAD) .

推送并部署

docker push registry/app:staging-$(git rev-parse --short HEAD)
kubectl set image deployment/app-staging app=registry/app:staging-$(git rev-parse --short HEAD) -n staging
kubectl rollout status deployment/app-staging -n staging --timeout=120s

健康检查

curl -sf https://staging.api.example.com/health || echo "部署可能异常，请检查"

如果步骤 2-4 任一命令返回非零退出码，立即停止并输出错误日志。

name: production description: 部署到生产环境（强制确认 + 灰度） args:
- name: canary_percent description: 灰度百分比 default: "10" enum: ["10", "25", "50", "100"] prompt: |
生产环境部署 —— 强制确认

⚠️ 生产环境操作！请确认以下检查项：
- staging 环境运行正常超过 30 分钟
- 已通知 #deployments 频道
- 数据库变更已 review（如有）
- 回滚命令已准备：kubectl rollout undo deployment/app-prod
用户确认后执行：
1. 打标签
```
git tag -a v$(date +%Y%m%d-%H%M) -m "Production deploy"
git push origin v$(date +%Y%m%d-%H%M)
```
2. 构建生产镜像
```
docker build -t registry/app:prod-$(git rev-parse --short HEAD) .
docker push registry/app:prod-$(git rev-parse --short HEAD)
```
3. 灰度发布（{{canary_percent}}%）
```
kubectl set image deployment/app-prod-canary app=registry/app:prod-$(git rev-parse --short HEAD) -n production
kubectl scale deployment/app-prod-canary --replicas=2 -n production
```
4. 监控 5 分钟检查错误率是否上升，如有异常立即执行回滚。
5. 全量发布（仅当 canary_percent=100 时）
```
kubectl set image deployment/app-prod app=registry/app:prod-$(git rev-parse --short HEAD) -n production
```


#### 示例 2：数据库安全迁移 Skill（含备份检查）

创建 `.claude/skills/db.yaml`：

```yaml
name: db
version: 1.1.0
description: 安全的数据库迁移流程

commands:
  - name: migrate
    description: 执行数据库迁移
    args:
      - name: env
        description: 目标环境
        default: development
        enum: [development, staging, production]
      - name: dry_run
        description: 仅预览不执行
        default: "false"
        enum: ["true", "false"]
    prompt: |
      目标环境：{{env}}
      
      {{#if (eq dry_run "true")}}
      【模拟运行模式】以下操作仅打印命令，不会实际执行！
      {{/if}}
      
      1. 查看当前数据库版本
         ```bash
         alembic current

查看待执行迁移
```
alembic history --revrange current:head
```

{{#if (eq env "production")}} 3. 【生产环境】确认最近一次备份时间

psql $DATABASE_URL -c "SELECT pg_backup_start_time();" || echo "请确认手动备份已完成"

{{#if (eq dry_run "true")}}预览{{else}}执行{{/if}}迁移

{{#if (eq dry_run "true")}}alembic upgrade head --sql{{else}}alembic upgrade head{{/if}}

验证版本
```
alembic current
```

{{#if (eq env "production")}} 6. 生产环境额外检查

检查应用错误率是否上升
确认核心业务查询正常 {{/if}}


#### 示例 3：调用本地脚本的 Skill（集成现有工具）

创建 `.claude/skills/local.yaml`：

```yaml
name: local
version: 1.0.0
description: 集成团队已有的本地脚本

commands:
  - name: lint-fix
    description: 运行团队自定义的 lint 修复脚本
    prompt: |
      执行团队 lint 修复流程：
      
      1. 先运行检查，查看问题数量
         ```bash
         ./scripts/lint-check.sh

自动修复可修复的问题
```
./scripts/lint-fix.sh
```
再次检查，确认无错误（警告可接受）
```
./scripts/lint-check.sh
```
如果仍有错误，列出具体文件和位置，请用户决定手动修复或忽略。

name: generate-client description: 根据 OpenAPI 生成前端客户端代码 args:
- name: spec description: OpenAPI 文件路径 default: "openapi.json" prompt: | 为前端生成 API 客户端：
1. 验证 OpenAPI 规范语法
```
npx @apidevtools/swagger-cli validate {{spec}}
```
2. 生成 TypeScript 客户端
```
npx openapi-typescript {{spec}} --output src/types/api.ts
npx openapi-fetch --input {{spec}} --output src/lib/api-client
```
3. 运行类型检查，确保生成代码无类型错误
```
npx tsc --noEmit
```


---

### 实战场景

#### 场景一：一键部署（完整 CI/CD Skill）

**背景**：团队每天需要多次部署到 staging 环境验证功能，手动执行构建、推送、更新 K8s 容易出错，且不同成员操作步骤不一致。

**步骤**：
1. 运维工程师编写 `deploy` Skill，固化 staging 部署的 5 个步骤
2. 开发完成功能后，在 Claude Code 中执行 `/deploy staging`
3. Claude 自动运行测试、构建镜像、更新 K8s、等待就绪
4. 如果测试失败，Claude 立即停止并输出失败用例

**结果**：
- 部署时间从平均 8 分钟缩短到 3 分钟（且开发者可同时做其他事）
- 人为失误（如忘记打标签、推送错镜像）降至零
- 新成员入职第一天即可独立部署，无需背诵操作手册
- 生产环境因 Skill 强制确认清单，再也没出现过"忘记通知团队"的情况

#### 场景二：数据库安全迁移（带备份检查）

**背景**：某次生产环境数据库迁移因未备份导致数据异常，回滚耗时 4 小时。团队需要一种强制安全流程，确保不会再遗漏备份。

**步骤**：
1. DBA 编写 `db migrate` Skill，为 production 环境增加强制备份确认步骤
2. 开发者执行 `/db migrate --env production` 时，Claude 先检查备份状态
3. Skill 使用 Handlebars 条件语法：生产环境才显示备份检查，开发环境跳过
4. 迁移后自动验证当前版本，并提示检查业务错误率

**结果**：
- 生产迁移的备份确认从"口头提醒"变为"流程阻塞点"，未确认无法继续
- 开发环境保留快速迁移能力，不受多余步骤干扰
- 通过 `--dry_run true` 参数，可在正式执行前预览 SQL，提前发现危险操作
- 团队将 Skill 纳入上线 Checklist，审计时可直接展示标准化流程记录

---

## 下一步

→ [05. MCP：连接外部工具](./05-MCP.md)