event-store-design

Use it when:: You're building event-sourcing infrastructure or choosing where to store events.
It does:: Sets the requirements for an event store — append-only, ordered per stream and globally, versioned for concurrency, subscribable, idempotent.
You get:: A design along these rules; a reference file holds the templates and worked examples.
Compares:: EventStoreDB, PostgreSQL, Kafka, DynamoDB and Marten, with what each is best and worst at.

TL;DR

A reference for designing the storage layer of an event-sourced system. The SKILL.md diagrams an event store as per-aggregate streams plus a global position, lists its requirements (immutable append-only events, per-stream and global ordering, optimistic concurrency via versions, real-time subscriptions, idempotent writes), and compares five technologies: EventStoreDB for pure event sourcing, PostgreSQL when you already run Postgres, Kafka for high-throughput streaming but weak per-stream queries, DynamoDB for serverless AWS, and Marten for .NET. Its do's and don'ts: stream IDs that include the aggregate type, correlation and causation IDs, version events from day one, deduplicate by event ID, index for your query patterns, never update or delete events, keep payloads small, don't skip optimistic concurrency, and handle slow consumers. The concrete templates and worked examples sit in a reference file.

Summarizes the skill at 4bde316.

npx skills add https://github.com/wshobson/agents --skill event-store-design

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

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

Weekly Downloads

153

-20% over the 8 weeks to Nov 9

Weekly values

Week to	Installs
Sep 21	191
Sep 28	220
Oct 5	266
Oct 12	216
Oct 19	182
Oct 26	187
Nov 2	174
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 databases backend

SKILL.md

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

Frontmatter

name: event-store-design
description: Design and implement event stores for event-sourced systems. Use when building event sourcing infrastructure, choosing event store technologies, or implementing event persistence patterns.

Event Store Design

Comprehensive guide to designing event stores for event-sourced applications.

When to Use This Skill

Designing event sourcing infrastructure
Choosing between event store technologies
Implementing custom event stores
Optimizing event storage and retrieval
Setting up event store schemas
Planning for event store scaling

Core Concepts

1. Event Store Architecture

┌─────────────────────────────────────────────────────┐
│                    Event Store                       │
├─────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
│  │   Stream 1   │  │   Stream 2   │  │   Stream 3   │ │
│  │ (Aggregate)  │  │ (Aggregate)  │  │ (Aggregate)  │ │
│  ├─────────────┤  ├─────────────┤  ├─────────────┤ │
│  │ Event 1     │  │ Event 1     │  │ Event 1     │ │
│  │ Event 2     │  │ Event 2     │  │ Event 2     │ │
│  │ Event 3     │  │ ...         │  │ Event 3     │ │
│  │ ...         │  │             │  │ Event 4     │ │
│  └─────────────┘  └─────────────┘  └─────────────┘ │
├─────────────────────────────────────────────────────┤
│  Global Position: 1 → 2 → 3 → 4 → 5 → 6 → ...     │
└─────────────────────────────────────────────────────┘

2. Event Store Requirements

Requirement	Description
Append-only	Events are immutable, only appends
Ordered	Per-stream and global ordering
Versioned	Optimistic concurrency control
Subscriptions	Real-time event notifications
Idempotent	Handle duplicate writes safely

Technology Comparison

Technology	Best For	Limitations
EventStoreDB	Pure event sourcing	Single-purpose
PostgreSQL	Existing Postgres stack	Manual implementation
Kafka	High-throughput streaming	Not ideal for per-stream queries
DynamoDB	Serverless, AWS-native	Query limitations
Marten	.NET ecosystems	.NET specific

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

Use stream IDs that include aggregate type - Order-{uuid}
Include correlation/causation IDs - For tracing
Version events from day one - Plan for schema evolution
Implement idempotency - Use event IDs for deduplication
Index appropriately - For your query patterns

Don'ts

Don't update or delete events - They're immutable facts
Don't store large payloads - Keep events small
Don't skip optimistic concurrency - Prevents data corruption
Don't ignore backpressure - Handle slow consumers