最佳实践
编写高质量的 Skill 不仅是技术问题，更是设计问题。本章总结了一系列最佳实践，帮助你创建专业、可维护、高效的 Skills。
设计原则
单一职责原则
每个 Skill 应该专注于一个明确的任务。不要试图创建"全能型" Skill。
❌ 违反单一职责
name: "code-helper"
description: "帮助编写、审查、测试和优化代码"
✅ 遵循单一职责
name: "code-reviewer"
description: "审查代码质量，发现潜在问题"
name: "test-generator"
description: "为代码生成单元测试"
name: "code-formatter"
description: "按照规范格式化代码"
单一职责的好处：
- 更容易触发：description 更精准
- 更易维护：修改不会影响其他功能
- 更易复用：可以灵活组合多个 Skills
明确边界原则
Skill 应该明确说明它的适用范围和边界。
## 适用范围
- Python 3.8+ 代码
- 单文件或代码片段
- 项目代码（非库代码）
## 不适用场景
- 其他编程语言
- 整个项目审查
- 库 API 设计审查
## 边界情况处理
- 空文件：提示用户
- 超大文件（>500 行）：建议分批审查
- 非代码文件：跳过并提示
渐进式信息原则
指令应该从简单到复杂，从概览到细节。
## 审查流程
### 第一阶段：快速扫描（30 秒）
快速识别明显问题：
- 语法错误
- 导入问题
- 命名规范
### 第二阶段：详细审查（5 分钟）
逐项检查：
- 类型注解
- 文档字符串
- 错误处理
### 第三阶段：深度分析（可选）
针对关键代码：
- 性能分析
- 安全审计
- 可维护性评估
Description 编写技巧
功能 + 触发条件公式
description 应该遵循"功能描述 + 触发条件"的格式：
[功能描述]。当用户 [触发条件] 时触发。
示例：
description: "审查 Python 代码质量，检查 PEP 8 规范和潜在问题。当用户请求代码审查、代码检查、code review 或提交 Python 代码时触发。"
关键词覆盖
列出用户可能使用的各种说法：
description: "为代码生成单元测试。当用户请求生成测试、写测试、添加单元测试、创建测试用例或 test coverage 时触发。"
排除条件
如果需要避免误触发，可以添加排除条件：
description: "审查 Python 代码质量。当用户请求代码审查时触发。注意：不适用于代码编写、代码调试或代码解释场景。"
指令编写技巧
使用检查清单
检查清单让 AI 系统地执行任务：
## 检查清单
在审查代码时，请逐项检查以下内容：
### 命名规范
- [ ] 变量名使用 snake_case
- [ ] 类名使用 PascalCase
- [ ] 常量使用全大写 SNAKE_CASE
- [ ] 私有属性以单下划线开头
- [ ] 名称具有描述性，避免单字母（循环变量除外）
### 类型注解
- [ ] 函数参数有类型注解
- [ ] 返回值有类型注解
- [ ] 复杂类型使用 typing 模块
- [ ] Optional 类型正确使用
### 文档
- [ ] 模块有 docstring
- [ ] 公共函数有 docstring
- [ ] docstring 格式一致
提供示例
示例比抽象描述更有效：
## 输出示例
### 📊 审查摘要
- 文件：user_service.py
- 问题总数：5
### 🔴 严重问题
| 行号 | 问题描述 | 修改建议 |
|------|----------|----------|
| 15 | 未处理可能的 None 值 | 添加 None 检查 |
| 42 | 资源未关闭 | 使用 with 语句 |
### 🟡 警告
| 行号 | 问题描述 | 修改建议 |
|------|----------|----------|
| 8 | 缺少类型注解 | 添加参数和返回值类型 |
| 23 | 行长度超过 88 字符 | 拆分长行 |
### 📝 总体评价
代码整体结构清晰，但存在一些需要改进的地方。建议优先修复严重问题。（评分：7/10）
定义优先级
明确问题的优先级，帮助用户聚焦：
## 问题优先级
### 🔴 严重（必须修复）
- 可能导致运行时错误
- 安全漏洞
- 数据丢失风险
### 🟡 警告（建议修复）
- 代码风格问题
- 性能问题
- 可维护性问题
### 🔵 建议（可选优化）
- 代码简化建议
- 文档改进建议
- 测试覆盖建议
组织多个 Skills
技能组合
多个 Skills 可以组合成工作流：
项目开发工作流：
1. code-formatter → 格式化代码
2. code-reviewer → 审查代码质量
3. test-generator → 生成测试
4. doc-generator → 生成文档
避免功能重叠
确保不同 Skills 之间没有功能重叠：
❌ 功能重叠
skill-a: "审查 Python 代码风格"
skill-b: "检查 Python 代码规范"
✅ 功能互补
skill-a: "审查 Python 代码风格（PEP 8）"
skill-b: "检查 Python 类型注解正确性"
建立技能库
为团队建立统一的技能库：
team-skills/
├── python/
│ ├── code-reviewer/
│ ├── test-generator/
│ └── doc-generator/
├── frontend/
│ ├── react-reviewer/
│ └── css-linter/
└── devops/
├── docker-reviewer/
└── ci-cd-generator/
版本管理
版本号规范
使用语义化版本号：
---
name: "code-reviewer"
version: "1.2.0"
---
版本号格式：主版本号.次版本号.修订号
- 主版本号：不兼容的重大变更
- 次版本号：向后兼容的功能新增
- 修订号：向后兼容的问题修复
变更日志
在 Skill 文件中记录变更：
## 变更日志
### v1.2.0 (2026-01-15)
- 新增：支持异步代码审查
- 改进：优化输出格式
### v1.1.0 (2026-01-01)
- 新增：支持类型注解检查
- 修复：空文件处理问题
### v1.0.0 (2025-12-20)
- 初始版本
性能优化
控制指令长度
过长的指令会增加 Token 消耗和响应时间：
❌ 过长的指令（5000+ 字符）
包含大量重复内容、冗长解释
✅ 适中的指令（1000-3000 字符）
精炼、结构化、无冗余
按需加载
利用 description 实现按需加载：
description: "审查 Python 代码。仅在用户明确请求代码审查时触发。"
分层指令
对于复杂任务，可以使用分层指令：
## 基础审查（默认执行）
- 语法检查
- 风格检查
## 深度审查（用户请求时执行）
- 性能分析
- 安全审计
测试与验证
测试用例
为 Skill 准备测试用例：
## 测试用例
### 用例 1：正常代码
输入：符合规范的 Python 代码
预期：通过审查，无严重问题
### 用例 2：问题代码
输入：包含明显问题的代码
预期：正确识别并报告问题
### 用例 3：边界情况
输入：空文件
预期：友好提示，不报错
### 用例 4：误触发测试
输入："帮我写一个 Python 函数"
预期：不触发此 Skill
持续改进
根据使用反馈持续改进：
- 收集用户反馈
- 分析触发准确性
- 优化输出质量
- 更新文档和示例
常见陷阱
陷阱一：过度抽象
❌ 过度抽象
description: "处理文本"
✅ 具体明确
description: "审查 Python 代码质量，检查 PEP 8 规范"
陷阱二：指令冲突
❌ 指令冲突
"检查所有代码风格问题，但忽略命名规范"
✅ 指令一致
"检查所有代码风格问题，包括命名规范"
陷阱三：忽略边界情况
❌ 忽略边界
（没有处理空输入、超大输入等情况）
✅ 处理边界
"对于空文件，提示用户提供代码"
"对于超大文件，建议分批审查"
小结
遵循这些最佳实践，可以创建高质量的 Skills：
- 单一职责：每个 Skill 只做一件事
- 明确边界：定义适用范围和边界情况
- 精准触发：description 包含功能和触发条件
- 结构化指令：使用检查清单和示例
- 持续优化：根据反馈改进
下一章我们将通过 实战案例 加深理解。