Agent SOPs

https://github.com/strands-agents/agent-sop
Admin
Agent SOPs are natural language workflows and markdown-based instruction sets that enable AI agents...
Tokens:50,826
Snippets:405
Trust Score:7.8
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and run MCP server

Source: https://github.com/strands-agents/agent-sop/blob/main/python/README.md

Install the package and start the MCP server with built-in or external SOPs.

```bash
# Install and run MCP server
pip install strands-agents-sops

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

--------------------------------

### Setup development environment

Source: https://github.com/strands-agents/agent-sop/blob/main/python/README.md

Navigate to the python directory and install development dependencies.

```bash
# Navigate to python directory
cd python

# Install development dependencies
pip install hatch
```

--------------------------------

### Example Input: Rough Idea and Project Name

Source: https://github.com/strands-agents/agent-sop/blob/main/agent-sops/pdd.sop.md

Provides a sample input for the agent SOP, containing a rough idea description and a project name. This is the starting point for the agent's transformation process.

```text
Rough idea: I want to build a feature for our team's internal tool that allows users to create and manage templates for common documents we produce. Users should be able to create, edit, and share templates, as well as use them to generate new documents with custom fields.

Project name: template-feature
```

--------------------------------

### Install agent-sop-author skill

Source: https://github.com/strands-agents/agent-sop/blob/main/README.md

Install the agent-sop-author skill using either the Vercel Skills CLI or the Claude Code marketplace. After installation, ask your agent to create a new SOP and it will use the skill to guide the process.

```bash
# Install via Vercel Skills CLI
npx skills add https://github.com/strands-agents/agent-sop/tree/skills-dist

# Or install via Claude Code marketplace
claude plugin marketplace add strands-agents/agent-sop
claude plugin install agent-sops@agent-sop
```

--------------------------------

### Install Dependencies with uv

Source: https://github.com/strands-agents/agent-sop/blob/main/agent-sops/eval.sop.md

Create a virtual environment and install dependencies using the uv package manager.

```bash
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt
```

--------------------------------

### Define SOP Examples

Source: https://github.com/strands-agents/agent-sop/blob/main/rules/agent-sop-format.md

The structure for providing example inputs and outputs.

```markdown
## Examples

### Example Input
```
[Example input]
```

### Example Output
```
[Example output]
```
```

--------------------------------

### Interactive SOP Requirements Clarification Example

Source: https://github.com/strands-agents/agent-sop/blob/main/rules/agent-sop-format.md

An example of an interactive SOP section that guides users through questions, enforces constraints on interaction, and specifies a file for logging responses.

```markdown
### 2. Requirements Clarification

Guide the user through a series of questions to refine their initial idea.

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

--------------------------------

### Example Input (PDD Mode)

Source: https://github.com/strands-agents/agent-sop/blob/main/agent-sops/code-task-generator.sop.md

Shows the input format for PDD mode, specifying the path to a plan file.

```text
input: ".agents/planning/my-project/implementation/plan.md"
```

--------------------------------

### Examples Section Template

Source: https://github.com/strands-agents/agent-sop/blob/main/skills/agent-sop-author/SKILL.md

Template for documenting input parameters and expected behavior for agent tasks.

```markdown
## 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.
```

--------------------------------

### Examples of good negative constraints with context

Source: https://github.com/strands-agents/agent-sop/blob/main/rules/agent-sop-format.md

These examples demonstrate how to provide necessary context for negative constraints to ensure clarity and understanding.

```markdown
- You MUST NOT use ellipses (...) in responses because your output will be read aloud by a text-to-speech engine, and the engine cannot properly pronounce ellipses
- You SHOULD NEVER delete Git history files since this could corrupt the repository and make recovery impossible
- You MUST NOT run `git push` because this could publish unreviewed code to shared repositories where others depend on it
```

--------------------------------

### Example Input (Description Mode)

Source: https://github.com/strands-agents/agent-sop/blob/main/agent-sops/code-task-generator.sop.md

Shows the input format for description mode, specifying a task description and output directory.

```text
input: "I need a function that validates email addresses and returns detailed error messages"
output_dir: ".agents/tasks/my-project"
```

--------------------------------

### Install strands agents and sops package

Source: https://github.com/strands-agents/agent-sop/blob/main/README.md

Install strands agents and the sops package together. Requires the strands-agents-sops package to be installed first (see Quick Start).

```bash
brew install strands-agents-sops
pip install strands-agents strands-agents-tools
```

--------------------------------

### Example Output (Description Mode)

Source: https://github.com/strands-agents/agent-sop/blob/main/agent-sops/code-task-generator.sop.md

Shows the expected output when running in description mode, including the detected mode, generated task file, and next steps.

```text
Detected mode: description

Generated code task: .agents/tasks/my-project/email-validator.code-task.md

Created task for email validation functionality with comprehensive acceptance criteria and implementation guidance.

Next steps: Run code-assist on the generated task to implement the solution.
```

--------------------------------

### Install skills via Claude Code marketplace

Source: https://github.com/strands-agents/agent-sop/blob/main/README.md

Install Agent SOPs as Claude Code plugins via the marketplace. After installation, skills are available as slash commands: /code-assist, /pdd, /codebase-summary, /code-task-generator, /eval, /agent-sop-author.

```bash
# Add the marketplace
claude plugin marketplace add strands-agents/agent-sop

# Install all agent SOPs
claude plugin install agent-sops@agent-sop

# Skills available as /code-assist, /pdd, /codebase-summary, /code-task-generator, /eval, /agent-sop-author
```

--------------------------------

### Define Examples Section

Source: https://github.com/strands-agents/agent-sop/blob/main/spec/agent-sops-specification.md

The optional examples section for providing sample input and expected output.

```markdown
## Examples

### Example Input
[Sample input]

### Example Output
[Expected output]
```

--------------------------------

### Example Output (PDD Mode)

Source: https://github.com/strands-agents/agent-sop/blob/main/agent-sops/code-task-generator.sop.md

Shows the expected output when running in PDD mode, including the detected mode, generated task files, and next steps.

```text
Detected mode: pdd

Generated code tasks for step 2: .agents/tasks/my-project/step02/

Created tasks:
- task-01-create-data-models.code-task.md
- task-02-implement-validation.code-task.md  
- task-03-add-serialization.code-task.md

Next steps: Run code-assist on each task in sequence

Step demo: Working data models with validation that can create, validate, and serialize/deserialize data objects
```

--------------------------------

### Example Cursor command invocation and parameter prompt

Source: https://github.com/strands-agents/agent-sop/blob/main/README.md

Example interaction in Cursor chat showing how to invoke a command with /code-assist.sop and provide required parameters. The AI prompts for parameters because Cursor doesn't support explicit parameter passing.

```text
You: /code-assist.sop

AI: I'll help you implement code using the code-assist workflow. 
    Please provide the following required parameters:
    - task_description: [description of the task]
    - mode (optional, default: "auto"): "interactive" or "auto"
    
You: task_description: "Create a user authentication system"
     mode: "interactive"
```

--------------------------------

### Start MCP server with strands-agents-sops

Source: https://github.com/strands-agents/agent-sop/blob/main/AGENTS.md

Start the MCP server with built-in SOPs, or include custom SOPs using --sop-paths. Custom SOP files must have a .sop.md postfix.

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

# Include custom SOPs (sops in path must have `.sop.md` postfix)
strands-agents-sops mcp --sop-paths ~/my-sops:/team/sops
```

--------------------------------

### Install Strands Agents packages

Source: https://github.com/strands-agents/agent-sop/blob/main/python/README.md

Install the required packages for using Strands Agents with SOPs.

```bash
pip install strands-agents strands-agents-tools strands-agents-sops
```

--------------------------------

### Python integration with strands_agents_sops

Source: https://github.com/strands-agents/agent-sop/blob/main/AGENTS.md

Python integration example: create an Agent with the code_assist SOP as system prompt and tools, then execute the SOP.

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

# Create agent with SOP as system prompt
agent = Agent(
    system_prompt=code_assist,
    tools=[editor, shell]
)

# Execute SOP
agent("Start code-assist sop")
```

--------------------------------

### Iterative Refinement Example

Source: https://github.com/strands-agents/agent-sop/blob/main/agent-sops/eval.sop.md

Demonstrates how to iteratively update the evaluation plan and test cases based on user feedback.

```text
User: "Create an evaluation plan for my agent at ./my-agent"
Assistant: [Creates initial plan in eval/eval-plan.md]

User: "Add more focus on error handling"
Assistant: "I'll update the evaluation plan to include error handling metrics..."
[Updates eval/eval-plan.md]

User: "Generate test cases with more edge cases"
Assistant: "I'll generate test cases with additional edge case coverage..."
[Updates eval/test-cases.jsonl]
```

--------------------------------

### Example Evaluation Input Configuration

Source: https://github.com/strands-agents/agent-sop/blob/main/agent-sops/eval.sop.md

Defines the agent path and evaluation focus parameters for the evaluation process.

```yaml
agent_path: "./chatbot-agent"
evaluation_focus: "response quality and tool calling accuracy"
```

--------------------------------

### Unstructured Prompt Example

Source: https://github.com/strands-agents/agent-sop/blob/main/skills/agent-sop-author/SKILL.md

An example of an unstructured prompt that lacks clear parameters and constraints.

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

--------------------------------

### Create custom SOP and generate skills

Source: https://github.com/strands-agents/agent-sop/blob/main/README.md

Example workflow for creating a custom SOP file and generating skills from it. Only files with .sop.md postfix are recognized. Invalid paths or malformed SOPs are skipped with warnings.

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

--------------------------------

### Example Output: Research Phase and Project Summary

Source: https://github.com/strands-agents/agent-sop/blob/main/agent-sops/pdd.sop.md

Shows the agent's output for the given input, including a research phase interaction and a project summary with directory structure, key design elements, implementation approach, and next steps.

```text
# Research Phase Interaction

Based on your requirements, I've identified several areas that would benefit from research:

1. **Existing template solutions** - Understanding what's already available
2. **Storage and versioning approaches** - How to handle template versions and sharing
3. **Custom field validation patterns** - Best practices for dynamic field validation

I notice you have several additional MCP search tools available beyond the standard ones, including 'peccy web search' and other external search capabilities. Should I incorporate these additional search tools into the research process for broader coverage of template management solutions and industry best practices?

---

# Project Summary

I've completed the transformation of your rough idea into a detailed design with an implementation plan. Here's what was created:

## Directory Structure
- .agents/planning/template-feature/
  - rough-idea.md (your initial concept)
  - idea-honing.md (our Q&A requirements clarification)
  - research/
    - existing-templates.md
    - storage-options.md
    - external-solutions.md
  - design/
    - detailed-design.md
  - implementation/
    - plan.md (includes implementation checklist)
  - summary.md (this document)

## Key Design Elements
- Template management system with CRUD operations
- Role-based access control for sharing
- Versioning system for templates
- Custom fields with validation
- Document generation engine

## Implementation Approach
The implementation plan breaks down the work into 12 incremental steps, starting with core data models and building up to the complete feature set.

## Next Steps
1. Review the detailed design document at .agents/planning/template-feature/design/detailed-design.md
2. Check the implementation plan and checklist at .agents/planning/template-feature/implementation/plan.md
3. Begin implementation following the checklist in the implementation plan

Would you like me to explain any specific part of the design or implementation plan in more detail?
```

--------------------------------

### Conditional Logic Step Example

Source: https://github.com/strands-agents/agent-sop/blob/main/skills/agent-sop-author/SKILL.md

Demonstrates how to structure steps that involve conditional processing logic.

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

--------------------------------

### SOP Step Structure Example

Source: https://github.com/strands-agents/agent-sop/blob/main/skills/agent-sop-author/SKILL.md

Demonstrates the required format for a step, including a numbered heading, name, description, and a constraints section using RFC 2119 keywords.

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

--------------------------------

### Install strands-agents-sops with Homebrew or pip

Source: https://github.com/strands-agents/agent-sop/blob/main/README.md

Install the strands-agents-sops package using either Homebrew or pip. The Homebrew command is shown first, with pip as an alternative.

```bash
# Using Homebrew
brew install strands-agents-sops

# Or using pip
pip install strands-agents-sops
```

--------------------------------

### Start MCP server with built-in or external SOPs

Source: https://github.com/strands-agents/agent-sop/blob/main/README.md

Start the MCP server with built-in SOPs only, or load external SOPs from custom directories using --sop-paths. External SOPs override built-in SOPs with the same name.

```bash
# Install the package (see Quick Start for pip alternative)
brew 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
```

--------------------------------

### Structured SOP Example

Source: https://github.com/strands-agents/agent-sop/blob/main/skills/agent-sop-author/SKILL.md

A structured version of the authentication system task, utilizing clear parameters, steps, and RFC 2119 constraints.

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

--------------------------------

### Install skills via Vercel Skills CLI

Source: https://github.com/strands-agents/agent-sop/blob/main/README.md

Install Agent SOPs as skills using the Vercel Skills CLI. This command adds the skills from the skills-dist branch.

```bash
npx skills add https://github.com/strands-agents/agent-sop/tree/skills-dist
```

--------------------------------

### Good Negative Constraint Example

Source: https://github.com/strands-agents/agent-sop/blob/main/spec/agent-sops-specification.md

An example of a properly formatted negative constraint including necessary context.

```markdown
- You MUST NOT delete files without confirmation because this could result in permanent data loss
```

--------------------------------

### Set up local skills for development

Source: https://github.com/strands-agents/agent-sop/blob/main/README.md

Set up local skills for development or testing. Clones the repository, installs the package, generates skills, and runs Claude Code with the plugin directory.

```bash
# Clone the repo
git clone https://github.com/strands-agents/agent-sop

# Generate local skills
cd agent-sop
pip install strands-agents-sops
strands-agents-sops skills --output-dir ./skills

# Run Claude Code with the plugin
claude --plugin-dir ./agent-sop
```

--------------------------------

### Examples of bad negative constraints without context

Source: https://github.com/strands-agents/agent-sop/blob/main/rules/agent-sop-format.md

These examples illustrate negative constraints that lack the required context, which should be avoided.

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

--------------------------------

### Default AGENTS.md Configuration

Source: https://github.com/strands-agents/agent-sop/blob/main/agent-sops/codebase-summary.sop.md

Example configuration for generating a consolidated AGENTS.md file with a specific prompt for AI navigation.

```yaml
output_dir: ".agents/summary"
consolidate: true
consolidate_targets: "AGENTS.md"
consolidate_prompt: "Create a concise AGENTS.md that provides a starting point for navigating the codebase. Document major subsystems, key entry points, and directory organization so agents can locate relevant code without reading every file. Include: (1) directory overview and component map, (2) repo-specific tools and scripts found in the codebase, (3) patterns that deviate from language/framework defaults, (4) information discoverable from config files (CI, linters, git hooks) that agents might otherwise miss. Do NOT include: exhaustive file-by-file directory listings, generic component descriptions that don't aid navigation, general programming best practices, volatile metrics like lines-of-code counts or file sizes, standard build/test/lint commands that are common to the language or framework, or fabricated acronyms. End with an empty 'Custom Instructions' section for human/agent-maintained conventions."
codebase_path: "/path/to/project"
```

--------------------------------

### MCP client configuration for agent-sops

Source: https://github.com/strands-agents/agent-sop/blob/main/AGENTS.md

Example MCP client configuration for the agent-sops server, specifying the command and arguments including custom SOP paths.

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

--------------------------------

### Generated .cursor/commands directory structure

Source: https://github.com/strands-agents/agent-sop/blob/main/README.md

Example output directory structure after generating Cursor commands. Shows the generated command files, including the custom-workflow.sop.md from the custom SOP.

```text
.cursor/commands/
├── code-assist.sop.md
├── codebase-summary.sop.md
├── code-task-generator.sop.md
├── pdd.sop.md
└── custom-workflow.sop.md
```

--------------------------------

### Negative Constraint Examples (Good vs Bad)

Source: https://github.com/strands-agents/agent-sop/blob/main/skills/agent-sop-author/SKILL.md

Compares well-formed negative constraints that include context against poorly formed ones that lack necessary justification.

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

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

--------------------------------

### Agent SOP skill format with frontmatter

Source: https://github.com/strands-agents/agent-sop/blob/main/README.md

Example of the standardized markdown format for an Agent SOP skill. Includes YAML frontmatter with the skill name and description, followed by the SOP instructions. Use this as a template when authoring new SOPs.

```markdown
---
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...]
```

--------------------------------

### Code Task Format Example: Create Email Validator Function

Source: https://github.com/strands-agents/agent-sop/blob/main/agent-sops/code-task-generator.sop.md

A complete example of a code task file for creating an email validator function. It demonstrates all required sections with concrete content.

```markdown
# Task: Create Email Validator Function

## Description
Create a function that validates email addresses and returns detailed error messages for invalid formats. This will be used across the application to ensure data quality and provide user-friendly feedback.

## Background
The application currently accepts any string as an email address, leading to data quality issues and failed communications. We need a robust validation function that can identify common email format errors and provide specific feedback to users.

## Reference Documentation
**Required:**
- Design: planning/design/detailed-design.md

**Additional References (if relevant to this task):**
- planning/research/validation-libraries.md (for email validation approach)

**Note:** You MUST read the detailed design document before beginning implementation. Read additional references as needed for context.

## Technical Requirements
1. Create a function that accepts an email string and returns validation results
2. Implement comprehensive email format validation using regex or email parsing library
3. Return detailed error messages for specific validation failures
4. Support common email formats including international domains
5. Include performance optimization for high-volume validation

## Dependencies
- Email validation library or regex patterns
- Error handling framework for structured error responses
- Unit testing framework for comprehensive test coverage

## Implementation Approach
1. Research and select appropriate email validation approach (regex vs library)
2. Implement core validation logic with specific error categorization
3. Add comprehensive error messaging for different failure types
4. Optimize for performance if needed for high-volume scenarios

## Acceptance Criteria

1. **Valid Email Acceptance**
   - Given a properly formatted email address
   - When the validation function is called
   - Then the function returns success with no errors

2. **Invalid Format Detection**
   - Given an email with invalid format (missing @, invalid characters, etc.)
   - When the validation function is called
   - Then the function returns failure with specific error message

3. **Detailed Error Messages**
   - Given various types of invalid emails
   - When validation fails
   - Then specific error messages are returned (e.g., "Missing @ symbol", "Invalid domain format")

4. **Performance Requirements**
   - Given 1000 email validations
   - When executed in sequence
   - Then all validations complete within 1 second

5. **Unit Test Coverage**
   - Given the email validator implementation
   - When running the test suite
   - Then all validation scenarios have corresponding unit tests with >90% coverage

## Metadata
- **Complexity**: Low
- **Labels**: Validation, Email, Data Quality, Utility Function
- **Required Skills**: Regular expressions, email standards, unit testing
```

--------------------------------

### Example SOP structure in Markdown

Source: https://github.com/strands-agents/agent-sop/blob/main/README.md

Shows the standardized structure of an Agent SOP document, including an overview, parameters with defaults, and steps with RFC 2119 constraints. Use this as a template when authoring new SOPs.

```markdown
# 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...]
```

--------------------------------

### Agent SOP basic structure

Source: https://github.com/strands-agents/agent-sop/blob/main/README.md

Basic structure for an Agent SOP document. Includes sections for Overview, Parameters, Steps with constraints, Examples, and Troubleshooting.

```markdown
# 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.
```

--------------------------------

### Required Agent SOP Structure

Source: https://github.com/strands-agents/agent-sop/blob/main/skills/agent-sop-author/SKILL.md

The mandatory template for all Agent SOP files, including sections for Overview, Parameters, Steps, Examples, and Troubleshooting.

```markdown
# [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]
```

--------------------------------

### SOP Format Structure

Source: https://github.com/strands-agents/agent-sop/blob/main/AGENTS.md

Standardized format for all SOP definitions, including sections for Overview, Parameters, Steps, Constraints, Examples, and Troubleshooting.

```markdown
# SOP Title

## 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
- You MUST NOT perform prohibited actions

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

## Troubleshooting
Common issues and their solutions.
```

--------------------------------

### Evaluation Plan Template for Agent

Source: https://github.com/strands-agents/agent-sop/blob/main/agent-sops/eval.sop.md

Template for creating an evaluation plan for an agent. It includes sections for requirements, agent analysis, metrics, test data, implementation design, and progress tracking. The template uses placeholders and comments to guide the user, and it specifies defaults such as 1-2 metrics and a maximum of 3 test scenarios.

```markdown
# Evaluation Plan for [AGENT NAME]

## 1. Evaluation Requirements

<!--
ACTION REQUIRED: User input and interpreted evaluation requirements. Defaults to 1-2 key metrics if unspecified.
-->

- **User Input:** `"$ARGUMENTS"` or "No Input"
- **Interpreted Evaluation Requirements:** [Parsed from user input - highest priority]

---

## 2. Agent Analysis

| **Attribute**         | **Details**                                                 |
| :-------------------- | :---------------------------------------------------------- |
| **Agent Name**        | [Agent name]                                                |
| **Purpose**           | [Primary purpose and use case in 1-2 sentences]             |
| **Core Capabilities** | [Key functionalities the agent provides]                    |
| **Input**             | [Short description, Data types, schemas]                    |
| **Output**            | [Short description, Response types, schemas]                |
| **Agent Framework**   | [e.g., CrewAI, LangGraph, AutoGen, Custom/None]             |
| **Technology Stack**  | [Programming language, frameworks, libraries, dependencies] |

**Agent Architecture Diagram:**

[Mermaid diagram illustrating:

- Agent components and their relationships
- Data flow between components
- External integrations (APIs, databases, tools)
- User interaction points]

**Key Components:**

- **[Component Name 1]:** [Brief description of purpose and functionality]
- **[Component Name 2]:** [Brief description of purpose and functionality]
- [Additional components as needed]

**Available Tools:**

- **[Tool Name 1]:** [Purpose and usage]
- **[Tool Name 2]:** [Purpose and usage]
- [Additional tools as needed]

**Observability Status**

- **Tracing Framework** [Fully/Partially/Not Instrumented, Framework name, version]
- **Custom Attributes** [Yes/No, Key custom attributes if present]

---

## 3. Evaluation Metrics

<!--
ACTION REQUIRED: If no specific user requirements are provided, use a minimal number of metrics (1-2 metrics) focusing on the most critical aspects of agent performance.
-->

### [Metric Name 1]

- **Evaluation Area:** [Final response quality/tool call accuracy/...]
- **Description:** [What is measured and why]
- **Method:** [Code-based | LLM-as-Judge ]

### [Metric Name 2]

[Repeat for each metric]

---

## 4. Test Data Generation

<!--
  ACTION REQUIRED: Keep scenarios minimal and focused. Do not propose more than 3 scenarios.
-->

- **[Test Scenario 1]**: [Description and purpose, complexity]
- **[Test scenario 2]**: [Description and purpose, complexity]
- **Total number of test cases**: [SHOULD NOT exceed 3]

---

## 5. Evaluation Implementation Design

### 5.1 Evaluation Code Structure

<!--
ACTION REQUIRED: The code structure below will be adjusted based on your evaluation requirements and existing agent codebase. This is the recommended starting structure. Only adjust it if necessary.
-->

./ # Repository root directory
├── requirements.txt # Consolidated dependencies
├── .venv/ # Python virtual environment (created by uv)
│
└── eval/ # Evaluation workspace
├── README.md # Running instructions and usage examples (always present)
├── run_evaluation.py # Strands Evals SDK evaluation implementation (always present)
├── results/ # Evaluation outputs (always present)
├── eval-plan.md # This evaluation specification and plan (always present)
└── test-cases.jsonl # Generated test cases (from evalkit.data)

### 5.2 Recommended Evaluation Technical Stack

| **Component**            | **Selection**                                                 |
| :----------------------- | :------------------------------------------------------------ |
| **Language/Version**     | [e.g., Python 3.11, Node.js 18+]                              |
| **Evaluation Framework** | [Strands Evals SDK (default)]                                 |
| **Evaluators**           | [OutputEvaluator, TrajectoryEvaluator, InteractionsEvaluator] |
| **Agent Integration**    | [e.g., Direct import, API]                                    |
| **Results Storage**      | [e.g., JSON files (default)]                                  |

---

## 6. Progress Tracking

### 6.1 User Requirements Log

| **Timestamp**      | **Phase** | **Requirement**                                                      |
| :----------------- | :-------- | :------------------------------------------------------------------- |
| [YYYY-MM-DD HH:MM] | Planning  | [User input from $ARGUMENTS, or "No specific requirements provided"] |

### 6.2 Evaluation Progress

| **Timestamp**      | **Component**    | **Status**                      | **Notes**                                      |
| :----------------- | :--------------- | :------------------------------ | :--------------------------------------------- |
| [YYYY-MM-DD HH:MM] | [Component name] | [In Progress/Completed/Blocked] | [Technical details, blockers, or achievements] |
```

--------------------------------

### Kiro CLI MCP config for built-in SOPs

Source: https://github.com/strands-agents/agent-sop/blob/main/README.md

Kiro CLI configuration for built-in SOPs only. Add this to ~/.kiro/settings/mcp.json. The agent-sops key is an example label; you can use a different name.

```json
{
  "mcpServers": {
    "agent-sops": {
      "command": "strands-agents-sops",
      "args": ["mcp"],
      "env": {}
    }
  }
}
```

--------------------------------

### Create custom SOP and generate Cursor commands with --sop-paths

Source: https://github.com/strands-agents/agent-sop/blob/main/README.md

Shows the full workflow for creating a custom SOP file and generating Cursor commands from it. Only files with .sop.md postfix are recognized, and the --sop-paths argument supports ~ and relative paths. Invalid paths or malformed SOPs are skipped with warnings.

```bash
# Create your custom SOP
mkdir ~/my-sops
cat > ~/my-sops/custom-workflow.sop.md << 'EOF'
# Custom Workflow
## Overview
My custom workflow for specific tasks.
## Parameters
- **task** (required): Description of task
## Steps
### 1. Custom Step
Do something custom.
EOF

# Generate Cursor commands with your custom SOPs
strands-agents-sops commands --type cursor --sop-paths ~/my-sops
```

--------------------------------

### Create and test custom SOPs with strands-agents-sops

Source: https://github.com/strands-agents/agent-sop/blob/main/AGENTS.md

Commands to create a custom SOP directory, write a custom SOP file following the format specification, test it with the MCP server using `strands-agents-sops mcp --sop-paths ~/my-sops`, and generate Skills including custom SOPs with `strands-agents-sops skills --sop-paths ~/my-sops --output-dir ./skills`.

```bash
# Create custom SOP directory
mkdir ~/my-sops

# Create custom SOP following format specification
cat > ~/my-sops/custom-workflow.sop.md << 'EOF'
# Custom Workflow
## Overview
My custom workflow for specific tasks.
## Parameters
- **task** (required): Description of task
## Steps
### 1. Custom Step
**Constraints:**
- You MUST follow the custom process
EOF

# Test with MCP server
strands-agents-sops mcp --sop-paths ~/my-sops

# Generate Skills including custom SOPs
strands-agents-sops skills --sop-paths ~/my-sops --output-dir ./skills
```

--------------------------------

### Check for requirements.txt

Source: https://github.com/strands-agents/agent-sop/blob/main/agent-sops/eval.sop.md

Verify the existence of the requirements.txt file in the repository root.

```bash
ls requirements.txt
```

--------------------------------

### Create custom SOP and use with MCP

Source: https://github.com/strands-agents/agent-sop/blob/main/python/README.md

Create a custom SOP file and use it with the MCP server.

```bash
# Create 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

# Use with MCP server
strands-agents-sops mcp --sop-paths ~/my-sops
```

--------------------------------

### Create an agent with SOPs

Source: https://github.com/strands-agents/agent-sop/blob/main/python/README.md

Create an agent using the Prompt-Driven Development SOP and with custom input.

```python
from strands import Agent
from strands_tools import shell, editor
import strands_agents_sops as sops

# Create an agent with the Prompt-Driven Development SOP
agent = Agent(
    system_prompt=sops.pdd,
    tools=[shell, editor]
)

# Use SOPs with custom input
agent = Agent(
    system_prompt=sops.pdd_with_input("Help me design a REST API"),
    tools=[shell, editor]
)
```

--------------------------------

### Kiro CLI: pin planning files with /context add

Source: https://github.com/strands-agents/agent-sop/blob/main/README.md

Kiro CLI command to pin relevant planning files for context while implementing a project. Use this to focus AI tools on useful reference docs.

```text
/context add .agents/planning/{project_name}/**/*.md

```

--------------------------------

### Create a CLI coding agent with code_assist SOP

Source: https://github.com/strands-agents/agent-sop/blob/main/README.md

Create a simple CLI coding agent using the code_assist SOP. The agent is initialized with the code_assist system prompt and editor/shell tools, then runs an interactive loop.

```python
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: "))
```

--------------------------------

### Define Parameter Acquisition Constraints

Source: https://github.com/strands-agents/agent-sop/blob/main/rules/agent-sop-format.md

Guidelines for handling flexible input methods and parameter validation.

```markdown
## Parameters

- **input_data** (required): The data to be processed.

**Constraints for parameter acquisition:**
- You MUST ask for all required parameters upfront in a single prompt rather than one at a time
- You MUST support multiple input methods including:
  - Direct input: Text provided directly in the conversation
  - File path: Path to a local file
  - URL: Link to an internal resource
  - Other methods: You SHOULD be open to other ways the user might want to provide the data
- You MUST use appropriate tools to access content based on the input method
- You MUST confirm successful acquisition of all parameters before proceeding
- You SHOULD save any acquired data to a consistent location for use in subsequent steps
```

--------------------------------

### Create evaluation directory structure

Source: https://github.com/strands-agents/agent-sop/blob/main/agent-sops/eval.sop.md

Command to create the required evaluation directory.

```bash
mkdir -p eval
```

--------------------------------

### Run tests with hatch

Source: https://github.com/strands-agents/agent-sop/blob/main/AGENTS.md

Run tests for the Python package using hatch. Navigate to the python directory first.

```bash
# Navigate to python package directory
cd python

# Use hatch to run manages testing environment
hatch test
```

--------------------------------

### Define SOP Parameters

Source: https://github.com/strands-agents/agent-sop/blob/main/rules/agent-sop-format.md

The standard format for listing required and optional parameters.

```markdown
## Parameters

- **required_param** (required): [Description of the required parameter]
- **another_required** (required): [Description of another required parameter]
- **optional_param** (optional): [Description of the optional parameter]
- **optional_with_default** (optional, default: "default_value"): [Description]
```

--------------------------------

### Navigate to evaluation project directory

Source: https://github.com/strands-agents/agent-sop/blob/main/agent-sops/eval.sop.md

Command to change the current working directory to the project folder containing both the agent and the evaluation directory.

```bash
cd <your-evaluation-project>  # Navigate to the directory containing both agent folder and eval/
```

--------------------------------

### Run tests with coverage

Source: https://github.com/strands-agents/agent-sop/blob/main/python/README.md

Run all tests with coverage using hatch.

```bash
# Run all tests with coverage
hatch test
```

--------------------------------

### Generate Agent Skills with strands-agents-sops

Source: https://github.com/strands-agents/agent-sop/blob/main/AGENTS.md

Generate Agent Skills format using strands-agents-sops, optionally including custom SOPs with --sop-paths.

```bash
# Generate Agent Skills format
strands-agents-sops skills --output-dir ./skills

# Include custom SOPs in Skills generation
strands-agents-sops skills --sop-paths ~/my-sops --output-dir ./skills
```

--------------------------------

### README.md Consolidation Configuration

Source: https://github.com/strands-agents/agent-sop/blob/main/agent-sops/codebase-summary.sop.md

Configuration snippet for targeting the README.md file for consolidation.

```yaml
consolidate_targets: "README.md"
consolidate_prompt: "Create a user-friendly README that explains the project purpose, installation, and usage"
```

--------------------------------

### Visual Workflow Diagram for Creating an Agent SOP

Source: https://github.com/strands-agents/agent-sop/blob/main/skills/agent-sop-author/SKILL.md

Mermaid flowchart showing the step-by-step process of creating an Agent SOP, from choosing a name to distributing the final SOP. The 'Validate format' step is highlighted in red, indicating it requires extra attention.

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

--------------------------------

### Project Directory Structure

Source: https://github.com/strands-agents/agent-sop/blob/main/AGENTS.md

Shows the project layout for the Agent SOP package, including the main Python package, source SOP definitions, tests, spec, and rules directories.

```text
agent-sop/
├── python/strands_agents_sops/    # Main Python package
│   ├── __main__.py               # CLI entry point (mcp|skills|rule commands)
│   ├── mcp.py                    # MCP server implementation
│   ├── skills.py                 # Agent Skills conversion
│   └── utils.py                  # Shared SOP utilities
├── agent-sops/                   # Source SOP definitions
│   ├── codebase-summary.sop.md   # Documentation generation workflow
│   ├── code-assist.sop.md        # TDD implementation workflow
│   ├── code-task-generator.sop.md # Task breakdown workflow
│   └── pdd.sop.md               # Prompt-driven development workflow
├── python/tests/                 # Comprehensive test suite
├── spec/                         # SOP format specification
└── rules/                        # SOP authoring guidelines
```

--------------------------------

### Define SOP Troubleshooting

Source: https://github.com/strands-agents/agent-sop/blob/main/rules/agent-sop-format.md

The format for documenting common issues and their resolutions.

```markdown
## Troubleshooting

### [Common Issue]
If [issue description], you should [resolution steps].

### [Another Issue]
[Description and resolution]
```

--------------------------------

### Documentation Output Structure

Source: https://github.com/strands-agents/agent-sop/blob/main/agent-sops/codebase-summary.sop.md

The expected directory structure created by the tool after generation.

```text
AGENTS.md (consolidated file in root directory)
.agents/summary/
├── index.md (knowledge base index)
├── codebase_info.md
├── architecture.md
├── components.md
├── interfaces.md
├── data_models.md
├── workflows.md
├── dependencies.md
└── review_notes.md
```

--------------------------------

### Generate Agent Skills with strands-agents-sops skills

Source: https://github.com/strands-agents/agent-sop/blob/main/README.md

Generate Agent Skills from built-in or external SOPs. Use --output-dir to set the output directory, --sop-paths to load external SOPs (colon-separated paths, supports ~ and relative paths). External SOPs override built-in SOPs with the same name.

```bash
# Generate Agent Skills 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
```

--------------------------------

### Define Steps Section

Source: https://github.com/strands-agents/agent-sop/blob/main/spec/agent-sops-specification.md

The required steps section containing instructions and RFC 2119 constraints.

```markdown
## Steps

### 1. Step Name

Natural language description of what happens in this step.

**Constraints:**
- You MUST perform specific action
- You SHOULD consider certain factors
- You MAY optionally do something else
```

--------------------------------

### Extended Parameter Acquisition Constraints

Source: https://github.com/strands-agents/agent-sop/blob/main/skills/agent-sop-author/SKILL.md

An optional, more detailed set of constraints for parameter acquisition that supports multiple 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
```

--------------------------------

### Define Parameters Section

Source: https://github.com/strands-agents/agent-sop/blob/main/spec/agent-sops-specification.md

The required parameters section defining inputs, requirements, and default values.

```markdown
## Parameters

- **required_param** (required): Description of the required parameter
- **optional_param** (optional): Description of the optional parameter
- **param_with_default** (optional, default: "value"): Description with default value
```

--------------------------------

### No Consolidation Configuration

Source: https://github.com/strands-agents/agent-sop/blob/main/agent-sops/codebase-summary.sop.md

Configuration for running checks without consolidating documentation files.

```yaml
consolidate: false
check_consistency: true
check_completeness: true
```

--------------------------------

### Generate Cursor commands with strands-agents-sops

Source: https://github.com/strands-agents/agent-sop/blob/main/AGENTS.md

Generate Cursor commands from built-in SOPs. Default output directory is .cursor/commands. Use --output-dir to specify a custom directory and --sop-paths to include custom SOPs.

```bash
# Generate Cursor commands from built-in SOPs (default: .cursor/commands)
strands-agents-sops commands --type cursor

# Specify custom output directory
strands-agents-sops commands --type cursor --output-dir .cursor/commands

# Include custom SOPs in commands generation
strands-agents-sops commands --type cursor --sop-paths ~/my-sops --output-dir .cursor/commands
```

--------------------------------

### Define Conditional Logic in Steps

Source: https://github.com/strands-agents/agent-sop/blob/main/rules/agent-sop-format.md

The format for documenting conditional actions within an SOP step.

```markdown
### 3. [Conditional Step]

If [condition], proceed with [specific action]. Otherwise, [alternative action].

**Constraints:**
- You MUST check [condition] before proceeding
- If [condition] is true, You MUST [action]
- If [condition] is false, You MUST [alternative action]
```

--------------------------------

### Format and lint code

Source: https://github.com/strands-agents/agent-sop/blob/main/python/README.md

Format code with Ruff, check linting, auto-fix linting issues, and clean build artifacts.

```bash
# Format code with Ruff
hatch run format

# Check linting issues
hatch run lint

# Auto-fix linting issues
hatch run lint-fix

# Clean build artifacts and cache
hatch run clean
```

--------------------------------

### Code quality commands with hatch

Source: https://github.com/strands-agents/agent-sop/blob/main/AGENTS.md

Commands for code quality: format, lint, auto-fix linting issues, and clean build artifacts.

```bash
# Format code
hatch run format

# Check code quality
hatch run lint

# Auto-fix linting issues
hatch run lint-fix

# Clean build artifacts
hatch run clean
```

--------------------------------

### Configure MCP server in Kiro CLI

Source: https://github.com/strands-agents/agent-sop/blob/main/python/README.md

Add the MCP server configuration to Kiro CLI's settings file.

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