Superpowers 教程 10：writing-skills（创建与测试自定义 Skills）

教程概述

系列目录：Superpowers 教程系列索引

writing-skills 是 Superpowers 的元技能——它教你如何创建新的技能。通过本教程，你将学会扩展 Superpowers 技能库，创建适合自己团队的定制化技能。

你将学到

✅ 技能的标准结构
✅ TDD 文档方法
✅ 技能测试策略
✅ 触发条件设计
✅ 实际技能开发案例

为什么创建自定义技能？

标准技能的局限

标准技能覆盖通用场景，但可能缺少：
- 团队特定的工作流
- 行业特定的规范
- 公司特定的合规要求
- 项目特定的最佳实践

自定义技能的价值

flowchart TD
    A[团队需求] --> B[创建自定义技能]
    B --> C[标准化流程]
    C --> D[新人快速上手]
    C --> E[AI 行为一致]
    C --> F[知识沉淀]
    
    style B fill:#e1f5ff
    style C fill:#e8f5e9

适用场景

场景	标准技能	自定义技能
通用开发流程	✅	-
团队代码规范	-	✅
行业合规要求	-	✅
特定技术栈	-	✅
公司流程	-	✅

技能结构详解

标准技能文件结构

skills/
└── your-skill-name/
    ├── SKILL.md           # 技能主文档（必需）
    ├── TEST.md            # 测试文档（推荐）
    ├── examples/          # 示例目录（推荐）
    │   ├── good/          # 好的示例
    │   └── bad/           # 坏的示例
    └── resources/         # 参考资源（可选）

SKILL.md 标准结构

# skill-name

[一句话描述技能的用途]

## Trigger

[触发条件 - 何时应该使用这个技能]

## Behavior

[行为描述 - 技能应该做什么]

## Process

[流程步骤 - 详细的执行步骤]

## Output

[输出要求 - 应该产生什么结果]

## Examples

[示例 - 好的和坏的对比]

## Anti-patterns

[反模式 - 应该避免的行为]

## Related Skills

[相关技能 - 与其他技能的关系]

TDD 文档方法

writing-skills 采用测试驱动文档（Test-Driven Documentation）方法：

flowchart TD
    A[明确技能目标] --> B[编写测试场景]
    B --> C[定义成功标准]
    C --> D[编写技能文档]
    D --> E[运行测试验证]
    E --> F{测试通过？}
    F -->|否 | G[修改技能文档]
    G --> E
    F -->|是 | H[技能完成]
    
    style B fill:#ffebee
    style C fill:#ffebee
    style H fill:#e8f5e9

步骤 1: 明确技能目标

## 技能目标模板

**技能名称**: [简洁描述性的名称]

**解决的问题**: 
[当前缺少什么？为什么需要这个技能？]

**目标用户**:
[谁会使用这个技能？]

**成功标准**:
- [ ] 标准 1
- [ ] 标准 2
- [ ] 标准 3

示例：

**技能名称**: deploying-to-production

**解决的问题**: 
团队在部署到生产环境时没有统一流程，导致：
- 部署前检查遗漏
- 回滚方案不明确
- 通知不及时

**目标用户**:
- 开发团队
- DevOps 工程师
- AI 编程助手

**成功标准**:
- [ ] 部署前自动检查清单
- [ ] 回滚方案必须明确
- [ ] 相关方自动通知

步骤 2: 编写测试场景

## 测试场景

### 场景 1: 正常触发

**输入**: "准备部署到生产环境"

**期望行为**:
1. 技能被触发
2. 显示部署检查清单
3. 要求确认回滚方案
4. 生成部署计划

**期望输出示例**:
```markdown
## 部署前检查清单

在部署之前，请确认以下项目：

### 代码检查
- [ ] 所有测试通过
- [ ] 代码审查完成
- [ ] 无已知严重 Bug

### 回滚方案
请描述回滚方案：
[等待用户输入]

### 通知列表
需要通知的相关方：
[等待用户输入]


### 场景 2: 边界情况

**输入**: "快速部署，跳过检查"

**期望行为**:
1. 技能被触发
2. 强调检查的重要性
3. 提供快速通道但需要确认

**期望输出**:
```markdown
⚠️ 我理解您需要快速部署，但为了确保生产环境稳定，
以下检查是必需的：

**最小检查清单**:
- [ ] 关键测试通过
- [ ] 回滚方案确认

如需跳过完整检查，请确认：
"我理解风险，确认继续"


### 场景 3: 不触发情况

**输入**: "部署到测试环境"

**期望行为**:
- 技能不触发（这是生产环境部署技能）
- 可能有其他技能处理

**验证**:
- 确认技能静默

步骤 3: 定义成功标准

## 成功标准详细定义

### 功能性标准
- [ ] 触发准确率 > 95%
- [ ] 输出格式一致
- [ ] 检查清单完整

### 非功能性标准
- [ ] 响应时间 < 5 秒
- [ ] 输出简洁清晰
- [ ] 易于理解和执行

### 边界情况
- [ ] 处理跳过检查请求
- [ ] 处理部分信息缺失
- [ ] 处理紧急部署场景

编写技能文档

Trigger 部分

## Trigger

**自动触发**:
- "部署到生产"
- "发布新版本"
- "push to production"
- "上线新功能"

**手动触发**:
- "使用 deploying-to-production 技能"
- "帮我准备部署"

**不触发**:
- "部署到测试环境"
- "部署到 staging"
- "本地测试"

Behavior 部分

## Behavior

当触发时，技能应该：

1. **呈现检查清单**
   - 代码检查项
   - 测试检查项
   - 文档检查项

2. **要求关键信息**
   - 回滚方案
   - 通知列表
   - 部署时间窗口

3. **生成部署计划**
   - 分步操作指南
   - 验证步骤
   - 监控指标

Process 部分

## Process

### 阶段 1: 部署前检查

1. 展示检查清单
2. 逐项确认
3. 记录结果

### 阶段 2: 风险评估

1. 评估变更范围
2. 确认回滚方案
3. 识别风险点

### 阶段 3: 部署计划

1. 生成详细计划
2. 确认时间节点
3. 分配责任

### 阶段 4: 执行部署

1. 按步骤执行
2. 每步验证
3. 记录结果

### 阶段 5: 部署后验证

1. 运行冒烟测试
2. 检查监控指标
3. 确认功能正常

Output 部分

## Output

技能应该生成：

### 部署检查报告
```markdown
## 部署检查报告

**应用**: my-app
**版本**: v1.2.3
**时间**: 2026-02-28 15:00

### 检查结果
- 代码检查：✅ 通过
- 测试检查：✅ 通过
- 文档检查：✅ 通过

### 风险评估
风险级别：低
回滚方案：已确认

### 批准
[ ] 技术负责人批准
[ ] 产品经理批准

部署操作指南

## 部署步骤

1. 拉取最新代码
   ```bash
   git pull origin main

构建
```
npm run build
```
部署
```
./deploy.sh production
```
验证
```
curl https://api.example.com/health
```

技能测试策略

测试类型

## 测试类型

### 1. 触发测试
验证技能在正确时触发，错误时不触发

### 2. 输出测试
验证输出格式和内容符合预期

### 3. 流程测试
验证技能流程完整性

### 4. 边界测试
验证边界情况处理

测试模板

## 测试用例

### Test 1: 标准部署流程

**输入**:

帮我部署到生产环境


**期望**:
1. ✅ 技能触发
2. ✅ 显示检查清单
3. ✅ 要求回滚方案

**验证命令**:
```bash
# 检查技能日志
cat .superpowers/logs/deploy-*.log

Test 2: 跳过检查请求

输入:

快速部署，跳过检查

期望:

✅ 技能触发
✅ 警告风险
✅ 要求确认

验证:

确认输出包含风险警告
确认需要明确确认

Test 3: 测试环境部署

输入:

部署到测试环境

期望:

❌ 技能不触发
ℹ️ 可能建议使用其他技能

验证:

确认技能静默


## 实际案例：创建团队代码规范技能

### 案例背景

团队有特定的代码规范，需要 AI 在代码审查时遵循：

```markdown
# team-code-review

## Trigger

- 完成功能开发时
- 请求代码审查时
- 提交 PR 前

## Behavior

根据团队规范审查代码，重点关注：
1. 命名规范
2. 函数长度
3. 注释要求
4. 错误处理
5. 测试覆盖

## Team Standards

### 命名规范
- 变量：camelCase
- 类：PascalCase
- 常量：UPPER_SNAKE_CASE
- 私有成员：_prefix

### 函数要求
- 最大行数：30 行
- 参数数量：≤ 5 个
- 必须有 JSDoc

### 注释要求
- 公共 API 必须有 JSDoc
- 复杂逻辑必须有解释注释
- 不允许"做了什么"的冗余注释

### 错误处理
- 必须处理所有异常情况
- 错误消息必须清晰
- 记录日志用于调试

### 测试要求
- 单元测试覆盖率 ≥ 85%
- 关键路径 100% 覆盖
- 包含边界条件测试

## Output Format

## 代码审查报告

**文件**: [文件路径]
**审查者**: AI Assistant

### ✅ 符合规范
- [列出符合的项目]

### ⚠️ 需要改进
- [列出不符合的项目和建议]

### 📋 检查清单
- [ ] 命名规范
- [ ] 函数长度
- [ ] 注释完整
- [ ] 错误处理
- [ ] 测试覆盖

最佳实践

1. 技能命名

✅ 好：
- test-driven-development
- systematic-debugging
- using-git-worktrees

❌ 坏：
- tdd (缩写不清晰)
- debug (太泛)
- git (太泛)

2. 触发条件设计

✅ 好：
- 自然语言触发词（多个同义词）
- 上下文感知触发
- 明确的排除条件

❌ 坏：
- 单一触发词
- 过于宽泛
- 没有排除条件

3. 输出格式

✅ 好：
- 结构化（Markdown）
- 清晰的分节
- 可执行的代码块

❌ 坏：
- 大段文字
- 没有格式
- 模糊描述

4. 测试覆盖

✅ 好：
- 正常场景测试
- 边界情况测试
- 负面场景测试

❌ 坏：
- 只有一个测试
- 没有边界测试
- 没有失败场景

5. 版本管理

## 版本历史

### v1.0.0 (2026-02-28)
- 初始版本
- 基本检查清单
- 标准输出格式

### v1.1.0 (2026-03-15)
- 添加快速部署通道
- 改进风险评估
- 优化输出格式

### v2.0.0 (2026-04-01)
- 添加自动化检查集成
- 支持多环境部署
- 回滚流程改进

技能发布与共享

发布到团队

## 发布流程

1. **内部审查**
   - 团队成员审查技能文档
   - 运行所有测试场景
   - 收集反馈

2. **试点使用**
   - 选择 1-2 个项目试点
   - 收集使用反馈
   - 迭代改进

3. **正式发布**
   - 更新技能仓库
   - 通知团队成员
   - 提供培训文档

4. **持续维护**
   - 定期审查和更新
   - 收集使用数据
   - 修复问题

发布到社区

## 发布到 Superpowers Marketplace

1. **准备发布**
   - 完整的技能文档
   - 完整的测试用例
   - 使用示例

2. **提交到 Marketplace**
   - 创建 PR 到 superpowers-marketplace
   - 遵循提交规范
   - 响应审查意见

3. **发布后**
   - 收集用户反馈
   - 持续改进
   - 维护文档

小结

writing-skills 是扩展 Superpowers 的元技能：

TDD 文档 - 先写测试再写文档
标准结构 - Trigger/Behavior/Process/Output
完整测试 - 正常/边界/负面场景
持续迭代 - 版本管理和维护

关键要点

✅ 明确技能目标和成功标准
✅ 先写测试场景再写文档
✅ 遵循标准结构
✅ 完整的测试覆盖

技能模板速查

# skill-name

[一句话描述]

## Trigger
[触发条件]

## Behavior
[行为描述]

## Process
[流程步骤]

## Output
[输出要求]

## Examples
[示例]

## Anti-patterns
[反模式]

## Related Skills
[相关技能]

Superpowers 教程系列总结

恭喜完成全部 10 篇教程！你已掌握：

教程	技能	核心价值
1	安装配置	快速上手
2	brainstorming	设计优先
3	writing-plans	原子化计划
4	TDD	测试驱动
5	debugging	系统调试
6	worktrees	隔离开发
7	code review	技术严谨
8	subagent	并行执行
9	verification	证据验证
10	writing-skills	扩展能力

持续学习：

访问 GitHub 仓库
加入社区讨论
分享你的自定义技能

系列导航：

← 上一篇：教程 9：verification-before-completion 与 finishing-a-branch
返回：教程系列索引