agentsclimarketplace
Sign in

Designing architecture

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

Design pre-implementation architecture: components, libraries, data flow, schema.From its SKILL.md

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.

2 things 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.
  • fetches URLsInstructs the agent to fetch 1 URL, including README.

SKILL.md

7.7 KB, ~1.7k tokens by cl100k_base, 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

What ships with it: 4 files

22.9 KB alongside SKILL.md

reference/

Gives 0 of the 12 instructions most architecture codebase skills give in ~1.7k tokens

Counted across 858 of the 1,304 authors here whose files we hold, read 2026-09-06

  • Apply the deletion test to identify shallow modulesin 32 of 858, across 31 files
  • Read domain glossary and ADRs before exploringin 22 of 858, across 19 files
  • Use Tailwind and Mermaid via CDN for reportsin 21 of 858, across 18 files
  • Document architecture decision recordsin 20 of 858, across 12 files
  • Offer to record ADRs for rejected candidatesin 17 of 858, across 14 files
  • Limit primary navigation to four to seven itemsin 17 of 858, across 7 files
  • Write HTML report to the system temp directoryin 17 of 858, across 14 files
  • Read product marketing context before asking questionsin 16 of 858, across 6 files
  • Use Mermaid graph TD for visual sitemapsin 15 of 858, across 5 files
  • Ensure every page has at least one internal linkin 15 of 858, across 5 files
  • Use ASCII tree format for page hierarchy draftsin 15 of 858, across 5 files
  • Enforce lowercase URLs with hyphensin 15 of 858, across 5 files

Said here and by no other author read

  • Parse requirements into functional and non-functional categories
  • Evaluate library candidates using consistent dimensions
  • Compare alternatives in a table with explicit trade-offs
  • Select the minimum patterns required for the problem
  • Map selections to existing project conventions
  • Define component structure and data flow

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.

Keep looking

Skills are one crate of 325,949. 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.