Use this skill when designing microservice architectures, decomposing monoliths, implementing inter-service communication, or solving distributed data challenges. Triggers on service decomposition, saga pattern, CQRS, event sourcing, API gateway, service mesh, circuit breaker, distributed transactions, and any task requiring microservice design decisions or migration strategies.
Use this skill when designing microservice architectures, decomposing monoliths, implementing inter-service communication, or solving distributed data challenges. Triggers on service decomposition, saga pattern, CQRS, event sourcing, API gateway, service mesh, circuit breaker, distributed transactions, and any task requiring microservice design decisions or migration strategies.
When this skill is activated, always start your first response with the 🧢 emoji.
Microservices Architecture
Microservices is an architectural style that structures an application as a collection of small, independently deployable services, each owning its domain and data. Each service runs in its own process and communicates through lightweight mechanisms like HTTP/gRPC or async messaging. The style enables teams to develop, deploy, and scale services independently, reducing coupling and increasing resilience. It trades the simplicity of a monolith for the operational complexity of distributed systems - that trade-off must be made deliberately.
When to Use This Skill
Trigger on these scenarios:
Decomposing a monolith into services (strangler fig, domain extraction)
Designing inter-service communication (sync vs async, REST vs gRPC vs events)
Defining service boundaries using Domain-Driven Design (bounded contexts)
Do NOT trigger for:
Simple CRUD apps or early-stage products with a single team - a monolith is the right choice
Tasks that are purely about infrastructure provisioning without architectural decisions
Key Principles
Single responsibility per service - Each service owns exactly one bounded context. If you need to join data across services in the database layer, your boundaries are wrong.
Smart endpoints, dumb pipes - Business logic lives in services, not in the message broker or API gateway. Pipes carry data; they do not transform it.
Design for failure - Every network call can fail. Services must handle partial failures gracefully using timeouts, retries with backoff, circuit breakers, and fallbacks.
Decentralize data ownership - Each service owns its own database. No shared databases. Cross-service queries are done through APIs or events, never direct DB access.
Automate everything - Microservices require CI/CD pipelines, automated testing, health checks, and observability from day one. Without automation, operational overhead becomes unmanageable.
Core Concepts
Service Boundaries
Define boundaries using Domain-Driven Design bounded contexts. A bounded context is a logical boundary within which a domain model is consistent. Map organizational structure (Conway's Law) to service boundaries. Services should be loosely coupled (change one without changing others) and highly cohesive (related behavior stays together).
Prefer async for cross-domain operations. Use sync only when the caller truly cannot proceed without the response.
Data Consistency
Distributed systems cannot guarantee both consistency and availability simultaneously (CAP theorem). Embrace eventual consistency for cross-service data. Use the saga pattern for distributed transactions. Never use two-phase commit across service boundaries - it creates tight coupling and is a single point of failure.
Service Discovery
Services find each other through a registry (Consul, Eureka) or via DNS with Kubernetes. Client-side discovery puts load-balancing logic in the client. Server-side discovery delegates to a load balancer. In Kubernetes, use DNS-based discovery with Services objects.
Observability
The three pillars: logs (structured JSON, correlation IDs), metrics (RED: Rate, Errors, Duration), traces (distributed tracing with OpenTelemetry). Every service must emit all three from day one. Correlation IDs must propagate across all service calls.
Common Tasks
Decompose a Monolith
Use the strangler fig pattern: incrementally extract functionality without a big-bang rewrite.
Identify bounded contexts in the monolith using event storming or domain modeling
Stand up an API gateway in front of the monolith
Extract the least-coupled domain first as a new service
Route traffic for that domain through the gateway to the new service
Repeat domain by domain, shrinking the monolith over time
Decommission the monolith when empty
Key rule: never split by technical layer (all controllers, all DAOs). Split by business capability.
Implement Saga Pattern
Use sagas to manage distributed transactions without two-phase commit. Two variants:
Choreography saga (event-driven, no central coordinator):
Each service listens for domain events and emits its own events
Compensating transactions roll back on failure
Good for simple flows; hard to trace complex ones
Orchestration saga (central coordinator drives the flow):
A saga orchestrator sends commands to each participant and tracks state
On failure, the orchestrator issues compensating commands in reverse order
Prefer for complex multi-step flows - easier to reason about and observe
Compensating transactions must be idempotent. Design them upfront, not as an afterthought.
Design API Gateway
The API gateway is the single entry point for external clients. Responsibilities:
Routing - map external URLs to internal service endpoints
Auth/AuthZ - validate JWTs or API keys before forwarding
Rate limiting - protect services from abuse
Request aggregation - combine multiple service calls into one response (BFF pattern)
Do NOT put business logic in the gateway. Keep it thin. Use the Backend for Frontend (BFF) pattern when different clients (mobile, web) need different response shapes.
Implement Circuit Breaker
The circuit breaker pattern prevents cascading failures when a downstream service is unhealthy.
States: Closed (requests flow normally) -> Open (fast-fail, no requests sent) -> Half-Open (probe with limited requests).
Implementation checklist:
Set a failure threshold (e.g., 50% error rate over 10 requests)
Set a timeout for the open state before transitioning to half-open
Log all state transitions as events
Expose circuit state in health endpoints
Pair with a fallback (cached response, default value, or degraded mode)
Libraries: Resilience4j (Java), Polly (.NET), opossum (Node.js), circuitbreaker (Go).
Choose Communication Pattern
Decision
Recommendation
Need immediate response
REST or gRPC (sync)
Decoupling producer from consumer
Async messaging (Kafka, SQS)
High-throughput, ordered events
Kafka
Simple task queuing
RabbitMQ or SQS
Internal service-to-service (low latency)
gRPC (contract-first, strongly typed)
Public-facing API
REST (broad tooling, human readable)
Fan-out to multiple consumers
Pub/sub (Kafka topics, SNS)
Never mix sync and async in a way that hides latency - if you call an async system synchronously (poll or long-poll), make that explicit.
Implement CQRS
Command Query Responsibility Segregation separates read and write models.
Read side: subscribes to domain events, builds denormalized read models optimized for queries
Steps to implement:
Separate command handlers from query handlers at the code level first (logical CQRS)
Introduce separate read and write datastores when read/write performance profiles diverge
Populate the read store by consuming domain events from the write side
Accept that read models are eventually consistent with the write store
CQRS is often paired with event sourcing (storing events as the source of truth) but does not require it.
Design Service Mesh
A service mesh handles cross-cutting concerns (mTLS, retries, observability) at the infrastructure layer via sidecar proxies, removing them from application code.
Components:
Data plane: sidecar proxies (Envoy) intercept all traffic
Control plane: configures proxies (Istio Pilot, Linkerd control plane)
Capabilities to configure:
mTLS between all services (zero-trust networking)
Distributed tracing via header propagation
Traffic shaping (canary deployments, A/B testing)
Retry and timeout policies at the mesh level
Only adopt a service mesh when you have 10+ services and the cross-cutting concerns cannot be handled consistently at the application layer.
Services are fine-grained but tightly coupled via sync chains
Redesign boundaries, introduce async communication
Chatty services
Too many small sync calls per request, high latency
Coarsen service boundaries or use async aggregation
Skipping observability
Cannot debug failures in distributed system
Instrument with logs, metrics, traces before going to production
Big-bang migration
Rewriting the entire monolith at once
Use strangler fig - migrate incrementally
No idempotency
Retries cause duplicate side effects
Design all endpoints and consumers to be idempotent
Gotchas
Choreography sagas are deceptively hard to debug at scale - In a choreography saga, each service reacts to events independently. There is no central coordinator to query for "what step are we on?" When a saga fails mid-way, tracing which compensating transactions ran and which did not requires correlating events across multiple services' logs by correlation ID. Prefer orchestration sagas for flows with more than 3-4 participants, and invest in distributed tracing from day one.
The strangler fig pattern stalls without an API gateway - Teams try to route traffic to the new service by updating clients directly. This requires coordinated deployment of every client and the new service simultaneously, defeating the incremental migration goal. An API gateway (or reverse proxy) that owns routing is mandatory for strangler fig to work; the gateway lets you shift traffic without touching clients.
Event-driven eventual consistency surprises users when reads lag behind writes - A user submits a form, the command is processed and an event emitted, but when they immediately reload the page the read model hasn't updated yet. This is expected in CQRS with async projection but is not acceptable UX without mitigation. Use optimistic UI updates on the client side, or add a short read-your-own-writes guarantee for the creating user's session.
Circuit breakers need per-dependency instances, not a single global one - A single circuit breaker protecting all downstream calls means one slow service opens the breaker and blocks all outbound calls. Instantiate separate circuit breakers per downstream dependency so a failure in Service B does not degrade calls to Service C.
Shared library updates become de-facto distributed deployments - Putting business logic or domain types in a shared library that all services depend on means updating that library forces a coordinated upgrade across all services. This reintroduces the coupling microservices were meant to remove. Keep shared libraries limited to infrastructure concerns (logging, tracing, auth middleware) and keep domain logic strictly inside the owning service.
On first activation of this skill in a conversation: check which companion skills are installed by running ls ~/.claude/skills/ ~/.agent/skills/ ~/.agents/skills/ .claude/skills/ .agent/skills/ .agents/skills/ 2>/dev/null. Compare the results against the recommended_skills field in this file's frontmatter. For any that are missing, mention them once and offer to install:
