Agent skill

Designing Architecture

by CloudAI-X in CloudAI-X/opencode-workflow

Guides software architecture decisions, design patterns, and system design principles.

MITAuto-check passedDevelopment

Install Designing Architecture

skills CLI
$ npx skills add CloudAI-X/opencode-workflow --skill designing-architecture -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install CloudAI-X/opencode-workflow designing-architecture --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/CloudAI-X/opencode-workflow.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/designing-architecture .claude/skills/designing-architecture && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
designing-architecture
GitHub stars
275
Token cost
~2.6k tokens
SKILL.md length
724 words
Files
1
Skills in repo
7
Repo updated
First seen
Licence
MIT

At a glance

Guides software architecture decisions, design patterns, and system design principles.

  • Works in 8 steps: Big Ball of Mud - No clear structure,… → Golden Hammer - Using one pattern for… → Premature Optimization - Designing for… → …
  • Designing systems
  • SKILL.md covers When to Use This Skill, Core Architecture Principles, Architectural Patterns and Design Patterns, plus 7 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Designing Architecture is an agent skill from CloudAI-X/opencode-workflow. Guides software architecture decisions, design patterns, and system design principles. Use when designing systems, choosing patterns, or making architectural decisions.

Its SKILL.md is about 2.6k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts. Compatibility notes: opencode

It sits in Development, covering Design patterns and Software architecture. The licence is MIT.

When your agent uses it

  • Designing systems
  • Choosing patterns
  • Making architectural decisions

Example prompts

  • “Use the designing-architecture skill to guide software architecture decisions, design patterns, and system design principles”
  • “/designing-architecture”

Requirements

  • Compatibility (from SKILL.md): opencode

Workflow steps

8 steps, taken from the first numbered list in SKILL.md.

  1. Big Ball of Mud - No clear structure, everything depends on everything
  2. Golden Hammer - Using one pattern for all problems
  3. Premature Optimization - Designing for scale before proving need
  4. Analysis Paralysis - Over-designing, never shipping
  5. Distributed Monolith - Microservices with tight coupling
  6. Anemic Domain Model - Entities with only getters/setters
  7. God Object - One class that does everything
  8. Leaky Abstraction - Implementation details leak through interfaces

What it can do on your machine

Read from SKILL.md and the folder at commit 0128ca6. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

  • Compatibility

    opencode

    From compatibility in the SKILL.md frontmatter.

Context cost

Designing Architecture loads about 2.6k tokens when it runs. Until then it costs about 48 tokens; SKILL.md has 724 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~48
When it runs · the whole SKILL.md, loaded when a task matches
~2.6k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from CloudAI-X/opencode-workflow at commit 0128ca6, republished under its MIT licence (© CloudAI-X). 724 words, ~2,631 tokens.

Download SKILL.mdSave it as .claude/skills/designing-architecture/SKILL.md (or your agent's skills folder).
name
designing-architecture
description
Guides software architecture decisions, design patterns, and system design principles. Use when designing systems, choosing patterns, or making architectural decisions.
compatibility
opencode
license
MIT
metadata.category
design
metadata.audience
developers

Designing Architecture

Principles and patterns for designing maintainable, scalable, and robust software systems.

When to Use This Skill

  • Designing new systems or features
  • Choosing between architectural patterns
  • Making technology decisions
  • Reviewing system design
  • Planning for scalability
  • Refactoring legacy systems

Core Architecture Principles

SOLID Principles
PrincipleSummaryViolation Sign
Single ResponsibilityOne reason to changeClass does too many things
Open/ClosedOpen for extension, closed for modificationModifying existing code for new features
Liskov SubstitutionSubtypes replaceable for base typesOverrides break parent behavior
Interface SegregationSmall, focused interfacesClasses implement unused methods
Dependency InversionDepend on abstractionsHigh-level modules depend on low-level
The Dependency Rule
Outer layers depend on inner layers, NEVER the reverse.

┌─────────────────────────────────────┐
│     Frameworks & Drivers           │  ← Database, Web, UI
├─────────────────────────────────────┤
│     Interface Adapters             │  ← Controllers, Presenters, Gateways
├─────────────────────────────────────┤
│     Application Business Rules     │  ← Use Cases
├─────────────────────────────────────┤
│     Enterprise Business Rules      │  ← Entities
└─────────────────────────────────────┘

Dependencies point INWARD only.

Architectural Patterns

Layered Architecture
┌─────────────────────────────────────┐
│     Presentation Layer             │  ← UI, API Controllers
├─────────────────────────────────────┤
│     Application Layer              │  ← Use Cases, Services
├─────────────────────────────────────┤
│     Domain Layer                   │  ← Business Logic, Entities
├─────────────────────────────────────┤
│     Infrastructure Layer           │  ← Database, External APIs
└─────────────────────────────────────┘

Use when: Traditional applications, clear separation needed Avoid when: High-performance needs, event-driven systems

Hexagonal Architecture (Ports & Adapters)
           ┌───────────────┐
           │   Primary     │
           │   Adapters    │  ← REST API, CLI, GraphQL
           └───────┬───────┘
                   │
        ┌──────────▼──────────┐
        │                     │
        │   ┌───────────┐     │
        │   │   Core    │     │
Primary │   │  Domain   │     │ Secondary
Ports   │   │  Logic    │     │ Ports
        │   └───────────┘     │
        │                     │
        └──────────┬──────────┘
                   │
           ┌───────▼───────┐
           │   Secondary   │
           │   Adapters    │  ← Database, Message Queue, External API
           └───────────────┘

Use when: Testability is critical, multiple interfaces needed Avoid when: Simple CRUD applications

Microservices Architecture
┌─────────┐  ┌─────────┐  ┌─────────┐
│ Service │  │ Service │  │ Service │
│    A    │  │    B    │  │    C    │
└────┬────┘  └────┬────┘  └────┬────┘
     │            │            │
     └────────────┴────────────┘
                  │
           ┌──────▼──────┐
           │   Message   │
           │    Bus      │
           └─────────────┘

Use when: Independent scaling, team autonomy, polyglot needs Avoid when: Small teams, simple domains, tight coupling required

Event-Driven Architecture
Event Source → Event Bus → Event Handlers
     │              │              │
     ▼              ▼              ▼
  Produces    Routes Events    Consumes
  Events      (Kafka, RabbitMQ)  Events

Use when: Async processing, decoupling, audit trails Avoid when: Immediate consistency required, simple workflows


Design Patterns

Creational Patterns
PatternPurposeWhen to Use
FactoryCreate objects without specifying classObject creation logic is complex
BuilderConstruct complex objects step-by-stepMany optional parameters
SingletonSingle instance globallyShared resource (use sparingly)
Dependency InjectionInject dependencies externallyTestability, loose coupling
Structural Patterns
PatternPurposeWhen to Use
AdapterConvert interface to anotherIntegrating incompatible systems
DecoratorAdd behavior dynamicallyExtending functionality without inheritance
FacadeSimplified interface to complex systemHiding complexity
RepositoryAbstract data accessSeparating domain from persistence
Behavioral Patterns
PatternPurposeWhen to Use
StrategyInterchangeable algorithmsMultiple ways to do something
ObserverNotify dependents of changesEvent systems, reactive updates
CommandEncapsulate actions as objectsUndo/redo, queuing, logging
Chain of ResponsibilityPass request along handlersMiddleware, validation chains

Domain-Driven Design Concepts

Strategic Design
ConceptDefinitionExample
Bounded ContextExplicit boundary for a domain modelOrder context, Shipping context
Ubiquitous LanguageShared vocabulary between devs and domain experts"Order", "Line Item", "Fulfillment"
Context MapHow bounded contexts relateCustomer shared between Sales and Support
Tactical Patterns
PatternPurposeExample
EntityObject with identityUser, Order
Value ObjectObject without identityMoney, Address
AggregateCluster of entities with rootOrder + LineItems
Domain EventSomething that happenedOrderPlaced, PaymentReceived
RepositoryCollection-like access to aggregatesOrderRepository
Domain ServiceLogic that doesn't fit entitiesPricingService

System Design Considerations

Scalability Patterns
PatternDescriptionTrade-off
Horizontal ScalingAdd more instancesStatelessness required
Vertical ScalingBigger machinesHardware limits
CachingStore computed resultsCache invalidation
Database ShardingSplit data across DBsQuery complexity
Read ReplicasSeparate read/writeEventual consistency
CDNEdge content deliveryStatic content only
Show full SKILL.md (285 more words)Show less
Resilience Patterns
PatternPurposeImplementation
Circuit BreakerPrevent cascade failuresFail fast when downstream is down
Retry with BackoffHandle transient failuresExponential delay between retries
BulkheadIsolate failuresSeparate thread pools per dependency
TimeoutBound waiting timeMax wait for responses
FallbackGraceful degradationDefault behavior when service unavailable
Data Consistency Patterns
PatternConsistencyUse When
ACID TransactionsStrongFinancial data, critical operations
SagaEventualDistributed transactions
Event SourcingEventualAudit trails, complex state
CQRSEventualDifferent read/write models

Technology Decision Framework

When to Use a Database
NeedRecommendedAvoid
Relational data, ACIDPostgreSQL, MySQLMongoDB
Document storage, flexible schemaMongoDB, DynamoDBRelational
Key-value, high speedRedis, MemcachedRelational
Time seriesInfluxDB, TimescaleDBGeneric SQL
Graph relationshipsNeo4j, NeptuneRelational (for complex)
SearchElasticsearch, MeilisearchFull table scans
When to Use Message Queues
NeedPattern
Async processingQueue (SQS, RabbitMQ)
Event broadcastingPub/Sub (SNS, Kafka)
Task schedulingDelayed queues
Load levelingQueue with workers
Event sourcingLog-based (Kafka)

Architecture Decision Records (ADR)

Template
markdown
# ADR-001: [Title]

## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]

## Context
[Why is this decision needed?]

## Decision
[What is the decision?]

## Consequences
### Positive
- [Benefit 1]
- [Benefit 2]

### Negative
- [Trade-off 1]
- [Trade-off 2]

## Alternatives Considered
1. [Alternative 1] - [Why rejected]
2. [Alternative 2] - [Why rejected]

Anti-Patterns to Avoid

  1. Big Ball of Mud - No clear structure, everything depends on everything
  2. Golden Hammer - Using one pattern for all problems
  3. Premature Optimization - Designing for scale before proving need
  4. Analysis Paralysis - Over-designing, never shipping
  5. Distributed Monolith - Microservices with tight coupling
  6. Anemic Domain Model - Entities with only getters/setters
  7. God Object - One class that does everything
  8. Leaky Abstraction - Implementation details leak through interfaces

Decision Checklist

Before finalizing an architecture decision, verify:

  • Does it solve the actual problem?
  • Is it the simplest solution that works?
  • Can the team maintain it?
  • Does it align with existing patterns?
  • Is it testable?
  • Can it evolve as requirements change?
  • Are the trade-offs acceptable?
  • Is the decision documented?

Quick Reference

SOLID:
  S - Single Responsibility
  O - Open/Closed
  L - Liskov Substitution
  I - Interface Segregation
  D - Dependency Inversion

PATTERNS:
  Layered     → Simple, clear separation
  Hexagonal   → Testable, adaptable
  Microservices → Scalable, independent
  Event-Driven  → Decoupled, async

DDD BUILDING BLOCKS:
  Entity, Value Object, Aggregate
  Repository, Domain Event, Domain Service

SCALABILITY:
  Horizontal scaling, Caching, Sharding, CDN

RESILIENCE:
  Circuit Breaker, Retry, Bulkhead, Timeout

© CloudAI-X, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/designing-architecture of CloudAI-X/opencode-workflow.

Open the folder on GitHubat commit 0128ca6

Compare with similar skills

Designing Architecture next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Designing Architecture compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Designing Architecture this skillCloudAI-X/opencode-workflow275—~2.6kAutomated safety check: PassMIT
Architecture PatternsKartikLabhshetwar/better-shot2.4k2 repos~1.4kAutomated safety check: PassCustom licence
Akka.Hosting Actor PatternsAaronontheweb/dotnet-skills1.2k1 repos~5kAutomated safety check: PassMIT
Brooks Audithyhmrright/brooks-lint1.5k1 repos~537Automated safety check: PassMIT
Adopt a Design PatternTotoro-jam/battle-tested-patterns345—~4.9kAutomated safety check: PassMIT
Pattern Conformance AuditTotoro-jam/battle-tested-patterns345—~1.6kAutomated safety check: PassMIT

Similar skills

  • Architecture Patterns

    KartikLabhshetwar/better-shot

    Deep dive into software architecture for macOS. An agent skill from KartikLabhshetwar/better-shot.

    2.4k GitHub starsUsed in 2 repos~1.4k tokens
    DevelopmentAuto-check passed
  • Akka.Hosting Actor Patterns

    Aaronontheweb/dotnet-skills

    Shows how to build entity actors with Akka.Hosting so the same code runs in local unit tests and in a sharded cluster in production.

    1.2k GitHub starsUsed in 1 repo~5k tokens
    DevelopmentAuto-check passed
  • Brooks Audit

    hyhmrright/brooks-lint

    Architecture audit that maps module dependencies, checks layering integrity, and flags structural decay across a codebase, drawing on twelve classic engineering books.

    1.5k GitHub starsUsed in 1 repo~537 tokens
    DevelopmentAuto-check passed
  • Adopt a Design Pattern

    Totoro-jam/battle-tested-patterns

    Matches a coding problem to one of 46 documented systems patterns, checks that it really fits, then adapts it into your codebase with a test for its invariant.

    345 GitHub stars~4.9k tokensUpdated 1 mo ago
    DevelopmentAuto-check passed
  • Pattern Conformance Audit

    Totoro-jam/battle-tested-patterns

    Audits a codebase's existing patterns, such as rate limiters, circuit breakers and caches, against canonical invariants and flags mislabeled or divergent ones.

    345 GitHub stars~1.6k tokensUpdated 1 mo ago
    DevelopmentAuto-check passed
  • Apply Martin Fowler-inspired enterprise architecture rules when choosing layers, service layers, transaction scripts, domain models, repositories, mappers, or…

    2.9k GitHub stars~228 tokensUpdated 29 days ago
    DevelopmentAuto-check passed

More from CloudAI-X/opencode-workflow

  • Analyzing Projects

    CloudAI-X/opencode-workflow

    Guides systematic project analysis, codebase exploration, and architecture pattern recognition.

    275 GitHub stars~1.8k tokensUpdated 9 mo ago
    Auto-check passed
  • Designing APIs

    CloudAI-X/opencode-workflow

    Guides REST and GraphQL API design, endpoint patterns, request/response schemas, versioning, and API best practices.

    275 GitHub stars~2.2k tokensUpdated 9 mo ago
    Auto-check passed
  • Designing Tests

    CloudAI-X/opencode-workflow

    Guides test strategy, TDD/BDD approaches, test coverage planning, and testing best practices.

    275 GitHub stars~2.9k tokensUpdated 9 mo ago
    Auto-check passed
  • Managing Git

    CloudAI-X/opencode-workflow

    Guides git workflows, branching strategies, commit conventions, and version control best practices.

    275 GitHub stars~2.5k tokensUpdated 9 mo ago
    Auto-check passed
  • Optimizing Performance

    CloudAI-X/opencode-workflow

    Guides performance optimization, profiling techniques, and bottleneck identification.

    275 GitHub stars~2.6k tokensUpdated 9 mo ago
    Auto-check passed
  • Parallel Execution

    CloudAI-X/opencode-workflow

    CRITICAL skill for executing multiple Task tool calls in a SINGLE message for true parallelism.

    275 GitHub stars~2.1k tokensUpdated 9 mo ago
    Auto-check passed

Categories

Questions about Designing Architecture

What does Designing Architecture do?

Guides software architecture decisions, design patterns, and system design principles. Designing Architecture is an agent skill from CloudAI-X/opencode-workflow. Guides software architecture decisions, design patterns, and system design principles.

When should I use Designing Architecture?

Designing Architecture fits situations like: designing systems; choosing patterns; making architectural decisions.

How do I install Designing Architecture in Claude Code?

Run `npx skills add CloudAI-X/opencode-workflow --skill designing-architecture -a claude-code`. Or copy the skill folder (skills/designing-architecture in CloudAI-X/opencode-workflow) into .claude/skills/designing-architecture in your project. Claude Code loads it when a task matches its description.

How do I install Designing Architecture in Codex?

Run `npx skills add CloudAI-X/opencode-workflow --skill designing-architecture -a codex`. Or copy the skill folder (skills/designing-architecture in CloudAI-X/opencode-workflow) into .agents/skills/designing-architecture in your project. Codex loads it when a task matches its description.

Can I use Designing Architecture in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add CloudAI-X/opencode-workflow --skill designing-architecture -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/designing-architecture, .gemini/skills/designing-architecture, .github/skills/designing-architecture and .opencode/skills/designing-architecture in your project.

What does Designing Architecture need to run?

SKILL.md names no scripts, command-line tools or credentials: Designing Architecture is instructions for the agent only. Compatibility (from SKILL.md): opencode.

Does Designing Architecture access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Designing Architecture safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Designing Architecture use?

Designing Architecture is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Designing Architecture use?

About 2.6k tokens (SKILL.md is roughly 11k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Designing Architecture?

Skills that share tags, products or a category with Designing Architecture: Architecture Patterns (KartikLabhshetwar/better-shot, 2.4k stars), Akka.Hosting Actor Patterns (Aaronontheweb/dotnet-skills, 1.2k stars), Brooks Audit (hyhmrright/brooks-lint, 1.5k stars) and Adopt a Design Pattern (Totoro-jam/battle-tested-patterns, 345 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Designing Architecture?

CloudAI-X (a GitHub user) maintains it in CloudAI-X/opencode-workflow, which has 275 GitHub stars. The repository holds 7 skills in this directory. The repository was last updated on January 10, 2026.

Source: CloudAI-X/opencode-workflow on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.