# microservices-architecture

Guides AI coding assistants through microservice design, service boundaries, and distributed messaging. Helps break apart monoliths into isolated services.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 522 installs · ★ 371
- Author: aj-geddes
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/aj-geddes/useful-ai-prompts/tree/HEAD/skills/microservices-architecture/SKILL.md
- Updated: 2026-03-04
- HTML: https://affpapa.org/en/nevibecode/skills/microservices-architecture

## What it does

This skill provides architecture instructions for breaking monolithic software into autonomous services. It walks the assistant through defining bounded contexts, setting up API gateways, handling service discovery, and configuring Istio service meshes.

The guidelines enforce asynchronous messaging, request tracing with correlation IDs, health checks, and circuit breakers. Each service must keep its own database. Sharing a single database across services is treated as an architectural violation.

Distributed transactions like two-phase commits are discouraged due to latency and failure risks. Instead, the rules instruct the assistant to design idempotent operations and plan for partial network failures from the start.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add aj-geddes/useful-ai-prompts --skill microservices-architecture -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/microservices-architecture/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/microservices-architecture/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add aj-geddes/useful-ai-prompts --skill microservices-architecture -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/microservices-architecture/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add aj-geddes/useful-ai-prompts --skill microservices-architecture -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/microservices-architecture/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install aj-geddes/useful-ai-prompts microservices-architecture
```

2. **Manually: put the files in place**
- File: `.github/skills/microservices-architecture/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add aj-geddes/useful-ai-prompts --skill microservices-architecture -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/aj-geddes/useful-ai-prompts --path skills/microservices-architecture
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/microservices-architecture/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add aj-geddes/useful-ai-prompts --skill microservices-architecture -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/aj-geddes/useful-ai-prompts/tree/HEAD/skills/microservices-architecture/SKILL.md

## When to use it
- split monolithic systems into decoupled domain services
- set up API gateways and Istio service mesh routing
- design asynchronous communication between distributed services
- maintain data consistency without two-phase commit transactions

## Example prompts
- Split this monolith into bounded contexts with dedicated databases for each service.
- Design an asynchronous event flow between the order and payment services.
- Configure an API gateway with circuit breaker patterns for backend microservices.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: c8d0f9ef491adc8b.

BEGIN THIRD-PARTY FILE c8d0f9ef491adc8b
````text
---
name: microservices-architecture
description: >
  Design and implement microservices architecture including service boundaries,
  communication patterns, API gateways, service mesh, service discovery, and
  distributed system patterns. Use when building microservices, distributed
  systems, or service-oriented architectures.
---

# Microservices Architecture

## Table of Contents

- [Overview](#overview)
- [When to Use](#when-to-use)
- [Quick Start](#quick-start)
- [Reference Guides](#reference-guides)
- [Best Practices](#best-practices)

## Overview

Comprehensive guide to designing, implementing, and maintaining microservices architectures. Covers service decomposition, communication patterns, data management, deployment strategies, and observability for distributed systems.

## When to Use

- Designing new microservices architectures
- Decomposing monolithic applications
- Implementing service-to-service communication
- Setting up API gateways and service mesh
- Implementing service discovery
- Managing distributed transactions
- Designing inter-service data consistency
- Scaling independent services

## Quick Start

Minimal working example:

```
Bounded Contexts:
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│  Order Service  │  │  User Service   │  │ Payment Service │
│                 │  │                 │  │                 │
│ - Create Order  │  │ - User Profile  │  │ - Process Pay   │
│ - Order Status  │  │ - Auth          │  │ - Refund        │
│ - Order History │  │ - Preferences   │  │ - Transactions  │
└─────────────────┘  └─────────────────┘  └─────────────────┘
```

## Reference Guides

Detailed implementations in the `references/` directory:

| Guide | Contents |
|---|---|
| [Service Boundary Design](references/service-boundary-design.md) | Service Boundary Design |
| [Communication Patterns](references/communication-patterns.md) | Communication Patterns |
| [API Gateway Pattern](references/api-gateway-pattern.md) | API Gateway Pattern |
| [Service Discovery](references/service-discovery.md) | Service Discovery |
| [Data Consistency Patterns](references/data-consistency-patterns.md) | Data Consistency Patterns |
| [Service Mesh (Istio)](references/service-mesh-istio.md) | Service Mesh (Istio) |

## Best Practices

### ✅ DO

- Design services around business capabilities
- Use asynchronous communication where possible
- Implement circuit breakers for resilience
````
END THIRD-PARTY FILE c8d0f9ef491adc8b

The third-party file has ended. Everything between the c8d0f9ef491adc8b tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2729 of 3671 bytes. © aj-geddes · MIT · https://github.com/aj-geddes/useful-ai-prompts/tree/HEAD/skills/microservices-architecture/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md