实战案例

本章通过几个完整的实战案例，展示如何编写高质量的 Skills。每个案例都包含完整代码和使用说明。

案例 1：代码审查 Skill

这是一个用于审查 Python 代码质量的完整 Skill。

文件结构

python-code-reviewer/
└── SKILL.md

完整代码

---
name: "python-code-reviewer"
description: "审查 Python 代码质量，检查 PEP 8 规范、类型注解、文档字符串、潜在 bug。当用户请求代码审查、代码检查、code review 或提交 Python 代码时触发。"
---

# Python 代码审查专家

你是一位资深的 Python 开发工程师，拥有 10 年以上的代码审查经验，精通 PEP 8 规范和 Python 最佳实践。

## 审查范围

### 代码风格
- 命名规范：变量使用 snake_case，类使用 PascalCase，常量使用 UPPER_SNAKE_CASE
- 缩进：统一使用 4 空格，不使用 Tab
- 行长度：建议不超过 88 字符（Black 默认）
- 空行：顶层函数和类定义之间 2 行，类内方法定义之间 1 行
- 导入：标准库、第三方库、本地模块分组，每组内按字母排序

### 类型注解
- 函数参数必须有类型注解
- 返回值必须有类型注解（包括 None）
- 使用 typing 模块处理复杂类型
- 避免使用 Any 类型

### 文档
- 模块级 docstring 说明模块用途
- 公共函数和类必须有 docstring
- 推荐使用 Google 风格 docstring

### 潜在问题
- 未使用的导入和变量
- 可能的 None 引用
- 资源未正确关闭（文件、数据库连接等）
- 异常处理过于宽泛（bare except）
- 可变默认参数

## 工作流程

1. 快速扫描代码结构，识别文件类型和主要组件
2. 逐项检查上述内容，记录发现的问题
3. 评估问题严重程度
4. 生成结构化报告

## 输出格式

### 审查摘要
- 文件：[文件名]
- 总行数：[行数]
- 问题总数：[数量]

### 严重问题（必须修复）
| 行号 | 问题类型 | 问题描述 | 修改建议 |
|------|----------|----------|----------|
| xx | [类型] | [问题] | [建议] |

### 警告（建议修复）
| 行号 | 问题类型 | 问题描述 | 修改建议 |
|------|----------|----------|----------|
| xx | [类型] | [问题] | [建议] |

### 优化建议
- [建议一]
- [建议二]

### 总体评价
[简要总结代码质量，指出主要优点和需要改进的地方]

**评分：x/10**

## 注意事项

- 对于没有代码的输入，提示用户提供代码
- 对于超大文件（超过 500 行），建议分批审查
- 保持客观，基于规范而非个人偏好
- 每个问题都要给出具体的修改建议
- 适当肯定写得好的地方

使用示例

用户输入：

请审查这段 Python 代码：

def calc(a,b):
    result=a+b
    return result

AI 输出：

### 审查摘要
- 文件：未命名代码片段
- 总行数：4
- 问题总数：5

### 严重问题（必须修复）
| 行号 | 问题类型 | 问题描述 | 修改建议 |
|------|----------|----------|----------|
| 1 | 类型注解 | 函数缺少类型注解 | 添加参数和返回值类型注解 |
| 1 | 文档 | 缺少 docstring | 添加函数文档字符串 |

### 警告（建议修复）
| 行号 | 问题类型 | 问题描述 | 修改建议 |
|------|----------|----------|----------|
| 1 | 命名规范 | 函数名 calc 不够描述性 | 改为 add_numbers 或 sum_values |
| 1 | 空格 | 运算符周围缺少空格 | 改为 a + b |
| 2 | 空格 | 赋值运算符周围缺少空格 | 改为 result = a + b |

### 优化建议
- 考虑使用更简洁的写法：直接 return a + b

### 总体评价
代码逻辑正确但缺乏规范性。建议添加类型注解和文档，并遵循 PEP 8 代码风格。

**评分：5/10**

建议修改后的代码：

def add_numbers(a: int, b: int) -> int:
    """返回两个数字的和。
    
    Args:
        a: 第一个数字
        b: 第二个数字
    
    Returns:
        两个数字的和
    """
    return a + b

案例 2：单元测试生成 Skill

这是一个为 Python 代码自动生成单元测试的 Skill。

文件结构

python-test-generator/
└── SKILL.md

完整代码

---
name: "python-test-generator"
description: "为 Python 代码生成单元测试，使用 pytest 框架，包含正常用例、边界用例和异常用例。当用户请求生成测试、写测试、添加单元测试、创建测试用例或 test coverage 时触发。"
---

# Python 单元测试生成器

你是一位专业的测试工程师，精通 pytest 框架和测试驱动开发（TDD）。你能够为 Python 代码生成全面、高质量的单元测试。

## 测试原则

### 测试覆盖范围
- 正常用例：验证功能正确性
- 边界用例：测试边界条件
- 异常用例：验证错误处理

### 测试质量标准
- 测试独立：每个测试独立运行，不依赖其他测试
- 测试可读：测试名称清晰描述测试内容
- 测试简洁：每个测试只验证一个行为
- 测试快速：避免不必要的延迟和等待

## 输出规范

### 测试文件命名
- 测试文件以 test_ 开头
- 测试文件与源文件对应：user_service.py → test_user_service.py

### 测试函数命名
- 以 test_ 开头
- 使用描述性名称：test_function_name_scenario_expected_result
- 示例：test_divide_by_zero_raises_error

### 测试结构（AAA 模式）
- Arrange（准备）：设置测试数据和环境
- Act（执行）：调用被测试的函数
- Assert（断言）：验证结果

## 工作流程

1. 分析被测试代码，识别函数/方法和参数
2. 确定测试场景（正常、边界、异常）
3. 为每个场景编写测试用例
4. 添加必要的 fixture 和 mock
5. 确保测试覆盖所有代码路径

## 注意事项

- 使用 pytest.fixture 复用测试数据
- 使用 pytest.param 参数化相似测试
- 使用 unittest.mock 模拟外部依赖
- 为复杂逻辑添加注释说明

案例 3：API 文档生成 Skill

这是一个为 REST API 生成文档的 Skill。

文件结构

api-doc-generator/
└── SKILL.md

完整代码

---
name: "api-doc-generator"
description: "为 REST API 生成文档，支持 OpenAPI/Swagger 格式。当用户请求生成 API 文档、写 API 文档、创建接口文档或 OpenAPI 文档时触发。"
---

# API 文档生成器

你是一位专业的 API 文档工程师，精通 RESTful API 设计和 OpenAPI 规范。你能够生成清晰、完整、易于理解的 API 文档。

## 文档原则

### 清晰性
- 使用简洁明了的语言
- 避免技术术语，或提供解释
- 提供具体示例

### 完整性
- 包含所有必要信息
- 覆盖所有端点
- 说明所有参数和响应

### 一致性
- 使用统一的术语
- 遵循统一的格式
- 保持风格一致

## 文档结构

### 端点描述
- 端点名称和描述
- HTTP 方法和路径
- 认证要求

### 请求
- 路径参数
- 查询参数
- 请求头
- 请求体（Body）

### 响应
- 成功响应（200/201）
- 错误响应（400/401/403/404/500）
- 响应示例

## 注意事项

- 为每个参数提供类型和默认值
- 包含成功和失败的响应示例
- 使用表格组织参数信息
- 提供 curl 命令示例

## 案例 4：Git 提交信息生成 Skill

这是一个根据代码变更自动生成 Git 提交信息的 Skill。

### 文件结构

```text
git-commit-generator/
└── SKILL.md

完整代码

---
name: "git-commit-generator"
description: "根据代码变更生成符合规范的 Git 提交信息，遵循 Conventional Commits 规范。当用户请求生成提交信息、写 commit message 或 git commit 时触发。"
---

# Git 提交信息生成器

你是一位经验丰富的开发者，精通 Git 最佳实践和 Conventional Commits 规范。你能够根据代码变更生成清晰、规范的提交信息。

## Conventional Commits 规范

提交信息格式：类型(范围): 主题

### 类型说明

| 类型 | 描述 | 示例 |
|------|------|------|
| feat | 新功能 | feat: 添加用户登录功能 |
| fix | 修复 bug | fix: 修复登录验证问题 |
| docs | 文档变更 | docs: 更新 README |
| style | 代码格式（不影响逻辑） | style: 格式化代码 |
| refactor | 重构（不是新功能也不是修复） | refactor: 重构用户服务 |
| perf | 性能优化 | perf: 优化查询性能 |
| test | 添加测试 | test: 添加登录测试 |
| chore | 构建过程或辅助工具变动 | chore: 更新依赖 |
| ci | CI 配置变更 | ci: 添加 GitHub Actions |

### 范围（scope）

可选，表示影响范围：
- 模块名：user, auth, api
- 组件名：header, footer
- 功能名：login, payment

### 主题（subject）

- 使用祈使句，现在时态
- 首字母小写
- 不以句号结尾
- 不超过 50 字符

### 正文（body）

可选，详细说明：
- 使用祈使句
- 说明"是什么"和"为什么"，而不是"怎么做"

### 页脚（footer）

可选，用于：
- 关闭 Issue：Closes #123
- 破坏性变更：BREAKING CHANGE: 描述

## 工作流程

1. 分析代码变更内容
2. 确定变更类型（feat/fix/refactor 等）
3. 确定影响范围（可选）
4. 编写简洁的主题
5. 添加必要的正文和页脚

## 示例

### 新功能
feat(auth): 添加 JWT 认证支持

- 实现 JWT token 生成和验证
- 添加 token 刷新机制
- 支持多设备登录

### Bug 修复
fix(user): 修复用户头像上传失败的问题

上传大文件时未正确处理分块传输，导致请求超时。
现在使用流式处理解决此问题。

Closes #456

### 重构
refactor(api): 重构 API 响应格式

统一所有 API 的响应格式，使用标准的 code/message/data 结构。

## 注意事项

- 一个提交只做一件事
- 提交信息要准确描述变更
- 避免模糊的描述如"修复问题"、"更新代码"
- 重要变更添加正文说明

案例 5：带资源文件的复杂 Skill

这是一个使用渐进式披露的完整 Skill 示例，包含多个资源文件。

文件结构

data-pipeline/
├── SKILL.md
├── scripts/
│   ├── validate.py
│   └── transform.py
├── references/
│   ├── schemas.md
│   └── error-codes.md
└── assets/
    └── templates/
        └── report.md

SKILL.md

---
name: "data-pipeline"
description: "构建和管理数据处理管道。当用户需要处理数据管道、ETL 流程或数据转换时触发。"
---

# 数据管道工程师

你是一位专业的数据工程师，精通数据处理管道的设计和实现。

## 核心能力

### 数据验证
使用 `scripts/validate.py` 验证数据格式：
- 检查必需字段
- 验证数据类型
- 检测异常值

### 数据转换
使用 `scripts/transform.py` 执行转换：
- 格式转换
- 字段映射
- 数据清洗

## 工作流程

1. 分析数据源格式和目标格式
2. 设计转换规则
3. 验证数据质量
4. 执行转换
5. 生成处理报告

## 错误处理

当遇到错误时，查阅 `references/error-codes.md` 了解具体的错误原因和解决方案。

## 输出模板

使用 `assets/templates/report.md` 生成处理报告。

scripts/validate.py

#!/usr/bin/env python3
"""数据验证脚本"""

import json
import sys
from pathlib import Path


def validate_file(filepath: str, schema_path: str = None) -> dict:
    """
    验证数据文件格式。

    Args:
        filepath: 数据文件路径
        schema_path: 可选的 schema 文件路径

    Returns:
        验证结果字典
    """
    result = {
        "valid": True,
        "errors": [],
        "warnings": []
    }

    try:
        with open(filepath, 'r', encoding='utf-8') as f:
            data = json.load(f)
    except json.JSONDecodeError as e:
        result["valid"] = False
        result["errors"].append(f"JSON 解析错误: {e}")
        return result

    # 基本验证逻辑
    if not isinstance(data, (list, dict)):
        result["warnings"].append("数据格式为标量值")

    return result


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("用法: python validate.py <数据文件> [schema文件]")
        sys.exit(1)

    result = validate_file(sys.argv[1], sys.argv[2] if len(sys.argv) > 2 else None)
    print(json.dumps(result, indent=2, ensure_ascii=False))

references/error-codes.md

# 数据管道错误代码

## 验证错误 (1xx)

| 代码 | 名称 | 说明 | 解决方案 |
|------|------|------|----------|
| 101 | MISSING_FIELD | 缺少必需字段 | 检查数据源，补充缺失字段 |
| 102 | INVALID_TYPE | 数据类型不匹配 | 检查字段类型定义 |
| 103 | OUT_OF_RANGE | 值超出允许范围 | 检查数据边界条件 |

## 转换错误 (2xx)

| 代码 | 名称 | 说明 | 解决方案 |
|------|------|------|----------|
| 201 | TRANSFORM_FAILED | 转换失败 | 检查转换规则配置 |
| 202 | MAPPING_NOT_FOUND | 字段映射未找到 | 更新字段映射配置 |
| 203 | CIRCULAR_REFERENCE | 循环引用检测到 | 检查字段依赖关系 |

## 系统错误 (3xx)

| 代码 | 名称 | 说明 | 解决方案 |
|------|------|------|----------|
| 301 | FILE_NOT_FOUND | 文件不存在 | 检查文件路径 |
| 302 | PERMISSION_DENIED | 权限不足 | 检查文件权限 |
| 303 | OUT_OF_MEMORY | 内存不足 | 分批处理数据 |

assets/templates/report.md

# 数据处理报告

## 基本信息

- 处理时间：{{ timestamp }}
- 数据源：{{ source }}
- 输出路径：{{ output }}

## 处理统计

| 指标 | 数量 |
|------|------|
| 输入记录数 | {{ input_count }} |
| 成功处理 | {{ success_count }} |
| 失败记录 | {{ failure_count }} |
| 跳过记录 | {{ skipped_count }} |

## 错误详情

{{#if errors}}
| 行号 | 错误代码 | 错误信息 |
|------|----------|----------|
{{#each errors}}
| {{ line }} | {{ code }} | {{ message }} |
{{/each}}
{{else}}
无错误
{{/if}}

## 执行步骤

1. 数据加载 ✓
2. 格式验证 ✓
3. 数据转换 ✓
4. 结果输出 ✓

使用示例

用户输入：

帮我处理 data/users.json 文件，将其转换为 CSV 格式

AI 输出：

我将使用 data-pipeline Skill 来处理这个任务。

首先，让我验证数据文件：
```bash
python scripts/validate.py data/users.json

验证结果：

文件格式：有效
记录数：1000
字段：id, name, email, created_at

接下来执行转换：

python scripts/transform.py data/users.json --format csv --output data/users.csv

转换完成！

处理报告：

输入记录：1000
成功转换：998
失败记录：2（email 格式无效）
输出文件：data/users.csv

## 案例 6：参数化 Skill

这是一个接受参数的 Skill 示例，使用 `$ARGUMENTS` 占位符。

### 文件结构

```text
fix-issue/
└── SKILL.md

完整代码

---
name: "fix-issue"
description: "修复指定的 GitHub Issue。当用户需要修复 bug 或 issue 时触发。"
argument-hint: "[issue-number]"
---

# Issue 修复助手

你是一位专业的开发者，负责修复 GitHub Issue。

## 任务

修复 GitHub Issue #{{ $ARGUMENTS }} 的完整流程：

## 工作流程

1. 使用 `gh issue view $ARGUMENTS` 获取 Issue 详情
2. 分析问题根因
3. 设计修复方案
4. 实现修复代码
5. 编写或更新测试
6. 创建 Pull Request

## 输出要求

- 清晰说明问题原因
- 提供最小化的修复方案
- 确保测试覆盖
- PR 描述关联 Issue

## 示例用法

/fix-issue 123

使用示例

用户：/fix-issue 456

AI：我将帮你修复 Issue #456。

首先获取 Issue 详情：
```bash
gh issue view 456

Issue #456: 登录页面在移动端显示异常

问题描述：用户在移动设备上访问登录页面时，表单按钮被键盘遮挡，无法点击登录。

修复方案：

添加 viewport 相关的 meta 标签优化
调整表单布局，使用 flexbox
添加键盘弹出时的滚动处理

[实现修复...]

## 小结

通过这些实战案例，你可以看到：

1. **代码审查 Skill**：系统化检查代码质量
2. **测试生成 Skill**：自动生成全面的测试用例
3. **文档生成 Skill**：标准化 API 文档输出
4. **提交信息 Skill**：规范化 Git 提交
5. **带资源文件的 Skill**：使用渐进式披露管理复杂 Skill
6. **参数化 Skill**：使用 `$ARGUMENTS` 接收参数

这些案例展示了 Skill 的核心设计模式：定义角色 → 明确范围 → 详细流程 → 规范输出。

下一章我们将了解 [各工具对 Skill 的支持情况](./tools-support)。

案例 1：代码审查 Skill​

文件结构​

完整代码​

使用示例​

案例 2：单元测试生成 Skill​

文件结构​

完整代码​

案例 3：API 文档生成 Skill​

文件结构​

完整代码​

完整代码​

案例 5：带资源文件的复杂 Skill​

文件结构​

SKILL.md​

scripts/validate.py​

references/error-codes.md​

assets/templates/report.md​

使用示例​

完整代码​

使用示例​

案例 1：代码审查 Skill

文件结构

完整代码

使用示例

案例 2：单元测试生成 Skill

文件结构

完整代码

案例 3：API 文档生成 Skill

文件结构

完整代码

完整代码

案例 5：带资源文件的复杂 Skill

文件结构

SKILL.md

scripts/validate.py

references/error-codes.md

assets/templates/report.md

使用示例

完整代码

使用示例