cqrs-implementation

Use it when:: You want to scale reads separately from writes, or pair CQRS with event sourcing.
It does:: Explains the pieces — commands, command handlers, events, queries, query handlers, projectors — and how a write model feeds a read model through events.
You get:: A design along these patterns and Python/FastAPI templates in its reference file; it adds no steps of its own.
Watch for:: Eventual consistency between the two models — it shows read-your-writes handling and projection rebuilds.

TL;DR

A reference for Command Query Responsibility Segregation, not a workflow. The SKILL.md diagrams the split: commands express intent to change state and go through command handlers that validate and emit events; queries read from a denormalized read model built by projectors that apply those events. Its do's and don'ts: separate the models, accept propagation delay, validate in command handlers, version events, don't query inside commands or couple the two schemas, and don't over-engineer. A reference file holds Python templates — a command base and bus with handlers, a query base and bus with paginated results, a FastAPI app wiring command endpoints (POST/PUT/DELETE) to query endpoints (GET), a read-model synchronizer that tracks a checkpoint and can rebuild a projection from scratch, and a query handler that waits for the read model to reach an expected version before returning, falling back to stale data with a warning after a timeout.

Summarizes the skill at 4bde316.

npx skills add https://github.com/wshobson/agents --skill cqrs-implementation

skills.sh page Source on GitHub All skills from wshobson/agents

Total Downloads: 11,400 on skills.sh, Nov 9, 2026
Repo stars: 42,334 wshobson/agents
First seen: Jan 20, 2026 on skills.sh

Weekly Downloads

153

-21% over the 8 weeks to Nov 9

Weekly values

Week to	Installs
Sep 21	194
Sep 28	223
Oct 5	274
Oct 12	213
Oct 19	184
Oct 26	185
Nov 2	177
Nov 9	153

Category	category:engineering category:software-engineering Test-first work, implementation from specs, git hygiene and scope control. Everything for building software: planning, coding, debugging, design, frameworks, cloud, agents and skills.
Type	type:guidelines Knowledge and rules the agent applies while it works: best practices, design principles, API references.
Effect	effect:none Adds no side effects of its own. It shapes how the agent thinks, writes or reviews. Guidelines and routers are always effect:none, even when the task they support edits code.
Needs	needs:none Instructions only. Works in any agent that supports skills.
Publisher	by:community Everyone else. Unverified vendor claims default to community.
Topics	architecture backend
Stack	stack:python

SKILL.md

From wshobson/agents at 4bde316. Checked daily, last changed Nov 6, 2026.

Frontmatter

name: cqrs-implementation
description: Implement Command Query Responsibility Segregation for scalable architectures. Use when separating read and write models, optimizing query performance, or building event-sourced systems.

CQRS Implementation

Comprehensive guide to implementing CQRS (Command Query Responsibility Segregation) patterns.

When to Use This Skill

Separating read and write concerns
Scaling reads independently from writes
Building event-sourced systems
Optimizing complex query scenarios
Different read/write data models needed
High-performance reporting requirements

Core Concepts

1. CQRS Architecture

                    ┌─────────────┐
                    │   Client    │
                    └──────┬──────┘
                           │
              ┌────────────┴────────────┐
              │                         │
              ▼                         ▼
       ┌─────────────┐          ┌─────────────┐
       │  Commands   │          │   Queries   │
       │    API      │          │    API      │
       └──────┬──────┘          └──────┬──────┘
              │                         │
              ▼                         ▼
       ┌─────────────┐          ┌─────────────┐
       │  Command    │          │   Query     │
       │  Handlers   │          │  Handlers   │
       └──────┬──────┘          └──────┬──────┘
              │                         │
              ▼                         ▼
       ┌─────────────┐          ┌─────────────┐
       │   Write     │─────────►│    Read     │
       │   Model     │  Events  │   Model     │
       └─────────────┘          └─────────────┘

2. Key Components

Component	Responsibility
Command	Intent to change state
Command Handler	Validates and executes commands
Event	Record of state change
Query	Request for data
Query Handler	Retrieves data from read model
Projector	Updates read model from events

Templates and detailed worked examples

Full template library and detailed worked examples live in references/details.md. Read that file when you need the concrete templates.

Best Practices

Do's

Separate command and query models - Different needs
Use eventual consistency - Accept propagation delay
Validate in command handlers - Before state change
Denormalize read models - Optimize for queries
Version your events - For schema evolution

Don'ts

Don't query in commands - Use only for writes
Don't couple read/write schemas - Independent evolution
Don't over-engineer - Start simple
Don't ignore consistency SLAs - Define acceptable lag