agentsclimarketplace

Designing architecture

Skill swell-agents/coding-skills/skills/designing-architecture

Canonical Anthropic Agent Skills for software engineering — TDD, code review, architecture, GitHub-issues PM, plus per-language conventions for Python, Go, Solidity, shell.

Install
npx -y skills add swell-agents/coding-skills --skill designing-architecture

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Design pre-implementation architecture: components, libraries, data flow, schema.

SKILL.md

7.7 KB, as published. Nobody here has run it

Methodology

Phase 1 — Requirements

  1. Parse the feature into functional and non-functional requirements (latency, throughput, availability, consistency, failure modes).
  2. Identify constraints: language, framework, existing codebase, deployment target, regulatory.
  3. Read the project's architecture map (often docs/architecture.md) — see reviewing-changes/reference/architecture-map-pattern.md for the convention. Identify integration points with existing modules.

Phase 2 — Technology landscape scan

  1. Discover candidates. Search awesome-lists (awesome-<language>, awesome-<domain>), GitHub by topic, package registries (PyPI, npm, crates.io). For data layer questions, also DB-Engines and CNCF Landscape.
  2. Evaluate each candidate with consistent dimensions:
    • GitHub stars and trend, last commit, release cadence.
    • Open vs closed issue ratio.
    • Documentation quality (fetch the README; check for runnable examples).
    • License compatibility (MIT/Apache/BSD safe; AGPL/GPL needs deliberate decision).
    • Dependency footprint (transitive count, security history).
  3. Cross-check official docs. Verify the library actually supports the exact use case — a star count doesn't.
  4. Compare alternatives in a table with consistent rows and explicit trade-offs.

Phase 3 — Pattern selection

  1. Identify candidate patterns from problem shape:
    • Creational — Factory, Builder, Singleton (only if state is genuinely global).
    • Structural — Adapter, Decorator, Facade, Proxy.
    • Behavioural — Strategy, Observer, Command, Chain of Responsibility, State.
    • Domain — Repository, Unit of Work, Specification, Value Object.
    • Architectural — Hexagonal / ports-and-adapters, Pipes & Filters, Event-Driven, CQRS, Saga, Outbox.
  2. Select the minimum patterns the problem needs. No pattern tourism.
  3. Map selections to the project's conventions; don't introduce a new pattern when an existing one fits.

Phase 4 — Design

  1. Define component structure: classes / modules / interfaces / boundaries.
  2. Define data flow: inputs → processing → outputs, including failure paths.
  3. Define error-handling strategy (retry, dead-letter, circuit-breaker, idempotency keys).
  4. Define configuration, secrets handling, dependency injection.
  5. Produce an ASCII diagram showing components, dependencies, and data direction.

Phase 5 — Implementation plan

  1. Decompose into TDD-ready steps. Each step:
    • Sized for one red-green-refactor cycle.
    • Independently testable.
    • Delivers incremental value.
  2. Order by dependency (what must exist before what).
  3. Hand off to running-tdd-cycles for execution. Do not implement here.

Database architecture overlay

When the design includes a data layer, run a parallel mini-pipeline:

  1. Pick the technology family.

    • Relational (PostgreSQL, MySQL) — strong consistency, complex joins, transactions.
    • Document (MongoDB, DynamoDB) — flexible schema, horizontal scale, simple access.
    • Key-value (Redis, DynamoDB) — sub-ms reads, cache-like access.
    • Time-series (TimescaleDB, InfluxDB, ClickHouse) — append-heavy, time-range queries.
    • Graph (Neo4j, Neptune) — multi-hop relationships are first-class.
    • Search (Elasticsearch, OpenSearch, Meilisearch) — full-text, faceted filtering.
    • NewSQL (CockroachDB, Spanner, YugabyteDB) — global consistency at scale. Decide via CAP-theorem framing: which two of consistency, availability, partition tolerance does the workload force?

  2. Schema design. Conceptual (ER diagram) → logical (3NF or deliberate denormalisation) → physical (data types, partitioning, sharding key). State trade-offs explicitly.

  3. Indexing strategy. B-tree for equality/range, Hash for exact match, GiST/GIN for full-text/geometry, BRIN for huge ordered tables, partial/filtered indexes for hot subsets. Composite indexes ordered by query selectivity.

  4. Migration plan. Zero-downtime where possible (expand → backfill → contract). Tooling (Alembic, Flyway, Liquibase, Prisma). Backward + forward compatibility for online deploys.

  5. Security and compliance. RBAC and row-level security where applicable. At-rest + in-transit encryption. Audit logging for sensitive ops.

Output

Produce a single Markdown document. The architecture document should be self-contained and feed directly into running-tdd-cycles.

---
purpose: Architecture design for <feature>
---

# Architecture — <feature>

## 1. Requirements
Functional + non-functional, including SLA targets if relevant.

## 2. Technology selection

### Selected
| Library | Purpose | Stars | Last release | Why |
|---|---|---|---|---|
| ... | ... | ... | ... | ... |

### Rejected
| Library | Reason |
|---|---|
| ... | ... |

### Sources
- [1] <awesome-list URL>
- [2] <official docs URL>
- [3] <ThoughtWorks Radar entry>

## 3. Patterns
The patterns selected and the concrete reason each fits this problem.

## 4. Architecture
ASCII diagram + per-component description.

## 5. Data layer (if applicable)
Technology, schema, indexes, migration plan.

## 6. TDD-ready implementation plan
1. **Step 1: <title>** — <what to implement>; depends on: none; test: <what the failing test pins down>.
2. **Step 2: <title>** — ...
   ...

## 7. Open questions
Decisions that need user input before implementation begins.

Behavioural traits

  • Research before recommending. Never propose a library without checking GitHub activity, docs, and at least one alternative.
  • Minimum viable architecture. Design only what the feature needs. No speculative abstractions.
  • Ecosystem first. Always prefer established libraries to custom code. Check awesome-*, package registries, and official docs before writing anything bespoke.
  • Explicit trade-offs. When choosing between alternatives, state what is gained and what is lost.
  • TDD-ready output. Decompose every architecture into red-green-refactor-sized steps.
  • Codebase-aware. Read the architecture map and existing code before designing. Follow established conventions.
  • No pattern tourism. Apply a pattern only when it solves a concrete problem in the current feature.
  • Recency matters. Prefer libraries with commits in the last six months and recent releases.

Cross-references

  • running-tdd-cycles — receives the implementation plan from this skill.
  • reviewing-changes — verifies the implementation against this design.
  • python-conventions / go-conventions / solidity-conventions — language-specific tooling and idioms feed into the design.
  • engineering-philosophy — KISS, YAGNI, Use Libraries, No Magic dominate during design.

Reference

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.