How to use the Projection Patterns agent skill

What does the projection-patterns skill make the agent do?

When the skill is loaded, the agent can explain and help design projections. A projection reads events from an event store and writes the results into a read model that is shaped for queries. The skill's SKILL.md covers the basic architecture (event store, projector, read model) and four projection types: live, catchup, persistent and inline.

It also lists practical rules: make projections idempotent so they are safe to replay, store checkpoints so they can resume after failures, monitor lag, keep projections independent of each other, log and alert on errors, respect event ordering, and denormalize for your query patterns.

• Live: real-time from a subscription, for current-state queries
• Catchup: processes historical events, used for rebuilding read models
• Persistent: stores a checkpoint, so it can resume after a restart
• Inline: runs in the same transaction as the write, for strong consistency

How do you install the projection-patterns skill?

Download the ZIP for the skill from this page. Then install it in one of two ways. For a personal setup, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder.

If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

• Option 1: unzip the downloaded file into ~/.claude/skills/ to make it available to you
• Option 2: unzip it into .claude/skills/ inside a project to share it with that project only
• Option 3: upload it in the Claude apps under Settings → Capabilities → Skills

How do you trigger the skill with a natural request?

You do not need a special command. The skill's description says to use it when implementing CQRS read sides, building materialized views, or optimizing query performance in event-sourced systems. Ask for help with one of those goals in ordinary language and the agent can draw on the skill.

Name the concrete thing you are building, the event types involved and the storage you plan to use. The more specific the request, the more useful the answer.

• Help me design a projection that builds a read model of orders from OrderPlaced and OrderShipped events.
• Which projection type should I use for a dashboard that must reflect events within seconds?
• My catchup projection is rebuilding slowly. What should I check first?
• Review this projector and tell me whether it is idempotent and stores checkpoints.

What does the reference file add?

The skill includes references/details.md, a template library and worked examples. The agent reads this file when it needs concrete templates. The excerpt of that file shows a basic Python projector, with an abstract Projection base class that has a unique name for checkpointing, a list of event types it handles, and an apply method, plus a Projector class that runs projections from the event store.

SKILL.md itself contains no runnable code. Treat the reference templates as a starting point to adapt to your framework and database, not as drop-in code.

What do you need before using it?

The source lists no requirements for this skill. It does not run scripts and does not use the network. The skill is guidance, so you still need your own event-sourced system, event store and database to apply its advice.

Its best fit is a team that already records events and needs read models on top of them. If you do not use event sourcing, the pattern may add complexity without benefit.

• Requires: nothing listed
• Runs scripts: no
• Uses network: no

What safety points should you know about?

Because the skill runs no scripts and makes no network calls, it adds no code execution or outbound traffic on its own. Its risk is advisory: the agent may suggest a design that does not fit your system. Review any SQL, schema change or projector code before running it against production data, and test rebuilds on a copy first.

What tips help you get good results?

Give the agent your event shapes, your ordering guarantees and the queries the read model must serve. Ask it to check your design against the listed do's and don'ts, such as idempotency, checkpoints and lag monitoring. Use the skill to plan for rebuilds early, since the guidance treats reconstruction as a design requirement.

• Share your event store and database choice so advice matches your stack
• Ask for a rebuild plan, not just a happy-path design
• Ask the agent to list failure cases for each projection