How strands-agents/agent-sop works
1. Repository purpose
- This repo is a packaging and distribution system for “Agent SOPs”: markdown-based workflow definitions that can be delivered to AI tools in multiple formats.
- The core architectural idea is single source SOP content converted into several target surfaces: MCP prompts, Cursor commands, Agent Skills, and a reusable format rule.
2. Canonical content layer
- The authoritative workflow content appears to live in the agent-sops/ directory, plus supporting documentation under spec/ and rules/.
- These markdown files define the SOPs themselves, the SOP format specification, and the authoring/validation rule, which are then transformed into runtime artifacts.
3. Python package as the transformation engine
- The python/strands_agents_sops/ package is the main executable subsystem.
- It likely contains one module per output channel:
- mcp.py for exposing SOPs as MCP prompts
- cursor.py for generating Cursor command files
- skills.py for generating Agent Skills
- rules.py for emitting the SOP format rule
- utils.py for shared file/path/markdown handling
- __main__.py and main.py-style entry handling in the package for the CLI
4. CLI as the primary control plane
- The package is used as a command-line tool (strands-agents-sops) with subcommands such as mcp, commands, skills, and rule.
- The CLI is the orchestration boundary: it loads built-in SOPs, optionally loads external SOPs from user-supplied paths, applies precedence rules, and emits the chosen target format.
5. External SOP loading is a first-class extension point
- The README and tests indicate a key architectural feature: users can supply additional SOP directories via --sop-paths.
- These external SOPs are discovered by filename suffix (.sop.md), normalized for paths like ~ and relative paths, and merged with built-ins using override precedence.
- This makes SOP content extensible without changing the package code.
6. Multiple output adapters
- The repo is not a single-product app; it is a multi-adapter content distribution system.
- Each adapter targets a different ecosystem boundary:
- MCP server: exposes prompts to clients like Kiro or Claude Code
- Cursor commands: generates command files consumable inside Cursor
- Skills: generates SKILL.md bundles for Claude/Skills-compatible tooling
- Rule output: prints or exports the SOP authoring format rule for other agent platforms
7. Generated artifact boundaries
- Generated outputs are intentionally separated from source SOPs:
- .cursor/commands/ for Cursor
- skills/<name>/SKILL.md for Agent Skills
- likely a rule file destination when exported into another tool’s conventions
- This separation is important for diagramming: source content enters the package, transformed artifacts exit into tool-specific directories.
8. Built-in workflows shipped with the package
- The README identifies several built-in SOPs: codebase-summary, pdd, code-task-generator, code-assist, and eval.
- The presence of skills/agent-sop-author/ and rules/agent-sop-format.md suggests the repo also ships its own authoring workflow and formatting guidance, not just end-user operational SOPs.
9. Validation and correctness layer
- Tests under python/tests/ cover cursor generation, SOP loading, rules, skills, main entry behavior, and utility functions.
- This indicates the architecture relies on deterministic transformation and discovery behavior, especially around malformed input and precedence handling.
- The skills/agent-sop-author/validate-sop.sh script adds a shell-based validation step for authored SOPs.
10. Distribution and packaging
- The Python project is isolated under python/ with its own pyproject.toml, so the repo is structured as a package distribution rather than a monolithic application.
- Top-level .claude-plugin/ metadata and GitHub workflows indicate the repo also publishes itself as a plugin/skill distribution artifact.
11. GitHub Actions and release pipeline
- The .github/workflows/ directory shows separate automation lanes:
- PR/push validation
- lint/test
- PyPI publishing on release
- skills publishing
- This means build/test/release is a significant architectural boundary: source SOP changes flow through CI into packaged Python releases and generated skill distributions.
12. How the pieces flow together
- A practical data flow is:
1. SOP markdown is authored in repo content locations
2. the Python CLI discovers built-in and external SOPs
3. the selected adapter renders them into a target format
4. the output is consumed by an AI tool, MCP client, or plugin/skills system
- The repo therefore functions as a content compiler for agent workflows.
13. Diagramming takeaway
- If you draw this architecture, the main nodes are:
- SOP source content
- Python CLI / transformer layer
- Adapter outputs for MCP, Cursor, Skills, and Rules
- External consumer tools such as Kiro, Claude Code, and Claude Skills-compatible systems
- The important boundary is not “backend vs frontend,” but canonical markdown workflows vs generated tool-specific integrations.
Main entry points: __main__.py CLI · rules.py Rules Adapter · skills.py Skills Adapter · workflows CI Workflows
Components 17
Source SOPs
Canonical markdown workflows and their authoring rules.
- Agent SOPs · Built-in workflow content shipped as markdown SOPs.
agent-sops - SOP Spec · Defines the repository's SOP format and structure.
spec/agent-sops-specification.md - Format Rule · Markdown rule used to validate and guide SOP authoring.
rules/agent-sop-format.md
Python Engine
CLI and transformation modules that discover and render SOPs.
- CLI · Command-line control plane for loading SOPs and selecting output adapters.
python/strands_agents_sops/__main__.py - MCP Adapter · Exposes SOPs as MCP prompts for compatible clients.
python/strands_agents_sops/mcp.py - Cursor Adapter · Generates Cursor command files from SOP content.
python/strands_agents_sops/cursor.py - Skills Adapter · Builds Agent Skills bundles such as SKILL.md outputs.
python/strands_agents_sops/skills.py - Rules Adapter · Emits the SOP format rule for other tools or exports.
python/strands_agents_sops/rules.py - Utilities · Shared path, discovery, and markdown handling used by adapters.
python/strands_agents_sops/utils.py - External SOPs · User-supplied SOP directories loaded through override precedence.
Generated Surfaces
Tool-specific artifacts and bundle formats produced from SOP content.
- MCP Prompts · Prompt surface consumed by MCP clients such as Claude Code or Kiro.
- Cursor Commands · Command files generated into Cursor's commands directory.
- Skill Bundle · Distributed skills package rooted at SKILL.md.
skills/agent-sop-author/SKILL.md - Rule Output · Rendered format rule consumed by other agent platforms.
Packaging & CI
Distribution metadata and automation for publishing and validation.
- Py Project · Python package definition and distribution metadata.
python/pyproject.toml - Plugin Meta · Claude plugin metadata used for packaging and marketplace distribution.
.claude-plugin/plugin.json - CI Workflows · GitHub Actions lanes for validation, testing, publishing, and skills release.
.github/workflows
Connections 18
- Agent SOPs → CLI: load built-ins · Canonical SOP markdown is discovered and fed into the CLI.
- External SOPs → CLI: override input · User-supplied SOP directories are merged with built-ins using precedence rules.
- SOP Spec → Rules Adapter: defines shape · The SOP specification informs the emitted format rule.
- Format Rule → Rules Adapter: source rule · The authoring rule is used as the basis for rule output.
- CLI → MCP Adapter: mcp · CLI dispatches to the MCP rendering path.
- CLI → Cursor Adapter: commands · CLI dispatches to Cursor command generation.
- CLI → Skills Adapter: skills · CLI dispatches to skill bundle generation.
- CLI → Rules Adapter: rule · CLI dispatches to rule emission.
- CLI → Utilities: uses · CLI relies on shared discovery and path helpers.
- MCP Adapter → MCP Prompts: renders · Adapter converts SOPs into MCP prompt surfaces.
- Cursor Adapter → Cursor Commands: renders · Adapter writes Cursor-compatible command files.
- Skills Adapter → Skill Bundle: renders · Adapter builds skill bundles for downstream tooling.
- Rules Adapter → Rule Output: renders · Adapter emits a portable format rule artifact.
- Skills Adapter → External SOPs: includes · Skill generation can incorporate external SOP content.
- Py Project → CLI: packages · Python packaging exposes the CLI entrypoint and modules.
- Plugin Meta → CI Workflows: publishes · Plugin metadata is delivered through repository automation.
- CI Workflows → Py Project: builds · CI validates and publishes the Python package on release.
- CI Workflows → Skill Bundle: releases · GitHub Actions publishes skill artifacts.