Skip to main content
skill CX Codex

software-architecture — Claude Code skill

software-architecture — a skill that walks the agent through SOLID and Clean Architecture, with a bad and a good version of the same TypeScript code for each principle.

MIT 150 installs ★ 9 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add Bbeierle12/Skill-MCP-Claude --skill software-architecture -a claude-code
Open on GitHub

What software-architecture does

The skill gives the agent a fixed frame for review. Every SOLID principle appears twice: a class doing too much, then the same job split into an entity, a repository and two services. Open/Closed gets an area function rewritten around an interface, Liskov a Square that stops inheriting from Rectangle, and so on through interface segregation and dependency inversion.

Clean Architecture is drawn as four layers — frameworks, interface adapters, application, domain — with dependencies pointing inward. Samples run from a User entity and an Email value object up to a CreateUserUseCase, a controller and a Prisma repository that maps rows back into domain objects.

Everything is written in TypeScript and the persistence example targets Prisma. Porting those shapes to another language is on you, because the agent will hand back the same class skeletons.

What it helps with

  • split a class that saves, mails and reports into entity, repository and services
  • swap a type switch for an interface with an area() method
  • pull user registration out of the controller into a use case
  • keep Prisma calls out of the HTTP layer
  • spot a subclass that breaks its base class contract

Example prompts for the agent

  • Review OrderService against SOLID and point out where single responsibility breaks.
  • Sketch the layers for a new service: domain, use cases, adapters, repository.
  • Move the Prisma calls out of UserController into a repository.

How to install software-architecture

1Skills CLI (Vercel)

npx skills add Bbeierle12/Skill-MCP-Claude --skill software-architecture -a claude-code

2Manually: put the files in place

~/.claude/skills/software-architecture/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/software-architecture/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about software-architecture

How to install software-architecture in Claude Code?

Run npx skills add Bbeierle12/Skill-MCP-Claude --skill software-architecture -a claude-code; the skill file lands at ~/.claude/skills/software-architecture/SKILL.md.

What does the software-architecture skill do?

It spells out the five SOLID principles and the Clean Architecture layers, each with before-and-after TypeScript code. The agent uses those samples when it designs a structure or reviews yours.

Which language are the examples in?

TypeScript, with a Prisma-backed repository. On a different stack the class shapes have to be carried over by hand.

Source text

SKILL.md · MIT
---
name: software-architecture
description: Implements design patterns including Clean Architecture, SOLID principles, and comprehensive software design best practices. Use when designing systems, reviewing architecture, establishing patterns, or making structural decisions.
---

# Software Architecture

## SOLID Principles

### Single Responsibility Principle (SRP)
A class should have only one reason to change.

```typescript
// ❌ Bad: Multiple responsibilities
class User {
  saveToDatabase() { }
  sendEmail() { }
  generateReport() { }
}

// ✅ Good: Single responsibility
class User { }
class UserRepository { save(user: User) { } }
class EmailService { send(to: string) { } }
class ReportGenerator { generate(user: User) { } }
```

### Open/Closed Principle (OCP)
Open for extension, closed for modification.

```typescript
// ❌ Bad: Requires modification for new types
function calculateArea(shape: Shape) {
  if (shape.type === 'circle') {
    return Math.PI * shape.radius ** 2;
  } else if (shape.type === 'rectangle') {
    return shape.width * shape.height;
  }
  // Need to modify for new shapes
}

// ✅ Good: Extend without modification
interface Shape {
  area(): number;
}

class Circle implements Shape {
  constructor(private radius: number) {}
  area() { return Math.PI * this.radius ** 2; }
}

class Rectangle implements Shape {
  constructor(private width: number, private height: number) {}
  area() { return this.width * this.height; }
}
```

### Liskov Substitution Principle (LSP)
Subtypes must be substitutable for their base types.

```typescript
// ❌ Bad: Square violates Rectangle's contract
class Rectangle {
  setWidth(w: number) { this.width = w; }
  setHeight(h: number) { this.height = h; }
}

class Square extends Rectangle {
  setWidth(w: number) { this.width = w; this.height = w; } // Violates LSP
}

// ✅ Good: Separate hierarchies
interface Shape {
  area(): number;
}

class Rectangle implements Shape { }
class Square implements Shape { }
```

### Interface Segregation Principle (ISP)
Clients shouldn't depend on interfaces they don't use.

```typescript
// ❌ Bad: Fat interface
interface Worker {
  work(): void;
  eat(): void;
  sleep(): void;
}

// ✅ Good: Segregated interfaces
interface Workable { work(): void; }
interface Eatable { eat(): void; }
interface Sleepable { sleep(): void; }

class Human implements Workable, Eatable, Sleepable { }
class Robot implements Workable { }
```

### Dependency Inversion Principle (DIP)
Depend on abstractions, not concretions.

```typescript
// ❌ Bad: High-level depends on low-level
class UserService {
  private database = new MySQLDatabase();
}

// ✅ Good: Both depend on abstraction
interface Database {
  save(data: any): Promise<void>;
  find(id: string): Promise<any>;
}

class UserService {
  constructor(private database: Database) {}
}

// Now can inject any implementation
const service = new UserService(new MySQLDatabase());
const testService = new UserService(new MockDatabase());
```

## Clean Architecture

```
┌─────────────────────────────────────────────────┐
│                  Frameworks                      │
│  (Express, React, Database Drivers)              │
├─────────────────────────────────────────────────┤
│              Interface Adapters                  │
│  (Controllers, Presenters, Gateways)            │
├─────────────────────────────────────────────────┤
│              Application Layer                   │
│  (Use Cases, Application Services)              │
├─────────────────────────────────────────────────┤
│                Domain Layer                      │
│  (Entities, Value Objects, Domain Services)     │
└─────────────────────────────────────────────────┘

Dependencies point INWARD only.
Inner layers know nothing about outer layers.
```

### Domain Layer (Innermost)

```typescript
// entities/User.ts
export class User {
  constructor(
    public readonly id: string,
    public readonly email: Email,
    public name: string,
    private password: HashedPassword
  ) {}

  changeName(newName: string): void {
    if (newName.length < 2) {
      throw new DomainError('Name too short');
    }
    this.name = newName;
  }

  verifyPassword(plaintext: string): boolean {
    return this.password.verify(plaintext);
  }
}

// value-objects/Email.ts
export class Email {
  constructor(private readonly value: string) {
    if (!this.isValid(value)) {
      throw new DomainError('Invalid email');
    }
  }

  private isValid(email: string): boolean {
    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
  }

  toString(): string {
    return this.value;
  }
}
```

### Application Layer (Use Cases)

```typescript
// use-cases/CreateUser.ts
interface CreateUserInput {
  email: string;
  password: string;
  name: string;
}

interface CreateUserOutput {
  id: string;
  email: string;
  name: string;
}

export class CreateUserUseCase {
  constructor(
    private userRepository: UserRepository,
    private passwordHasher: PasswordHasher,
    private emailService: EmailService
  ) {}

  async execute(input: CreateUserInput): Promise<CreateUserOutput> {
    // Validate email uniqueness
    const existing = await this.userRepository.findByEmail(input.email);
    if (existing) {
      throw new ApplicationError('Email already exists');
    }

    // Create domain object
    const hashedPassword = await this.passwordHasher.hash(input.password);
    const user = new User(
      generateId(),
      new Email(input.email),
      input.name,
      hashedPassword
    );

    // Persist
    await this.userRepository.save(user);

    // Side effects
    await this.emailService.sendWelcome(user.email);

    return {
      id: user.id,
      email: user.email.toString(),
      name: user.name,
    };
  }
}
```

### Interface Adapters

```typescript
// controllers/UserController.ts
export class UserController {
  constructor(private createUserUseCase: CreateUserUseCase) {}

  async create(req: Request, res: Response): Promise<void> {
    const result = await this.createUserUseCase.execute({
      email: req.body.email,
      password: req.body.password,
      name: req.body.name,
    });

    res.status(201).json(result);
  }
}

// repositories/PrismaUserRepository.ts
export class PrismaUserRepository implements UserRepository {
  async save(user: User): Promise<void> {
    await prisma.user.create({
      data: {
        id: user.id,
        email: user.email.toString(),
        name: user.name,
      },
    });
  }

  async findByEmail(email: string): Promise<User | null> {
    const data = await prisma.user.findUnique({
      where: { email },
    });
    return data ? this.toDomain(data) : null;
  }

  private toDomain(data: PrismaUser): User {
    return new User(
      data.id,
      new Email(data.email),
      data.name,
      new HashedPassword(data.password)
    );
  }
}
```

## Design Patterns

### Repository Pattern
```typescript
interface Repository<T> {
  findById(id: string): Promise<T | null>;
  findAll(): Promise<T[]>;
  save(entity: T): Promise<void>;
  delete(id: string): Promise<void>;
}
```

### Factory Pattern
```typescript
interface PaymentProcessor {
  process(amount: number): Promise<void>;
}

class PaymentProcessorFactory {
  create(type: 'stripe' | 'paypal'): PaymentProcessor {
    switch (type) {
      case 'stripe': return new StripeProcessor();
      case 'paypal': return new PayPalProcessor();
    }
  }
}
```

### Strategy Pattern
```typescript
interface PricingStrategy {
  calculate(basePrice: number): number;
}

class RegularPricing implements PricingStrategy {
  calculate(basePrice: number) { return basePrice; }
}

class PremiumPricing implements PricingStrategy {
  calculate(basePrice: number) { return basePrice * 0.9; }
}

class Order {
  constructor(private pricingStrategy: PricingStrategy) {}
  
  getTotal(basePrice: number) {
    return this.pricingStrategy.calculate(basePrice);
  }
}
```

### Observer Pattern
```typescript
interface Observer<T> {
  update(data: T): void;
}

class EventEmitter<T> {
  private observers: Observer<T>[] = [];

  subscribe(observer: Observer<T>): void {
    this.observers.push(observer);
  }

  notify(data: T): void {
    this.observers.forEach(o => o.update(data));
  }
}
```

## Architecture Decision Records (ADR)

Document significant decisions:

```markdown
# ADR-001: Use PostgreSQL for Primary Database

## Status
Accepted

## Context
Need to choose a primary database for user data storage.

## Decision
Use PostgreSQL.

## Consequences
### Positive
- Strong consistency guarantees
- Rich query capabilities
- Well-supported ORMs

### Negative
- Requires more operational overhead than SQLite
- Horizontal scaling more complex than NoSQL
```

## Anti-Patterns to Avoid

### God Object
❌ One class that does everything

### Spaghetti Code
❌ No clear structure or flow

### Golden Hammer
❌ Using same solution for every problem

### Premature Optimization
❌ Optimizing before measuring

### Cargo Cult Programming
❌ Using patterns without understanding why

© Bbeierle12 · MIT · Bbeierle12/Skill-MCP-Claude

Similar skills

All skills for Code review and refactoring →
clean-architecture wondelai clean-architecture — a skill that keeps business rules independent of framework and database by enforcing one rule: source code dependencies point inward. CX Codex +1 8,000installs design-patterns-implementation aj-geddes design-patterns-implementation — a skill for Claude Code and Codex that picks and applies design patterns to architectural problems. It kicks in during refactoring, architecture review, and when building extensible systems. CX Codex +1 601installs architecture-patterns OrchestKit architecture-patterns enforces clean architecture, backend layer boundaries, and directory limits. Triggers when designing module boundaries or running refactoring tasks. CX Codex +1 236installs code-architecture curiositech code-architecture is a Claude Code skill for organizing code within a single application. It covers clean and hexagonal architecture, feature-based folders, dependency inversion, and module boundaries. CX Codex +1 169installs software-design-principles databricks-solutions software-design-principles — a Markdown engineering guide for code review, module planning, and refactoring. It enforces clean boundaries, non-functional requirements, and layered design across pull requests. CX Codex +1 ★ 38repo stars nestjs-oop-design-patterns amirtaherkhani nestjs-oop-design-patterns — a Claude Code skill for applying OOP, SOLID, and design patterns to NestJS and TypeScript. It activates during code changes or when investigating object-design problems. CX Codex +1 560installs

From the same set19

The whole set →
particles-gpu particles-gpu generates GPU-accelerated particle systems for Three.js and React Three Fiber. Ideal for rendering thousands to millions of points smoothly. CX Codex +1 173installs shader-fundamentals The shader-fundamentals skill covers GLSL basics, from vertex and fragment shaders to coordinates, types, and data flow. Use it when building or debugging shader code. CX Codex +1 173installs gsap-sequencing The gsap-sequencing skill guides complex GSAP timelines with labels, nested sequences, callbacks, and precise placement. Use it for coordinated UI motion. CX Codex +1 163installs audio-analysis audio-analysis is a Claude Code skill for inspecting audio with Tone.js and the Web Audio API. It supports work on visualizations, beat detection, and audio-reactive features. CX Codex +1 151installs particles-physics particles-physics is a Claude Code skill that adds forces and velocity fields to particle motion in scenes with gravity, wind, attractors or turbulence. CX Codex +1 134installs r3f-fundamentals r3f-fundamentals guides setup of React Three Fiber scenes, Canvas configuration, lighting, camera rigs, and render loop logic in declarative JSX. CX Codex +1 125installs shader-noise shader-noise is a Claude Code skill with GLSL noise algorithms for generating organic textures, terrain, clouds, fire, and cellular patterns in shaders. CX Codex +1 121installs form-ux-patterns The form-ux-patterns skill guides the design of complex forms with grouped fields, step-by-step flows, and conditional inputs. Use it for checkout or onboarding experiences. CX Codex +1 120installs

Project sponsors

Companies that keep this analytics open