最佳实践与常见陷阱

经过实践总结的最佳实践和常见陷阱，帮助你写出高质量的 Skill。

最佳实践

1. Prompt 设计

✅ 明确具体

// ✅ 好：明确维度和格式
请从以下维度分析：
1. 功能：代码的主要作用
2. 流程：执行步骤
3. 问题：潜在 bug
4. 优化：改进建议

使用 Markdown 格式，每个维度用 ## 标题

// ❌ 不好：模糊笼统
请分析这段代码

✅ 提供上下文

// ✅ 好：提供项目上下文
代码：
{{code}}

上下文：
- 语言：{{language}}
- 框架：{{framework}}
- 项目类型：{{projectType}}

✅ 设置约束

// ✅ 好：明确约束
要求：
- 使用中文回答
- 代码示例必须可运行
- 指出问题时要给出解决方案

禁止：
- 不要修改功能
- 不要删除注释

2. 示例编写

✅ 覆盖不同场景

{
  "examples": [
    {
      "input": "简单代码示例",
      "output": "..."
    },
    {
      "input": "复杂代码示例",
      "output": "..."
    },
    {
      "input": "边界情况示例",
      "output": "..."
    }
  ]
}

✅ 展示期望质量

// ✅ 好：示例展示完美的输出
"output": "## 1. 整体功能\n这是一个...\n\n## 2. 执行流程\n1. ...\n2. ...\n\n## 3. 关键变量\n- `x`: ...\n- `y`: ..."

// ❌ 不好：示例质量不高
"output": "这段代码是一个函数。"

3. 变量命名

✅ 语义化命名

// ✅ 好：语义清晰
{{code}}
{{language}}
{{complexityLevel}}
{{includeTests}}

// ❌ 不好：缩写或模糊
{{c}}
{{lang}}
{{level}}
{{tests}}

4. Skill 组织

✅ 单一职责

{
  "name": "explain-code",
  "description": "解释代码工作原理"
}
// 只做解释，不做其他事情

{
  "name": "optimize-code",
  "description": "优化代码性能"
}
// 只做优化，不做其他事情

✅ 组合使用

用户: /explain-code
...

用户: /optimize-code
...

// 而不是一个 Skill 做两件事

5. 渐进复杂度

✅ 从简单开始

Step 1: 基础功能
Step 2: 添加错误处理
Step 3: 添加性能优化
Step 4: 添加高级特性

✅ 提供默认值

{{language || 'JavaScript'}}
{{complexity || 'medium'}}
{{includeComments || true}}

常见陷阱

陷阱 1：Prompt 太长

问题：Prompt 超过 2000 字，AI 容易遗漏信息

现象：

• AI 只执行了部分要求
• 输出不完整

解决：

• 精简 Prompt，保留核心内容
• 将复杂 Skill 拆分成多个简单 Skill
• 使用母 Skill 协调子 Skill

// ❌ 不好：太长
请审查代码，包括：
1. 安全问题（10 个子项）
2. 性能问题（10 个子项）
3. 代码质量（10 个子项）
4. 最佳实践（10 个子项）
5. 架构设计（10 个子项）
...

// ✅ 好：精简
请审查代码，关注：
1. 安全问题（核心 3-5 项）
2. 性能问题（核心 3-5 项）
3. 代码质量（核心 3-5 项）

陷阱 2：示例太少

问题：没有示例或示例质量低

现象：

• AI 输出格式不一致
• 输出质量不稳定

解决：

• 至少提供 2-3 个高质量示例
• 示例覆盖不同场景
• 示例展示期望的完美输出

陷阱 3：变量未定义

问题：Prompt 使用了未定义的变量

现象：

• AI 无法正确理解任务
• 输出包含 原文

解决：

• 确保所有 都在输入中定义
• 为变量提供默认值
• 在 Prompt 开头说明需要的变量

陷阱 4：要求矛盾

问题：Prompt 中包含矛盾的要求

现象：

• AI 困惑，输出质量差
• 不同调用结果不一致

解决：

• 检查 Prompt 逻辑一致性
• 避免矛盾的要求
• 明确优先级

// ❌ 不好：矛盾
请生成简洁但详细的文档
请快速但仔细地进行分析

// ✅ 好：一致
请生成简洁的文档（控制在 200 字以内）
请进行快速初步分析（5 分钟内完成）

陷阱 5：过度约束

问题：Prompt 中约束过多，限制 AI 能力

现象：

• 输出僵化，缺乏灵活性
• 无法处理边界情况

解决：

• 只约束必要的部分
• 给 AI 留有一定自由度
• 在示例中展示灵活性

陷阱 6：忽视错误处理

问题：Skill 没有考虑错误情况

现象：

• 输入异常时 Skill 失败
• 输出包含错误信息

解决：

• 在 Prompt 中添加输入验证
• 提供错误处理指南
• 在示例中包含错误处理

// ✅ 好：包含错误处理
如果输入为空，返回："错误：输入不能为空"
如果输入格式错误，返回："错误：输入格式不正确，期望格式为..."

陷阱 7：不更新维护

问题：Skill 创建后不再更新

现象：

• Skill 与项目需求脱节
• 输出质量逐渐下降

解决：

• 定期回顾和更新 Skill
• 根据使用反馈改进
• 建立 Skill 版本管理

检查清单

创建 Skill 时，检查以下事项：

基本信息

• [ ] Name 使用 kebab-case
• [ ] Description 简洁明确
• [ ] Description 不说"这个 Skill"

Prompt 设计

• [ ] 任务明确具体
• [ ] 使用变量占位符
• [ ] 提供项目上下文
• [ ] 明确输出格式
• [ ] 设置合理约束
• [ ] 长度适中（< 2000 字）

示例编写

• [ ] 至少 2-3 个示例
• [ ] 覆盖不同场景
• [ ] 展示完美输出质量
• [ ] 包含边界情况

错误处理

• [ ] 考虑空输入
• [ ] 考虑格式错误
• [ ] 考虑异常数据
• [ ] 提供错误提示

测试验证

• [ ] 测试简单输入
• [ ] 测试复杂输入
• [ ] 测试边界情况
• [ ] 测试错误输入

版本管理

Skill 版本命名

explain-code-v1.json
explain-code-v2.json
explain-code-v2.1.json

变更记录

## v1.0.0 (2026-01-15)
- 初始版本
- 基础代码解释功能

## v1.1.0 (2026-02-01)
- 添加性能分析维度
- 优化输出格式

## v2.0.0 (2026-03-01)
- 支持多语言
- 添加安全审查
- **BREAKING**: 输入格式变更

团队协作

Skill 共享

1. 存放位置：项目仓库的 .skills/ 目录
2. 命名规范：团队名-skill-name.json
3. 文档说明：README 中说明 Skill 用途

代码审查

Skill 也应该被审查：

• Prompt 是否清晰？
• 示例是否足够？
• 是否有安全漏洞？
• 是否遵循最佳实践？

性能优化

减少 Token 消耗

// ❌ 不好：冗长
请详细解释以下代码的工作原理，包括它的整体功能、执行流程、关键变量和函数、潜在问题以及改进建议...

// ✅ 好：简洁
请解释代码：
1. 功能：主要作用
2. 流程：执行步骤
3. 问题：潜在 bug
4. 优化：改进建议

缓存结果

对于重复性任务，考虑缓存 Skill 输出：

输入：相同代码片段
输出：直接返回缓存结果

总结

方面	最佳实践	避免陷阱
Prompt	明确、简洁、有约束	太长、模糊、矛盾
示例	多场景、高质量	太少、质量低
变量	语义化、有默认值	未定义、缩写
维护	定期更新、版本管理	一次性、不维护

下一步

继续学习其他核心概念：

→ OpenSpec 核心概念