# design-expert

design-expert equips your agent with system design patterns, distributed architecture principles, and Python reference code.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 178 installs · ★ 45 repo stars
- Author: personamanagmentlayer
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/personamanagmentlayer/pcl/tree/HEAD/stdlib/design/design-expert/SKILL.md
- Updated: 2026-10-12
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/design-expert

## What it does

This skill provides architecture guidelines for scaling software systems and backend services. It covers distributed systems topics like CAP theorem, Raft and Paxos consensus, message queues, and circuit breaker patterns.

The instruction set includes concrete Python code for database sharding routers, round-robin read replicas, sliding-window rate limiters, and caching strategies such as cache-aside or write-behind. The skill operates using `Read`, `Write`, and `Edit` tools.

If an application runs as a simple single-server script, sharding and distributed consensus guidance will add unnecessary complexity.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add personamanagmentlayer/pcl --skill design-expert -a claude-code
```

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

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add personamanagmentlayer/pcl --skill design-expert -a codex
```

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

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add personamanagmentlayer/pcl --skill design-expert -a cursor
```

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install personamanagmentlayer/pcl stdlib/design/design-expert
```

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

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add personamanagmentlayer/pcl --skill design-expert -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/personamanagmentlayer/pcl --path stdlib/design/design-expert
```

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add personamanagmentlayer/pcl --skill design-expert -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/personamanagmentlayer/pcl/tree/HEAD/stdlib/design/design-expert/SKILL.md

## When to use it
- design database sharding logic and read-replica routing in Python
- implement a sliding-window rate limiter for incoming requests
- set up cache-aside or write-behind caching decorators
- handle external service failures with a circuit breaker pattern

## Example prompts
- Implement a circuit breaker class in Python with closed, open, and half-open states.
- Design a database router that directs writes to primary and reads to replicas.
- Write a sliding-window rate limiter using collections.deque.

## Source text · SKILL.md · Apache-2.0

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: 3b278a38c12f1834.

BEGIN THIRD-PARTY FILE 3b278a38c12f1834
````text
---
name: design-expert
version: 1.1.0
description: >-
  Expert-level system design, architecture patterns, scalability, and distributed systems.
  Use when the user mentions system design, architecture, scalability, distributed systems,
  or patterns, or when the task involves Architecture Patterns or Design Principles.
category: design
tags: [system-design, architecture, scalability, distributed-systems, patterns]
allowed-tools:
  - Read
  - Write
  - Edit
---

# System Design Expert

Expert guidance for system design, software architecture, scalability patterns, and distributed systems.

## Core Concepts

### Architecture Patterns

- Microservices vs Monolithic
- Event-driven architecture
- CQRS and Event Sourcing
- Layered architecture
- Hexagonal architecture
- Service-oriented architecture (SOA)

### Scalability

- Horizontal vs vertical scaling
- Load balancing strategies
- Caching layers
- Database sharding
- Read replicas
- CDN usage

### Distributed Systems

- CAP theorem
- Consistency models
- Distributed consensus (Raft, Paxos)
- Message queues
- Service discovery
- Circuit breakers

## Design Patterns

```python
# Singleton Pattern
class DatabaseConnection:
    _instance = None
    _lock = threading.Lock()

    def __new__(cls):
        if cls._instance is None:
            with cls._lock:
                if cls._instance is None:
                    cls._instance = super().__new__(cls)
                    cls._instance._initialize()
        return cls._instance

    def _initialize(self):
        self.connection = self._create_connection()

# Factory Pattern
class ShapeFactory:
    @staticmethod
    def create_shape(shape_type: str):
        if shape_type == "circle":
            return Circle()
        elif shape_type == "square":
            return Square()
        raise ValueError(f"Unknown shape: {shape_type}")

# Observer Pattern
class Subject:
    def __init__(self):
        self._observers = []

    def attach(self, observer):
        self._observers.append(observer)

    def notify(self, event):
        for observer in self._observers:
            observer.update(event)

# Strategy Pattern
class PaymentStrategy:
    def pay(self, amount): pass

class CreditCardPayment(PaymentStrategy):
    def pay(self, amount):
        return f"Paid ${amount} via credit card"

class PayPalPayment(PaymentStrategy):
    def pay(self, amount):
        return f"Paid ${amount} via PayPal"
```

## Scalability Patterns

```python
# Circuit Breaker Pattern
from enum import Enum
import time

class CircuitState(Enum):
    CLOSED = "closed"
    OPEN = "open"
    HALF_OPEN = "half_open"

class CircuitBreaker:
    def __init__(self, failure_threshold=5, timeout=60):
        self.failure_threshold = failure_threshold
        self.timeout = timeout
        self.failure_count = 0
        self.last_failure_time = None
        self.state = CircuitState.CLOSED

    def call(self, func, *args, **kwargs):
````
END THIRD-PARTY FILE 3b278a38c12f1834

The third-party file has ended. Everything between the 3b278a38c12f1834 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 2943 of 8891 bytes. © personamanagmentlayer · Apache-2.0 · https://github.com/personamanagmentlayer/pcl/tree/HEAD/stdlib/design/design-expert/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
