Agent SOP

Natural language workflows that enable AI agents to perform complex, multi-step tasks with consistency and reliability.

Documentation ◆ Python SDK ◆ Tools ◆ Samples ◆ MCP Server ◆ Agent Builder

Agent SOPs

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. They transform complex processes into reusable, shareable workflows that work across different AI systems and teams.

Lovingly nicknamed "Strands Operating Procedures" by the team.

What are Agent SOPs?

Agent SOPs use a standardized format to define:

• Clear objectives with detailed overviews
• Parameterized inputs for flexible reuse across different contexts
• Step-by-step instructions with RFC 2119 constraints (MUST, SHOULD, MAY)
• Examples and troubleshooting for reliable execution
• Multi-modal distribution (MCP tools, Anthropic Skills, Python modules)

Example SOP Structure

# Code Assist

## Overview
This SOP guides the implementation of code tasks using test-driven development 
principles, following a structured Explore, Plan, Code, Commit workflow.

## Parameters
- **task_description** (required): Description of the task to be implemented
- **mode** (optional, default: "interactive"): "interactive" or "fsc" (Full Self-Coding)

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

**Constraints:**
- You MUST validate and create the documentation directory structure
- You MUST discover existing instruction files using find commands
- You MUST NOT proceed if directory creation fails

### 2. Explore Phase
[Additional steps with specific constraints...]

Available SOPs

SOP	Purpose	Use Cases
codebase-summary	Comprehensive codebase analysis and documentation generation	Project onboarding, documentation creation, system understanding
pdd	Prompt-driven development methodology	Complex problem solving, architectural decisions, system design
code-task-generator	Intelligent task breakdown and planning from requirements	Project planning, sprint preparation, requirement analysis
code-assist	TDD-based code implementation with structured workflow	Feature development, bug fixes, refactoring

Quick Start

Install the strands-agents-sops package:

pip install strands-agents-sops

Using with Strands Agents

Install strands agents and the sops package:

pip install strands-agents strands-agents-tools strands-agents-sops

Create a simple cli coding agent:

from strands import Agent
from strands_tools import editor, shell
from strands_agents_sops import code_assist

agent = Agent(
  system_prompt=code_assist,
  tools=[editor, shell]
)

agent("Start code-assist sop")

while(True):
  agent(input("\nInput: "))

Using as MCP Server

The MCP (Model Context Protocol) server exposes SOPs as tools that AI assistants can discover and execute on-demand:

# Install the package
pip install strands-agents-sops

# Start MCP server with built-in SOPs only
strands-agents-sops mcp

# Load external SOPs from custom directories (sops in path must have `.sop.md` postfix)
strands-agents-sops mcp --sop-paths ~/my-sops:/path/to/other-sops

# External SOPs override built-in SOPs with same name
strands-agents-sops mcp --sop-paths ~/custom-sops  # Your custom code-assist.sop.md overrides built-in

External SOP Loading

The --sop-paths argument allows you to extend the MCP server with your own SOPs:

• File format: Only files with .sop.md postfix are recognized as SOPs
• Colon-separated paths: ~/sops1:/absolute/path:relative/path
• Path expansion: Supports ~ (home directory) and relative paths
• First-wins precedence: External SOPs override built-in SOPs with same name
• Graceful error handling: Invalid paths or malformed SOPs are skipped with warnings

Example workflow:

# Create your custom SOP
mkdir ~/my-sops
cat > ~/my-sops/custom-workflow.sop.md << 'EOF'
# Custom Workflow
## Overview
My custom workflow for specific tasks.
## Steps
### 1. Custom Step
Do something custom.
EOF

# Start MCP server with your custom SOPs
strands-agents-sops mcp --sop-paths ~/my-sops

Then connect your MCP-compatible AI assistant to access SOPs as tools. Here is an example mcp server configuration:

{
  "mcpServers": {
    "agent-sops": {
      "command": "strands-agents-sops",
      "args": ["mcp", "--sop-paths", "~/my-sops"]
    }
  }
}

---

Anthropic Skills Integration

Agent SOPs are fully compatible with Claude's Skills system, allowing you to teach Claude specialized workflows that can be reused across conversations and projects.

How SOPs Work as Skills

The key value of using SOPs as Skills is progressive disclosure of context. Instead of loading all workflow instructions into Claude's context upfront, you can provide many SOP skills to Claude, and Claude will intelligently decide which ones to load and execute based on the task at hand.

This approach offers several advantages:

• Context Efficiency: Only relevant workflow instructions are loaded when needed
• Scalable Expertise: Provide dozens of specialized workflows without overwhelming the context
• Intelligent Selection: Claude automatically chooses the most appropriate SOP for each task
• Dynamic Loading: Complex workflows are only activated when Claude determines they're useful

For example, you might provide Claude with all Agent SOPs as skills. When asked to "implement user authentication," Claude would automatically select and load the code-assist skill. When asked to "document this codebase," it would choose the codebase-summary skill instead.

Converting SOPs to Skills

Each Agent SOP can be automatically converted to Anthropic's Skills format:

# Generate Skills format from built-in SOPs only
strands-agents-sops skills

# Or specify custom output directory
strands-agents-sops skills --output-dir my-skills

# Load external SOPs from custom directories
strands-agents-sops skills --sop-paths ~/my-sops:/path/to/other-sops

# External SOPs override built-in SOPs with same name
strands-agents-sops skills --sop-paths ~/custom-sops --output-dir ./skills

External SOP Loading

The --sop-paths argument allows you to extend skills generation with your own SOPs:

• File format: Only files with .sop.md postfix are recognized as SOPs
• Colon-separated paths: ~/sops1:/absolute/path:relative/path
• Path expansion: Supports ~ (home directory) and relative paths
• First-wins precedence: External SOPs override built-in SOPs with same name
• Graceful error handling: Invalid paths or malformed SOPs are skipped with warnings

Example workflow:

# Create your custom SOP
mkdir ~/my-sops
cat > ~/my-sops/custom-workflow.sop.md << 'EOF'
# Custom Workflow
## Overview
My custom workflow for specific tasks.
## Steps
### 1. Custom Step
Do something custom.
EOF

# Generate skills with your custom SOPs
strands-agents-sops skills --sop-paths ~/my-sops --output-dir ./skills

This creates individual skill directories:

skills/
├── code-assist/
│   └── SKILL.md
├── codebase-summary/
│   └── SKILL.md
├── code-task-generator/
│   └── SKILL.md
└── pdd/
    └── SKILL.md

Using Skills in Claude

Claude.ai

1. Navigate to your Claude.ai account
2. Go to Skills settings
3. Upload the generated SKILL.md files
4. Reference skills in conversations: "Use the code-assist skill to implement user authentication"

Claude API

# Upload skill via API
skill_content = open('skills/code-assist/SKILL.md').read()
skill = client.skills.create(
    name="code-assist",
    content=skill_content
)

# Use skill in conversation
response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    skills=[skill.id],
    messages=[{
        "role": "user", 
        "content": "Use the code-assist skill to implement a user authentication system"
    }]
)

Claude Code

Install skills as plugins in Claude Code:

# Add this repository as a marketplace
/plugin marketplace add strands-agents/agent-sop

# Install skills
/plugin install example-skills@agent-sop

Skill Format

Each generated skill includes proper frontmatter and instructions:

---
name: code-assist
description: TDD-based code implementation with structured Explore, Plan, Code, Commit workflow
---

# Code Assist

This skill guides the implementation of code tasks using test-driven development 
principles, following a structured workflow that balances automation with user 
collaboration while adhering to existing package patterns.

[Full SOP instructions follow...]

---

What Are Agent SOPs?

Agent SOPs use a standardized markdown format with key features that enable repeatable and understandable behavior from AI agents:

1. Structured steps with RFC 2119 constraints - Each workflow step uses RFC 2119 keywords like MUST, SHOULD, and MAY to provide precise control over agent behavior without rigid scripting, ensuring reliable execution while preserving the agent's reasoning ability.
2. Parameterized inputs - Rather than hardcoding specific values, SOPs accept parameters that customize behavior for different projects, teams, or requirements. This transforms single-use prompts into flexible templates that can be applied broadly while maintaining consistency.
3. Easy authoring through AI assistance - Teams can create new SOPs in minutes. Coding agents can read the SOP format specification and generate new workflows based on natural language descriptions, making the creation process accessible to anyone regardless of prompt engineering expertise.
4. Progress tracking and resumability - Agent SOPs can instruct agents to document their progress as they work, making it easy to understand what's happening and resume if something breaks. This transparency was crucial for debugging prompts and building developer trust in AI automation.

Creating Agent SOPs

Authoring with AI Agents

Agent SOPs can be authored in minutes using your favorite AI agent and the standard formatting rule. You can either copy the rule directly from this repo or use strands-agents-sops rule:

# Output the Agent SOP format rule
strands-agents-sops rule

The rule can be used in various AI coding agents:

1. Kiro - Copy into your home directory or project as .kiro/steering/agent-sop-format.md.
2. Amazon Q Developer - Copy into your project as .amazonq/rules/agent-sop-format.md.
3. Claude Code - Instruct Claude Code to read the rule file.
4. Cursor - Copy into your project as .cursor/rules/agent-sop-format.mdc (Note the .mdc file extension).
5. Cline - Copy into your project as .clinerules/agent-sop-format.md.

Basic Structure

# SOP Name

## Overview
Brief description of what this SOP accomplishes and when to use it.

## Parameters
- **required_param** (required): Description of required input
- **optional_param** (optional, default: value): Description with default

## Steps
### 1. Step Name
Description of what this step accomplishes.

**Constraints:**
- You MUST perform required actions
- You SHOULD follow recommended practices
- You MAY include optional enhancements

## Examples
Concrete usage examples showing input and expected outcomes.

## Troubleshooting
Common issues and their solutions.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Security

See CONTRIBUTING for more information.