agent-sop-author

Agent SOP 作者

概述

Agent SOP（标准操作规程）是基于 Markdown 的指令集，通过自然语言、参数化输入和基于约束的执行，引导 AI Agent 完成复杂工作流。本技能将教你如何创建（或更新）、构建和验证可在不同 AI 系统中使用的 Agent SOP。

用法

处理 Agent SOP 时，如需：

• 创建新的工作流自动化 SOP
• 更新现有的工作流自动化 SOP
• 构建多步骤 Agent 工作流
• 应用 RFC 2119 约束（MUST、SHOULD、MAY）
• 验证 SOP 格式和结构
• 将工作流转换为可复用模板
• 确保 SOP 可在不同 AI 系统（Claude、Kiro、Cursor 等）中使用

核心概念

什么是 Agent SOP？

Agent SOP 是标准化的 Markdown 文件（.sop.md），用于定义：

• 明确的目标，并附有详细概述
• 参数化输入，便于灵活复用
• 分步说明，并附有 RFC 2119 约束
• 示例和故障排除，确保可靠执行
• 多模态分发（MCP 工具、Agent Skills、Python 模块）

主要特性

RFC 2119 约束：使用标准化关键词（MUST、SHOULD、MAY），在不采用僵化脚本的情况下精确控制 Agent 的行为。

参数化：接受可定制行为的参数，以适应不同项目、团队或需求。

可恢复性：记录 Agent 工作时的进度，便于在工作被中断后了解进展并继续执行。

创建 Agent SOP

文件位置

你 MUST 检查当前工作目录中是否存在 agent-sops/ 目录：

• 如果存在 agent-sops/，你 MUST 将 SOP 文件写入该目录
• 如果不存在 agent-sops/，你 MAY 将 SOP 写入当前目录，或询问用户将其保存到何处

文件命名

你 MUST 遵循以下命名约定：

• 使用 .sop.md 文件扩展名
• 文件名使用 kebab-case（例如，code-assist.sop.md、idea-honing.sop.md）
• 选择能表明 SOP 用途的描述性名称

验证

每次更改后，你 MUST 运行 validate-sop.sh：

验证脚本位于此 SKILL.md 文件所在的同一目录中。读取此技能时，你会知道 SKILL.md 的完整路径；验证脚本也位于该目录中。

<skill-directory>/validate-sop.sh path/to/your-sop.sop.md

你 MUST 在继续之前修复所有错误（❌）。条件允许时，你 SHOULD 处理警告（⚠️）。

必需结构

每个 Agent SOP MUST 按顺序包含以下章节：

# [SOP Name]

## Overview
[Concise description of what the SOP does and when to use it]

## Parameters

- **required_param** (required): Description
- **optional_param** (optional, default: "value"): Description

**Constraints for parameter acquisition:**
- If all required parameters are already provided, You MUST proceed to the Steps
- If any required parameters are missing, You MUST ask for them before proceeding
- When asking for parameters, You MUST request all parameters in a single prompt
- When asking for parameters, You MUST use the exact parameter names as defined

## Steps
### 1. [Step Name]
Description of what happens in this step.

**Constraints:**
- You MUST [specific requirement]
- You SHOULD [recommended behavior]
- You MAY [optional behavior]

## Examples
[Concrete usage examples]

## Troubleshooting
[Common issues and solutions]

Parameters 章节

你 MUST 使用以下格式定义参数：

## Parameters

- **parameter_name** (required): Description of required input
- **another_param** (required): Description
- **optional_param** (optional): Description of optional input
- **with_default** (optional, default: "default_value"): Description

**Constraints for parameter acquisition:**
- If all required parameters are already provided, You MUST proceed to the Steps
- If any required parameters are missing, You MUST ask for them before proceeding
- When asking for parameters, You MUST request all parameters in a single prompt
- When asking for parameters, You MUST use the exact parameter names as defined

参数命名规则：

• 你 MUST 使用小写字母
• 空格处 MUST 使用下划线（snake_case）
• 名称 MUST 能清楚描述用途
• 你 MUST 将必需参数列在可选参数之前

参数获取约束章节：

• 每个 Parameters 章节中 MUST 包含此章节
• 你 MUST 包含以下指令：
  • “如果所有必需参数均已提供，你 MUST 继续执行 Steps”
  • “如果缺少任何必需参数，你 MUST 在继续之前询问用户”
  • “询问参数时，你 MUST 在同一条提示中请求所有参数”
  • “询问参数时，你 MUST 使用定义的确切参数名称”
• 为了灵活地提供输入方式，你 MAY 添加其他约束：

**Constraints for parameter acquisition:**
- If all required parameters are already provided, You MUST proceed to the Steps
- If any required parameters are missing, You MUST ask for them before proceeding
- When asking for parameters, You MUST request all parameters in a single prompt
- When asking for parameters, You MUST use the exact parameter names as defined
- You MUST support multiple input methods including:
  - Direct input: Text provided directly
  - File path: Path to a local file
  - URL: Link to an internal resource
- You MUST use appropriate tools to access content
- You MUST confirm successful acquisition before proceeding
- You SHOULD save acquired data to a consistent location

Steps 章节

你 MUST 按以下要求组织步骤：

1. 使用带编号的标题（### 1.、### 2. 等）
2. 步骤名称
3. 自然语言描述
4. 包含 RFC 2119 关键词的 Constraints: 章节

示例：

### 1. Setup
Initialize the project environment and create necessary structures.

**Constraints:**
- You MUST validate directory structure exists
- You MUST create missing directories
- You MUST NOT proceed if directory creation fails
- You SHOULD log all setup actions
- You MAY skip validation if --force flag is provided

条件逻辑：

### 3. Conditional Processing
If validation passes, proceed with processing. Otherwise, report errors.

**Constraints:**
- You MUST check validation status before proceeding
- If validation passes, You MUST process the data
- If validation fails, You MUST report specific errors
- You MUST NOT continue with invalid data

RFC 2119 关键词

你必须按照 RFC 2119 中的定义使用这些关键词：

• MUST / REQUIRED：绝对要求
• MUST NOT / SHALL NOT：绝对禁止
• SHOULD / RECOMMENDED：强烈建议（可能有合理理由不遵循）
• SHOULD NOT / NOT RECOMMENDED：强烈不建议（可能有合理理由接受）
• MAY / OPTIONAL：完全可选的项目

否定约束

使用否定约束时，你必须提供上下文：

良好（包含上下文）：

- You MUST NOT use ellipses (...) because your output will be read aloud by text-to-speech
- You SHOULD NEVER delete Git history files since this could corrupt the repository
- You MUST NOT run `git push` because this could publish unreviewed code

不佳（不包含上下文）：

- You MUST NOT use ellipses
- You SHOULD NEVER delete Git files
- You MUST NOT run git push

否定约束的常见上下文：

• 技术限制：“因为系统无法处理……”
• 安全风险：“因为这可能会暴露敏感数据……”
• 数据完整性：“因为这可能会损坏重要信息……”
• 用户体验：“因为用户会感到困惑……”
• 兼容性：“因为这会破坏与……的集成”
• 性能：“因为这可能会导致明显的速度下降……”

示例部分

你应该提供具体示例，展示：

• 示例输入参数
• 预期输出或行为
• 常见使用模式

## Examples

### Example 1: Basic Usage
**Input:**
- task_description: "Create user authentication system"
- mode: "interactive"

**Expected Behavior:**
Agent will guide through TDD workflow, creating tests first, then implementation.

### Example 2: Automated Mode
**Input:**
- task_description: "Fix bug in payment processing"
- mode: "auto"

**Expected Behavior:**
Agent will automatically implement fix following established patterns.

故障排除部分

你应该列出常见问题及解决方案：

## Troubleshooting

### Parameter Validation Fails
If parameter validation fails, check that:
- All required parameters are provided
- Parameter names use snake_case
- Values match expected types

### Step Execution Hangs
If a step appears to hang:
- Check for missing tool permissions
- Verify file paths are accessible
- Review constraint requirements

交互式 SOP

对于需要用户交互的 SOP：

1. 你应该明确指出何时需要用户交互
2. 你必须说明如何处理用户响应
3. 你应该说明交互记录的保存位置

示例：

### 2. Requirements Clarification
Guide the user through questions to refine their initial idea.

**Constraints:**
- You MUST ask one question at a time
- You MUST append each Q&A to "idea-honing.md"
- You SHOULD adapt follow-up questions based on previous answers
- You MUST continue until sufficient detail is gathered

最佳实践

编写 SOP 时，你应该遵循以下实践：

1. 聚焦步骤：每个步骤都应达成一个明确目标
2. 使用清晰的约束：明确区分要求与建议
3. 提供示例：为复杂工作流展示具体用法
4. 使用自然语言：编写易于理解的描述
5. 尽量简化：避免多层嵌套的条件逻辑
6. 明确产物：为所有创建的产物注明文件路径
7. 充分测试：验证 SOP 在不同 AI 系统上均可正常运行
8. 记录边缘情况：为常见问题提供故障排除说明

快速参考

元素	格式	是否必需
文件扩展名	.sop.md	是
标题	# SOP Name	是
概述	## Overview	是
参数	## Parameters	是
步骤	## Steps with ### N.	是
约束	**Constraints:** with RFC 2119	是
示例	## Examples	建议
故障排除	## Troubleshooting	建议

常见模式

之前：无结构的提示词

Please implement a user authentication system using TDD.
Make sure to write tests first and follow best practices.

之后：结构化 SOP

# Code Assist

## Overview
This SOP guides implementation using test-driven development.

## Parameters
- **task_description** (required): Description of task
- **mode** (optional, default: "interactive"): "interactive" or "auto"

## Steps
### 1. Setup
Initialize project environment.

**Constraints:**
- You MUST validate directory structure
- You MUST create test directory if missing
- You MUST NOT proceed if setup fails

### 2. Test Creation
Create tests based on requirements.

**Constraints:**
- You MUST write tests before implementation
- You SHOULD follow existing test patterns
- You MAY add additional edge case tests

常见错误

否定约束缺少上下文

问题： 使用 MUST NOT，却没有解释原因。
修正： 始终提供上下文：“你不得执行 X，因为 Y。”

参数描述含糊

问题： “input_data（必需）：数据” 修正： “input_data（必需）：包含用户资料字段（姓名、电子邮件、角色）的 JSON 对象”

混淆要求级别

问题： 对可选行为使用 MUST，或对关键要求使用 MAY。 修正： 准确使用 RFC 2119 关键词——绝对要求用 MUST，建议用 SHOULD，可选项用 MAY。

缺少示例

问题： 复杂工作流没有具体用法示例。 修正： 至少提供一个完整示例，展示输入参数和预期行为。

步骤过于复杂

问题： 单个步骤试图通过嵌套条件完成多个目标。 修正： 将其拆分为多个聚焦的步骤，每个步骤都包含明确的约束。

可视化工作流

flowchart TD
    Start[Create SOP] --> Name[Choose descriptive name]
    Name --> Structure[Add required sections]
    Structure --> Overview[Write overview]
    Overview --> Params[Define parameters]
    Params --> Steps[Create steps with constraints]
    Steps --> Examples[Add examples]
    Examples --> Troubleshoot[Add troubleshooting]
    Troubleshoot --> Validate[Validate format]
    Validate --> Test[Test with AI agent]
    Test --> Done[Distribute SOP]

    style Start fill:#90EE90
    style Done fill:#90EE90
    style Validate fill:#FFB6C1

关键要点

Agent SOP 可将复杂工作流转化为可复用、可分享的指令，并能在不同 AI 系统中使用。它们采用标准化的 Markdown 格式，并使用 RFC 2119 约束，在精确控制的同时保留 Agent 的推理能力。

创建 SOP 时，应注重清晰的结构、结合上下文的具体约束，以及具体示例。请在不同 AI 系统中进行充分测试，以确保可靠性。