名称: sop-authoring 用户可调用: false 描述: 当为AI代理编写或创建新标准操作程序(SOPs)时使用。涵盖有效的SOP写作、清晰原则和可操作指令设计。允许的工具:

读取
写入
编辑
Bash
Grep
Glob

SOP编写

有效的标准操作程序(SOPs)将复杂的工作流程转化为可重用、确定性的指令给AI代理。这个技能涵盖了编写清晰、可操作SOP的原则和实践。

关键概念

什么构成一个好的SOP

单一职责: 每个SOP处理一个特定的工作流程或任务
确定性: 相同的输入产生相同的输出
可操作性: 每个步骤都是具体且可执行的
参数化: 变量使跨上下文重用成为可能
自包含: 最少的外部依赖

SOP与一般文档的区别

SOPs: 描述性工作流程，具有特定步骤
文档: 描述性参考材料
指南: 带有解释的教育内容
教程: 逐步学习体验

当您需要一致、可重复执行多步过程时使用SOPs。

最佳实践

编写清晰指令

应做:

使用主动语态和祈使语气
以动作动词开始步骤（分析、生成、验证）
具体说明预期结果
为每个步骤包含成功标准
使用编号列表用于顺序步骤
使用项目符号用于无序项目

不应做:

使用被动语态（“应该被完成” → “执行此操作”）
包括模糊指令（“改进代码”）
混合程序性和参考内容
未说明即假定隐式知识

标题和描述

# {动作动词} {结果} SOP

## 概述
{1-2句话描述此SOP实现什么及何时使用}

好标题:

“生成代码库文档”
“使用TDD实现功能”
“为安全性审查拉取请求”

差标题:

“文档”（太模糊）
“如何可能改进代码质量”（不确定）
“一切的完整指南”（太宽泛）

结构步骤

顺序步骤:

## 步骤

1. 分析代码库结构
   - 识别主要入口点
   - 映射目录组织
   - 记录关键依赖

2. 提取架构模式
   - 识别使用的设计模式
   - 记录数据流
   - 注意组件关系

3. 生成文档
   - 创建包含概述的README.md
   - 记录API接口
   - 添加设置说明

条件逻辑:

## 步骤

1. 检查是否存在测试
   - 如果存在测试: 运行现有测试套件
   - 如果无测试: 先创建测试结构

2. 基于测试结果实现功能
   - 如果测试通过: 添加新功能
   - 如果测试失败: 在继续前修复失败测试

参数

定义使SOPs可重用的参数:

## 参数

- **仓库路径**: {repository_path}
- **输出格式**: {output_format} (markdown, json, html)
- **详细程度**: {verbosity} (简洁, 详细, 全面)

在步骤中使用:

1. 导航到 {repository_path}
2. 以 {output_format} 格式生成文档
3. 使用 {verbosity} 详细程度

成功标准

包含明确的成功标准:

## 成功标准

- [ ] 所有源文件都有记录
- [ ] README.md存在，包含设置说明
- [ ] API文档完整
- [ ] 示例经过测试且工作正常

示例

示例1: 代码审查SOP

# 审查代码变更以获取质量

## 概述
系统审查代码变更，以确保质量、可维护性和遵守项目标准。

## 参数

- **拉取请求URL**: {pr_url}
- **审查深度**: {depth} (快速, 标准, 彻底)

## 步骤

1. 从 {pr_url} 获取拉取请求详情
   - 阅读PR描述和上下文
   - 识别更改的文件
   - 注意破坏性更改

2. 审查代码质量
   - 检查代码异味
   - 验证错误处理
   - 评估测试覆盖率
   - 验证文档更新

3. 检查架构一致性
   - 确保模式匹配现有代码
   - 验证关注点分离
   - 审查依赖添加

4. 生成审查反馈
   - 按严重性列出问题（关键, 主要, 次要）
   - 建议具体改进
   - 突出正面更改

## 成功标准

- [ ] 所有关键问题已识别
- [ ] 反馈具体且可操作
- [ ] 代码风格检查符合项目标准
- [ ] 安全影响已审查

示例2: 功能实现SOP

# 使用测试驱动开发实现功能

## 概述
遵循TDD红绿重构周期，实现新功能，具有全面的测试覆盖率。

## 参数

- **功能描述**: {feature_description}
- **测试框架**: {test_framework}

## 步骤

1. 创建失败测试（红）
   - 编写描述期望行为的测试
   - 运行测试以确认失败
   - 验证失败消息正确

2. 实现最小代码（绿）
   - 编写最简单代码以通过测试
   - 避免过早优化
   - 运行测试以确认通过

3. 重构（重构）
   - 改进代码结构
   - 提取常见模式
   - 运行测试以确保仍通过

4. 对每个需求重复
   - 将功能分解为小增量
   - 对每个遵循红绿重构
   - 每个完整周期后提交

## 成功标准

- [ ] 所有测试通过
- [ ] 测试覆盖率 ≥ 80%
- [ ] 无代码重复
- [ ] 功能满足需求

示例3: 文档生成SOP

# 生成全面的代码库文档

## 概述
分析代码库并生成全面文档，包括架构概述、API参考和设置说明。

## 参数

- **仓库路径**: {repository_path}
- **文档格式**: {format} (markdown, html, pdf)
- **包括示例**: {include_examples} (是, 否)

## 步骤

1. 分析仓库结构
   - 识别编程语言
   - 映射目录组织
   - 定位配置文件
   - 找到现有文档

2. 提取架构信息
   - 识别主要入口点
   - 记录数据流
   - 映射组件依赖
   - 注意设计模式

3. 文档化公共API
   - 列出所有公共函数/方法
   - 提取参数类型
   - 记录返回值
   - 如果 {include_examples} 是是，包括使用示例

4. 生成设置说明
   - 列出先决条件
   - 记录安装步骤
   - 提供配置示例
   - 包括故障排除部分

5. 创建文档文件
   - 生成包含概述的README.md
   - 创建带接口文档的API.md
   - 如果项目接受贡献，添加CONTRIBUTING.md
   - 格式化输出为 {format}

## 成功标准

- [ ] 文档覆盖所有公共API
- [ ] 设置说明完整
- [ ] 架构解释清晰
- [ ] 示例经过测试且准确

常见模式

错误处理

## 错误处理

如果任何步骤失败:
1. 记录失败原因
2. 提供故障排除步骤
3. 建议替代方法
4. 不继续到下一步

验证步骤

## 验证

在每个主要步骤后:
- 验证输出满足质量标准
- 检查错误或警告
- 确认结果匹配期望

迭代过程

## 过程

对于每个 {item} 在 {collection} 中:
1. 对 {item} 执行操作
2. 验证结果
3. 继续下一个 {item}

反模式

避免这些常见错误:

过度一般指令
- ❌ “改进代码质量”
- ✅ “运行linter并修复所有错误，然后移除代码重复”
缺少上下文
- ❌ “运行测试”
- ✅ “使用 npm test 运行测试套件，并验证所有测试通过”
模糊成功标准
- ❌ “代码应该好”
- ✅ “代码通过所有linter检查且无安全漏洞”
隐含假设
- ❌ 假设工具已安装
- ✅ 明确列出先决条件
混合多个工作流程
- ❌ 在一个SOP中结合测试、部署和监控
- ✅ 创建可组合的单独SOPs

SOP编写Skill sop-authoring