跳到主要内容

实战案例

本章通过几个完整的实战案例，展示如何编写高质量的 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 结构。

## 注意事项

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

小结​

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

  1. 代码审查 Skill：系统化检查代码质量
  2. 测试生成 Skill：自动生成全面的测试用例
  3. 文档生成 Skill：标准化 API 文档输出
  4. 提交信息 Skill：规范化 Git 提交

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

下一章我们将了解 各工具对 Skill 的支持情况。