projection-patterns
- Use it when:
- You have an event-sourced system and need query-friendly views, dashboards or search indexes built from its events.
- Terms:
- A projection turns a stream of events into a read model, a table or index shaped for queries; a checkpoint records the last event applied.
- It does:
- Explains four projection types, live, catch-up, persistent and inline, and nine do's and don'ts, such as idempotent projections so replays are safe.
- You get:
- Async Python templates for a projector with checkpoints and rebuilds, an order summary, an Elasticsearch search index, daily sales totals and a multi-table projection.
TL;DR
In CQRS with event sourcing, changes are stored as events and reads come from separate read models; this skill covers that read side. The SKILL.md shows the architecture (event store, projector, read model) and four projection types: live from a subscription for current state, catch-up over history to rebuild, persistent with a stored checkpoint to resume after a restart, and inline in the write's transaction for strong consistency. Its rules: make projections idempotent so replays are safe, use transactions for multi-table updates, store checkpoints, monitor lag and plan for rebuilds; keep projections independent, handle and alert on errors, process events in order and denormalize for the queries you need. A reference file holds the templates, in async Python, with asyncpg for Postgres: a base Projection class and a Projector that runs each projection from its checkpoint and can rebuild one from scratch, an order summary projection, a product search projection into Elasticsearch, a daily sales aggregate that subtracts refunds, and a customer activity projection across several tables.
Summarizes the skill at 4bde316.
npx skills add https://github.com/wshobson/agents --skill projection-patterns skills.sh pageSource on GitHubAll skills from wshobson/agents
- Total Downloads
- 10,900 on skills.sh, Nov 9, 2026
- Repo stars
- 42,334 wshobson/agents
- First seen
- Jan 20, 2026 on skills.sh
Weekly values
| Week to | Installs |
|---|---|
| Sep 21 | 180 |
| Sep 28 | 211 |
| Oct 5 | 267 |
| Oct 12 | 207 |
| Oct 19 | 180 |
| Oct 26 | 178 |
| Nov 2 | 171 |
| Nov 9 | 150 |
| Category |
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 |
Knowledge and rules the agent applies while it works: best practices, design principles, API references. |
| Effect |
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 |
Instructions only. Works in any agent that supports skills. |
| Publisher |
Everyone else. Unverified vendor claims default to community. |
| Topics | |
| Stack |
SKILL.md
From wshobson/agents at 4bde316. Checked daily, last changed Nov 6, 2026.
Frontmatter
name: projection-patterns
description: Build read models and projections from event streams. Use when implementing CQRS read sides, building materialized views, or optimizing query performance in event-sourced systems.Projection Patterns
Comprehensive guide to building projections and read models for event-sourced systems.
When to Use This Skill
- Building CQRS read models
- Creating materialized views from events
- Optimizing query performance
- Implementing real-time dashboards
- Building search indexes from events
- Aggregating data across streams
Core Concepts
1. Projection Architecture
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Event Store │────►│ Projector │────►│ Read Model │
│ │ │ │ │ (Database) │
│ ┌─────────┐ │ │ ┌─────────┐ │ │ ┌─────────┐ │
│ │ Events │ │ │ │ Handler │ │ │ │ Tables │ │
│ └─────────┘ │ │ │ Logic │ │ │ │ Views │ │
│ │ │ └─────────┘ │ │ │ Cache │ │
└─────────────┘ └─────────────┘ └─────────────┘
2. Projection Types
| Type | Description | Use Case |
|---|---|---|
| Live | Real-time from subscription | Current state queries |
| Catchup | Process historical events | Rebuilding read models |
| Persistent | Stores checkpoint | Resume after restart |
| Inline | Same transaction as write | Strong consistency |
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
- Make projections idempotent - Safe to replay
- Use transactions - For multi-table updates
- Store checkpoints - Resume after failures
- Monitor lag - Alert on projection delays
- Plan for rebuilds - Design for reconstruction
Don'ts
- Don't couple projections - Each is independent
- Don't skip error handling - Log and alert on failures
- Don't ignore ordering - Events must be processed in order
- Don't over-normalize - Denormalize for query patterns