Back to Details

agent-sop-author

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent SOP Author

Agent SOP 编写指南

Overview

概述

Agent SOPs (Standard Operating Procedures) are markdown-based instruction sets that guide AI agents through sophisticated workflows using natural language, parameterized inputs, and constraint-based execution. This skill teaches you how to create (or update), structure, and validate Agent SOPs that work across different AI systems.
Agent SOP（标准操作流程）是基于Markdown的指令集，通过自然语言、参数化输入和基于约束的执行，引导AI Agent完成复杂的工作流。本技能将教你如何创建（或更新）、构建和验证可在不同AI系统间通用的Agent SOP。

Usage

使用场景

When working with Agent SOPs and need to:
  • Create new workflow automation SOPs
  • Update existing workflow automation SOPs
  • Structure multi-step agent workflows
  • Apply RFC 2119 constraints (MUST, SHOULD, MAY)
  • Validate SOP format and structure
  • Convert workflows into reusable templates
  • Ensure SOPs work across AI systems (Claude, Kiro, Cursor, etc.)
当你处理Agent SOP时，若需要完成以下操作，可使用本技能：
  • 创建新的工作流自动化SOP
  • 更新现有的工作流自动化SOP
  • 构建多步骤Agent工作流
  • 应用RFC 2119约束（MUST、SHOULD、MAY）
  • 验证SOP的格式与结构
  • 将工作流转换为可复用模板
  • 确保SOP可在不同AI系统（Claude、Kiro、Cursor等）中运行

Core Concepts

核心概念

What is an Agent SOP?

什么是Agent SOP？

An Agent SOP is a standardized markdown file (
.sop.md
) that defines:
  • Clear objectives with detailed overviews
  • Parameterized inputs for flexible reuse
  • Step-by-step instructions with RFC 2119 constraints
  • Examples and troubleshooting for reliable execution
  • Multi-modal distribution (MCP tools, Anthropic Skills, Python modules)
Agent SOP是标准化的Markdown文件（
.sop.md
），定义了以下内容：
  • 明确目标及详细概述
  • 参数化输入以支持灵活复用
  • 带RFC 2119约束的分步指令
  • 示例与故障排除方案以保障可靠执行
  • 多模态分发（MCP工具、Anthropic Skills、Python模块）

Key Features

关键特性

RFC 2119 Constraints: Use standardized keywords (MUST, SHOULD, MAY) to provide precise control over agent behavior without rigid scripting.
Parameterization: Accept parameters that customize behavior for different projects, teams, or requirements.
Resumability: Document progress as agents work, making it easy to understand and resume if interrupted.
RFC 2119约束：使用标准化关键词（MUST、SHOULD、MAY），无需僵化脚本即可精准控制Agent行为。
参数化：支持自定义参数，以适配不同项目、团队或需求。
可恢复性：记录Agent的工作进度，便于理解和中断后恢复。

Creating Agent SOPs

创建Agent SOP

File Location

文件位置

You MUST check for an 
agent-sops/
directory in the current working directory:
  • If 
    agent-sops/
    exists, You MUST write the SOP file there
  • If 
    agent-sops/
    does not exist, You MAY write the SOP in the current directory or ask the user where to save it
你必须检查当前工作目录中是否存在
agent-sops/
目录：
  • 若
    agent-sops/
    已存在，你必须将SOP文件写入该目录
  • 若
    agent-sops/
    不存在，你可以将SOP写入当前目录，或询问用户保存位置

File Naming

文件命名

You MUST follow these naming conventions:
  • Use 
    .sop.md
    file extension
  • Use kebab-case for filenames (e.g., 
    code-assist.sop.md
    , 
    idea-honing.sop.md
    )
  • Choose descriptive names that indicate the SOP's purpose
你必须遵循以下命名规范：
  • 使用
    .sop.md
    文件扩展名
  • 文件名采用短横线分隔（kebab-case），例如
    code-assist.sop.md
    、
    idea-honing.sop.md
  • 选择能体现SOP用途的描述性名称

Validation

验证

You MUST run validate-sop.sh after EVERY change:
The validation script is located in the same directory as this SKILL.md file. When you read this skill, you will know the full path to SKILL.md, and the validation script is in that same directory.
bash
<skill-directory>/validate-sop.sh path/to/your-sop.sop.md
You MUST fix all errors (❌) before proceeding. You SHOULD address warnings (⚠️) when possible.
每次修改后，你必须运行validate-sop.sh脚本：
验证脚本与本SKILL.md文件位于同一目录。当你阅读本技能时，即可知晓SKILL.md的完整路径，验证脚本就在该路径下。
bash
<skill-directory>/validate-sop.sh path/to/your-sop.sop.md
你必须先修复所有错误（❌），才能继续操作。若有警告（⚠️），你应该尽可能解决。

Required Structure

必填结构

Every Agent SOP MUST include these sections in order:
markdown
undefined
每个Agent SOP必须按以下顺序包含这些章节：
markdown
undefined

[SOP Name]

[SOP名称]

Overview

概述

[Concise description of what the SOP does and when to use it]
[SOP功能及适用场景的简洁描述]

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
  • required_param（必填）：描述
  • optional_param（可选，默认值："value"）：描述
参数获取约束：
  • 若已提供所有必填参数，你必须直接进入步骤环节
  • 若缺少任何必填参数，你必须先询问用户获取
  • 询问参数时，你必须在单次提示中请求所有所需参数
  • 询问参数时，你必须使用定义好的准确参数名

Steps

步骤

1. [Step Name]

1. [步骤名称]

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]
undefined
[常见问题及解决方案]
undefined

Parameters Section

参数章节

You MUST define parameters using this format:
markdown
undefined
你必须使用以下格式定义参数：
markdown
undefined

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

**Parameter naming rules:**
- You **MUST** use lowercase letters
- You **MUST** use underscores for spaces (snake_case)
- You **MUST** be descriptive of purpose
- You **MUST** list required parameters before optional ones

**The Constraints for parameter acquisition section:**
- You **MUST** include this section in every Parameters section
- You **MUST** include these directives:
  - "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 **MAY** add additional constraints for flexible input methods:

```markdown
**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
  • parameter_name（必填）：必填输入的描述
  • another_param（必填）：描述
  • optional_param（可选）：可选输入的描述
  • with_default（可选，默认值："default_value"）：描述
参数获取约束：
  • 若已提供所有必填参数，你必须直接进入步骤环节
  • 若缺少任何必填参数，你必须先询问用户获取
  • 询问参数时，你必须在单次提示中请求所有所需参数
  • 询问参数时，你必须使用定义好的准确参数名

**参数命名规则：**
- 你必须使用小写字母
- 你必须使用下划线分隔空格（snake_case）
- 你必须使用能体现用途的描述性名称
- 你必须先列出必填参数，再列出可选参数

**参数获取约束章节：**
- 你必须在每个参数章节中包含此部分
- 你必须包含以下指令：
  - "若已提供所有必填参数，你必须直接进入步骤环节"
  - "若缺少任何必填参数，你必须先询问用户获取"
  - "询问参数时，你必须在单次提示中请求所有所需参数"
  - "询问参数时，你必须使用定义好的准确参数名"
- 你可以添加针对灵活输入方式的额外约束：

```markdown
**参数获取约束：**
- 若已提供所有必填参数，你必须直接进入步骤环节
- 若缺少任何必填参数，你必须先询问用户获取
- 询问参数时，你必须在单次提示中请求所有所需参数
- 询问参数时，你必须使用定义好的准确参数名
- 你必须支持多种输入方式，包括：
  - 直接输入：直接提供文本
  - 文件路径：本地文件路径
  - URL：内部资源链接
- 你必须使用合适的工具访问内容
- 你必须在继续前确认参数已成功获取
- 你应该将获取的数据保存到统一位置

Steps Section

步骤章节

You MUST structure steps with:
  1. Numbered heading (### 1., ### 2., etc.)
  2. Step name
  3. Natural language description
  4. Constraints: section with RFC 2119 keywords
Example:
markdown
undefined
你必须按以下结构组织步骤：
  1. 带编号的标题（### 1.、### 2.等）
  2. 步骤名称
  3. 自然语言描述
  4. 包含RFC 2119关键词的**约束：**章节
示例：
markdown
undefined

1. Setup

1. 环境搭建

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

**For conditional logic:**

```markdown
初始化项目环境并创建必要的结构。
约束：
  • 你必须验证目录结构是否存在
  • 你必须创建缺失的目录
  • 若目录创建失败，你不得继续操作
  • 你应该记录所有搭建操作
  • 若提供了--force标志，你可以跳过验证

**条件逻辑示例：**

```markdown

3. Conditional Processing

3. 条件处理

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
undefined
若验证通过，则继续处理；否则，报告错误。
约束：
  • 你必须在继续前检查验证状态
  • 若验证通过，你必须处理数据
  • 若验证失败，你必须报告具体错误
  • 你不得使用无效数据继续操作
undefined

RFC 2119 Keywords

RFC 2119关键词

You MUST use these keywords as defined in RFC 2119:
  • MUST / REQUIRED: Absolute requirement
  • MUST NOT / SHALL NOT: Absolute prohibition
  • SHOULD / RECOMMENDED: Strong recommendation (may have valid reasons to ignore)
  • SHOULD NOT / NOT RECOMMENDED: Strong discouragement (may have valid reasons to accept)
  • MAY / OPTIONAL: Truly optional item
你必须按照RFC 2119中的定义使用以下关键词：
  • MUST / REQUIRED：绝对要求
  • MUST NOT / SHALL NOT：绝对禁止
  • SHOULD / RECOMMENDED：强烈推荐（存在合理理由时可忽略）
  • SHOULD NOT / NOT RECOMMENDED：强烈不建议（存在合理理由时可接受）
  • MAY / OPTIONAL：完全可选的内容

Negative Constraints

否定约束

You MUST provide context when using negative constraints:
Good (with context):
markdown
- 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
Bad (without context):
markdown
- You MUST NOT use ellipses
- You SHOULD NEVER delete Git files
- You MUST NOT run git push
Common contexts for negative constraints:
  • Technical limitations: "because the system cannot handle..."
  • Security risks: "since this could expose sensitive data..."
  • Data integrity: "as this could corrupt important information..."
  • User experience: "because users will be confused by..."
  • Compatibility: "since this breaks integration with..."
  • Performance: "as this could cause significant slowdowns..."
你必须在使用否定约束时提供上下文：
正确示例（带上下文）：
markdown
- 你不得使用省略号(...)，因为你的输出会被文本转语音工具朗读
- 你绝不能删除Git历史文件，因为这可能损坏仓库
- 你不得执行`git push`，因为这可能发布未审核的代码
错误示例（无上下文）：
markdown
- 你不得使用省略号
- 你绝不能删除Git文件
- 你不得执行git push
否定约束的常见上下文：
  • 技术限制："因为系统无法处理..."
  • 安全风险："因为这可能暴露敏感数据..."
  • 数据完整性："因为这可能损坏重要信息..."
  • 用户体验："因为用户会对...感到困惑"
  • 兼容性："因为这会破坏与...的集成"
  • 性能："因为这可能导致严重的性能下降..."

Examples Section

示例章节

You SHOULD include concrete examples showing:
  • Example input parameters
  • Expected output or behavior
  • Common usage patterns
markdown
undefined
你应该包含具体示例，展示：
  • 示例输入参数
  • 预期输出或行为
  • 常见使用模式
markdown
undefined

Examples

示例

Example 1: Basic Usage

示例1：基础使用

Input:
  • task_description: "Create user authentication system"
  • mode: "interactive"
Expected Behavior: Agent will guide through TDD workflow, creating tests first, then implementation.
输入：
  • task_description: "创建用户认证系统"
  • mode: "interactive"
预期行为： Agent将引导你通过TDD工作流，先编写测试，再实现功能。

Example 2: Automated Mode

示例2：自动化模式

Input:
  • task_description: "Fix bug in payment processing"
  • mode: "auto"
Expected Behavior: Agent will automatically implement fix following established patterns.
undefined
输入：
  • task_description: "修复支付处理中的bug"
  • mode: "auto"
预期行为： Agent将按照既定模式自动实现修复。
undefined

Troubleshooting Section

故障排除章节

You SHOULD include common issues and solutions:
markdown
undefined
你应该包含常见问题及解决方案：
markdown
undefined

Troubleshooting

故障排除

Parameter Validation Fails

参数验证失败

If parameter validation fails, check that:
  • All required parameters are provided
  • Parameter names use snake_case
  • Values match expected types
若参数验证失败，请检查：
  • 是否已提供所有必填参数
  • 参数名是否使用snake_case格式
  • 值是否符合预期类型

Step Execution Hangs

步骤执行停滞

If a step appears to hang:
  • Check for missing tool permissions
  • Verify file paths are accessible
  • Review constraint requirements
undefined
若某步骤出现停滞：
  • 检查是否缺少工具权限
  • 验证文件路径是否可访问
  • 查看约束要求
undefined

Interactive SOPs

交互式SOP

For SOPs requiring user interaction:
  1. You SHOULD clearly indicate when user interaction is expected
  2. You MUST specify how to handle user responses
  3. You SHOULD specify where to save interaction records
Example:
markdown
undefined
对于需要用户交互的SOP：
  1. 你应该明确指出何时需要用户交互
  2. 你必须说明如何处理用户响应
  3. 你应该指定交互记录的保存位置
示例：
markdown
undefined

2. Requirements Clarification

2. 需求澄清

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
undefined
引导用户通过问题完善初始想法。
约束：
  • 你必须一次提出一个问题
  • 你必须将每次问答追加到"idea-honing.md"
  • 你应该根据之前的回答调整后续问题
  • 你必须持续提问，直到收集到足够的细节
undefined

Best Practices

最佳实践

You SHOULD follow these practices when authoring SOPs:
  1. Keep steps focused: Each step should accomplish one clear objective
  2. Use clear constraints: Be specific about requirements vs recommendations
  3. Provide examples: Show concrete usage for complex workflows
  4. Natural language: Write descriptions that are easy to understand
  5. Minimize complexity: Avoid deeply nested conditional logic
  6. Specify artifacts: Include file paths for all created artifacts
  7. Test thoroughly: Validate SOPs work across different AI systems
  8. Document edge cases: Include troubleshooting for common issues
编写SOP时，你应该遵循以下实践：
  1. 步骤聚焦：每个步骤应完成一个明确的目标
  2. 约束清晰：明确区分要求与推荐内容
  3. 提供示例：为复杂工作流展示具体用法
  4. 自然语言：使用易于理解的描述
  5. 降低复杂度：避免深度嵌套的条件逻辑
  6. 指定产物：包含所有创建产物的文件路径
  7. 充分测试：验证SOP可在不同AI系统中运行
  8. 记录边缘情况：包含常见问题的故障排除方案

Quick Reference

快速参考

ElementFormatRequired
File extension
.sop.md
Yes
Title
# SOP Name
Yes
Overview
## Overview
Yes
Parameters
## Parameters
Yes
Steps
## Steps
with 
### N.
Yes
Constraints
**Constraints:**
with RFC 2119		Yes
Examples
## Examples
Recommended
Troubleshooting
## Troubleshooting
Recommended
元素格式是否必填
文件扩展名
.sop.md
是
标题
# SOP名称
是
概述
## 概述
是
参数
## 参数
是
步骤
## Steps
搭配 
### N.
是
约束
**Constraints:**
搭配RFC 2119关键词		是
示例
## 示例
推荐
故障排除
## 故障排除
推荐

Common Patterns

常见模式

Before: Unstructured Prompt

优化前：非结构化提示

markdown
Please implement a user authentication system using TDD.
Make sure to write tests first and follow best practices.
markdown
请使用TDD实现用户认证系统。
确保先写测试，遵循最佳实践。

After: Structured SOP

优化后：结构化SOP

markdown
undefined
markdown
undefined

Code Assist

代码辅助

Overview

概述

This SOP guides implementation using test-driven development.
本SOP引导你使用测试驱动开发实现功能。

Parameters

参数

  • task_description (required): Description of task
  • mode (optional, default: "interactive"): "interactive" or "auto"
  • task_description（必填）：任务描述
  • mode（可选，默认值："interactive"）："interactive"或"auto"

Steps

步骤

1. Setup

1. 环境搭建

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

2. 测试编写

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
undefined
根据需求编写测试。
约束：
  • 你必须先写测试，再实现功能
  • 你应该遵循已有的测试模式
  • 你可以添加额外的边缘情况测试
undefined

Common Mistakes

常见错误

Missing Context in Negative Constraints

否定约束缺少上下文

Problem: Using MUST NOT without explaining why. Fix: Always provide context: "You MUST NOT X because Y"
问题： 使用MUST NOT但未说明原因。 解决： 始终提供上下文："你不得X，因为Y"

Vague Parameter Descriptions

参数描述模糊

Problem: "input_data (required): The data" Fix: "input_data (required): JSON object containing user profile fields (name, email, role)"
问题： "input_data（必填）：数据" 解决： "input_data（必填）：包含用户资料字段（姓名、邮箱、角色）的JSON对象"

Mixing Requirement Levels

需求级别混淆

Problem: Using MUST for optional behaviors or MAY for critical requirements. Fix: Use RFC 2119 keywords precisely - MUST for absolute requirements, SHOULD for recommendations, MAY for optional.
问题： 对可选行为使用MUST，或对关键要求使用MAY。 解决： 精准使用RFC 2119关键词——MUST用于绝对要求，SHOULD用于推荐，MAY用于可选内容。

Missing Examples

缺少示例

Problem: Complex workflow without concrete usage examples. Fix: Include at least one complete example showing input parameters and expected behavior.
问题： 复杂工作流未提供具体使用示例。 解决： 至少包含一个完整示例，展示输入参数和预期行为。

Overly Complex Steps

步骤过于复杂

Problem: Single step trying to accomplish multiple objectives with nested conditionals. Fix: Break into multiple focused steps, each with clear constraints.
问题： 单个步骤试图完成多个目标，包含嵌套条件逻辑。 解决： 将其拆分为多个聚焦的步骤，每个步骤都有清晰的约束。

Visual Workflow

可视化工作流

mermaid
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
mermaid
flowchart TD
    Start[创建SOP] --> Name[选择描述性名称]
    Name --> Structure[添加必填章节]
    Structure --> Overview[编写概述]
    Overview --> Params[定义参数]
    Params --> Steps[创建带约束的步骤]
    Steps --> Examples[添加示例]
    Examples --> Troubleshoot[添加故障排除]
    Troubleshoot --> Validate[验证格式]
    Validate --> Test[通过AI Agent测试]
    Test --> Done[分发SOP]

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

The Bottom Line

核心总结

Agent SOPs transform complex workflows into reusable, shareable instructions that work across different AI systems. They use standardized markdown format with RFC 2119 constraints to provide precise control while preserving agent reasoning ability.
When creating SOPs, focus on clear structure, specific constraints with context, and concrete examples. Test thoroughly across different AI systems to ensure reliability.
Agent SOP将复杂工作流转换为可复用、可共享的指令，可在不同AI系统中运行。它们使用标准化Markdown格式和RFC 2119约束，在保留Agent推理能力的同时实现精准控制。
创建SOP时，应注重清晰的结构、带上下文的具体约束，以及具体示例。需在不同AI系统中充分测试，确保可靠性。