Agent Sop Author

Agent SOP Author

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.

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.)

Core Concepts

What is an 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, Agent Skills, Python modules)

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.

Creating Agent SOPs

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

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

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.

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

You MUST fix all errors (❌) before proceeding. You SHOULD address warnings (⚠️) when possible.

Required Structure

Every Agent SOP MUST include these sections in order:

# [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 Section

You MUST define parameters using this format:

## 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:

**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 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:

### 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

For conditional logic:

### 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 Keywords

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

Negative Constraints

You MUST provide context when using negative constraints:

Good (with context):

- 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):

- 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..."