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
npx skills add Bbeierle12/Skill-MCP-Claude --skill software-architecture -a claude-codeWhat 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
OrderServiceagainst 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
UserControllerinto a repository.
How to install software-architecture
1Skills CLI (Vercel)
npx skills add Bbeierle12/Skill-MCP-Claude --skill software-architecture -a claude-code2Manually: put the files in place
~/.claude/skills/software-architecture/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/software-architecture/
1Skills CLI (Vercel)
npx skills add Bbeierle12/Skill-MCP-Claude --skill software-architecture -a codex2Manually: put the files in place
.agents/skills/software-architecture/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add Bbeierle12/Skill-MCP-Claude --skill software-architecture -a cursor2Manually: put the files in place
.cursor/skills/software-architecture/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install Bbeierle12/Skill-MCP-Claude skills/software-architecture2Manually: put the files in place
.github/skills/software-architecture/SKILL.md1Skills CLI (Vercel)
npx skills add Bbeierle12/Skill-MCP-Claude --skill software-architecture -a gemini-cli2Platform CLI
gemini skills install https://github.com/Bbeierle12/Skill-MCP-Claude --path skills/software-architectureManually: put the files in place
.devin/skills/software-architecture/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add Bbeierle12/Skill-MCP-Claude --skill software-architecture -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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