strands-agents/agent-sop: Natural Language SOPs for AI Coding Agents

The problem Agent SOPs solve: procedure drift across agent runs

An agent asked to implement a feature will improvise. One run explores the codebase first, another starts editing, a third writes tests after the fact. The output may still compile, but the process is not repeatable, and repeatability is what makes agent output reviewable by a team.

Agent SOPs address that by moving the procedure out of the prompt and into a markdown document with a fixed shape: an overview, a parameter list, numbered steps, and constraints written in RFC 2119 language (MUST, SHOULD, MAY). The README describes the format as "markdown-based instruction sets that guide AI agents through sophisticated workflows using natural language, parameterized inputs, and constraint-based execution." The audience is teams already building on Strands Agents who want the same workflow to be shareable across people and projects rather than retyped per session.

The README frames distribution as multi-modal: MCP tools, Agent Skills, and Python modules. That matters more than the format itself, because it means one SOP file can be consumed by a CLI agent, an MCP client, or an import statement without rewriting the content.

Inside an SOP file: parameters, steps and RFC 2119 constraints

An SOP is a single markdown file. The README's example, code-assist, opens with an Overview that names the workflow (Explore, Plan, Code, Commit) and a Parameters block. In that example, task_description is required and mode is optional with a default of "interactive"; the alternative value shown is "fsc" (Full Self-Coding). Steps follow, each with a Constraints list. The quoted constraints are blunt: the agent MUST validate and create the documentation directory structure, MUST discover existing instruction files using find commands, and MUST NOT proceed if directory creation fails.

The constraints are the mechanism. Natural language alone leaves room for interpretation, so the SOP pins the parts that must not vary and leaves the rest to the model. Parameters are what make a file reusable: the same code-assist SOP runs against a different task_description without editing the document.

The repository ships five SOPs under agent-sops/: codebase-summary for codebase analysis and documentation generation, pdd for prompt-driven development, code-task-generator for breaking requirements into tasks, code-assist for TDD-based implementation, and eval for an evaluation workflow built on the Strands Evals SDK. Each targets a different phase, and they are designed to hand artifacts to one another rather than run in isolation.

The .agents/ directory is the real interface between the SOPs

The PDD family (codebase-summary, pdd, code-task-generator, code-assist) writes into a .agents/ directory, and the layout is the contract between them. summary/ holds codebase-summary output. planning/{project_name}/ holds pdd output with subfolders for rough-idea.md, idea-honing.md, research/, design/ and implementation/. tasks/{project_name}/step01/ holds code-task-generator output as task-*.code-task.md files. scratchpad/{project_name}/{task_name}/ holds code-assist working files.

The README is explicit about what to commit: summary always, planning often, tasks optionally or in an issue tracker instead, and scratchpad in .gitignore. That split is a design decision, not housekeeping. It means the durable reasoning (why a design was chosen) survives in version control while transient implementation notes do not.

Auto-generated project names are prefixed with the current date in YYYY-MM-DD form, for example 2026-01-30-auth-system. The stated reason is identification and sorting. The practical effect is that planning and task folders sort chronologically without a separate index.

Because the folders are plain paths, they also scope context. The README gives a Kiro CLI example that pins planning files during implementation:

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

That command adds the planning markdown for one project to the agent's context. It is the closest thing in the README to a context-management strategy, and it only works if the directory convention is followed.

Installing strands-agents-sops and running a first SOP

The package is published on PyPI as strands-agents-sops. The README gives two install routes, Homebrew and pip:

brew install strands-agents-sops

pip install strands-agents-sops

For a Strands Agents setup the README installs the runtime and tools alongside the SOP package:

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

The README notes that the pip alternative for strands-agents-sops is covered in the Quick Start section, so the Homebrew line is not the only option in that block.

The first real use is importing an SOP as a system prompt. The README's example builds a small CLI coding agent with the editor and shell tools and passes code_assist directly:

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

What the reader should expect: the SOP text becomes the agent's system prompt, and the first message names the SOP so the model follows it. From there the loop takes terminal input. The import name code_assist mirrors the SOP file code-assist.sop.md, so the other SOPs follow the same pattern.

The second route is MCP. The README states the MCP server exposes SOPs as prompts that assistants discover on demand. In Kiro CLI you add strands-agents-sops mcp to ~/.kiro/settings/mcp.json and let Kiro launch the server rather than starting a terminal process yourself. The README says the underlying server command is strands-agents-sops mcp, and that is where the truncated install section ends.

Where Agent SOPs stop being the right tool

The package assumes a Strands Agents runtime. The Python example imports Agent from strands and tools from strands_tools; the SOP files themselves are markdown and portable, but the documented execution paths are Strands-specific or MCP-specific. If your stack is neither, you are copying markdown into another framework's prompt and maintaining that glue yourself.

The constraints are also only as strong as the model's compliance. MUST NOT proceed if directory creation fails is an instruction, not a guard. Nothing in the README describes a validator that rejects a run which ignored a constraint, so a non-compliant model can skip a step and the SOP will not notice.

Context size is a real cost. An SOP with overview, parameters, numbered steps, constraints, examples and troubleshooting is not a short prompt. Passing it as system_prompt consumes budget on every turn, and the README does not document a way to load only the steps relevant to the current phase.

There is also no SOP authoring tool. The repository contains markdown files, a rules/ directory, a spec/ directory and a python/ directory, but the README does not describe a schema validator or a linter for new SOPs. Teams writing their own SOP get the format by example, not by tooling.

Finally, the eval SOP depends on the Strands Evals SDK, so that workflow inherits a second dependency and a second upgrade cadence.

Agent SOP versus Agent Skills

The README lists Agent Skills as one of three distribution modes, which makes Skills the natural comparison. The difference is in how content reaches the model. An SOP here is a document with parameters and numbered steps that is typically loaded as a system prompt or fetched from the MCP server as a prompt; the whole procedure is in front of the model for the run. A Skill is a packaged capability that a host discovers and invokes, with its own packaging and discovery conventions.

The practical consequence is control versus reach. An SOP gives you the full procedure in one reviewable file, and the README's .agents/ convention shows how far that goes: the SOPs pass artifacts to each other through directories, not through a runtime registry. A Skill is easier to distribute to hosts that already understand Skills, but the procedure is split across whatever the Skill format requires.

If your team reviews procedures in pull requests and wants the workflow readable end to end, the SOP file is the more direct artifact. If you need the workflow to appear inside a host that only understands Skills, the SOP content still has to be repackaged. The README does not document a conversion step between the two.

Maintenance, licensing and upgrade cost

The last push to main was on 2026-08-07, the same day v1.1.3 was released, so the repository is not dormant. Release spacing is uneven: v1.1.1 on 2026-03-04, v1.1.2 on 2026-04-15, then v1.1.3 on 2026-08-07 after roughly a four-month gap. The repository is not archived. The README does not document a deprecation policy or a compatibility guarantee for SOP file formats across minor versions, so if you fork or extend an SOP, pin the version you validated against.

Upgrade cost has two parts. The Python package is a normal pip or Homebrew upgrade. The SOP content is the harder part: if you copied code-assist.sop.md into your own repository and edited it, a package upgrade will not update your copy, and the README does not describe a merge or override mechanism. The .agents/ directory layout is the other compatibility surface, since other SOPs read from summary/, planning/ and tasks/. A change to that layout would break downstream SOPs, and the README does not state that the layout is stable.

The project is Apache-2.0, with a LICENSE and a NOTICE file at the repository root. Apache-2.0 permits commercial use and modification and includes a patent grant, but it also carries attribution and notice-retention conditions. If you redistribute the SOP files inside a product, read NOTICE and LICENSE rather than assuming the markdown is unencumbered. This is a description of the licence, not legal advice.

Editorial conclusion

Adopt it if you already run Strands Agents and want repeatable, reviewable procedures in plain markdown rather than prompt text scattered across scripts. Skip it if you need a runtime-agnostic format or a GUI for authoring SOPs, because the repository ships markdown and a Python package, not an editor. Before committing, verify that the SOP you need exists in agent-sops/, that its parameters match your inputs, and that your agent framework can load a system prompt the size of code-assist.sop.md.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. strands-agents/agent-sop on GitHub