Stage 2 · design

Solution architect pack reference

Every skill in the Solution architect pack — what it makes, when to use it, what it needs, its quality bar, and what it hands off to.

Design-phase artifacts: diagrams, decision records, design docs, contracts, schemas, threat models, and the reviews that gate them.

Skills

adr-generator

Generate an Architecture Decision Record (ADR) from a context-decision-consequences brief. Supports the two common formats — MADR (Markdown Any Decision Records) and Michael Nygard's original ADR template.

Tier standard · v0.1.1 · SKILL.md · skill page

Use it when Use whenever the user wants to capture an architectural decision, write an ADR, or document a "we decided X because Y" moment.

A good result:

• Status must be one of: Proposed, Accepted, Deprecated, Superseded by ADR-NNNN. Default to Proposed unless the user says it's already been agreed. "We decided", "we chose" and "we're going with" all say it was agreed: write Accepted.
• Title is a noun phrase, not a verb phrase. ✅ "Postgres as the primary datastore" — ❌ "Decide what database to use".
• Consequences must include trade-offs, not just upsides. If you can't list a downside, the decision wasn't real.
• Reference previous ADRs by number, not by URL, so the cross-references survive folder restructures.
• Don't editorialize. An ADR records what was decided, not what you (the AI) think was wisest.

api-contract-draft

Draft an OpenAPI 3.1 contract from a feature brief or story — resource-oriented paths, a full error catalog (RFC 9457), pagination/idempotency/versioning decided not deferred, examples on every operation, plus a decisions log so review argues choices instead of YAML.

Tier standard · v0.1.2 · SKILL.md · skill page

Use it when the user wants to design an API, draft an OpenAPI/Swagger spec, define request/response shapes, or agree a contract between frontend/backend or two teams before code.

A good result:

• The YAML validates. OpenAPI 3.1, parseable, refs resolve. A contract that doesn't lint is a sketch.
• Every operation enumerates its 4xx set with stable code values a client can switch on. "400: Bad Request" alone is an unwritten error contract.
• Every decision in the log has a rationale, and every deviation from reference.md conventions is logged as a decision — silent deviation is how two services end up with three pagination styles.
• Examples look like production data. "id": "string" in an example means nobody pictured a real call.
• No float money, no naked timestamps, no stringly-typed enums. The three classic contract regrets, all preventable at draft time.
• Unsafe operations state their idempotency story. A reviewer can answer "what happens on retry?" for every POST.

Not for:

• Documenting an API that already exists — that's guide-builder (reference archetype)
• Choosing REST vs GraphQL vs gRPC — this skill starts after that choice is made
• An event, message or webhook contract — that's event-contract-draft
• Reviewing a contract someone else drafted — doc-critique or council-review
• Generating server/client code from the spec — hand the frozen contract to the codegen tool

architecture-diagrams

Generate architecture diagrams (Mermaid, PlantUML, C4) from a written description of a system. Supports AWS/Azure/GCP cloud topologies, microservice landscapes, sequence flows, container diagrams, and ER models.

Tier standard · v0.1.0 · SKILL.md · skill page

Use it when Use whenever the user asks for an architecture diagram, system sketch, flow diagram, or visualization of a design.

A good result:

• Fit on one screen. If you have more than ~15 nodes, split into two diagrams (e.g., "Context" and "Container") rather than cramming everything in.
• Show direction of data flow, not just connections. Arrows should mean something.
• Label every arrow that crosses a trust boundary or a network hop.
• Use subgraphs / groups to make zones explicit (VPC, public/private subnets, account boundaries, on-prem vs cloud).
• Be valid syntax. Mentally trace through the Mermaid/PlantUML once before responding. Common breakers: unescaped ( ) < > inside labels, missing end for subgraphs, mixing graph types.

Hands off to: figma-diagrams when the diagram needs to live where designers work.

data-contract

Draft a data contract for a dataset, table, or event stream consumed by others — schema with per-field semantics and units, measurable quality SLAs (freshness, completeness, validity, distribution), a schema-evolution policy that says what breaks consumers, a named owner, and PII classification.

Tier standard · v0.1.0 · SKILL.md · skill page

Use it when the user is publishing a dataset/table/topic other teams depend on, needs a data contract, or wants to stop downstream pipelines breaking on silent schema or quality changes.

A good result:

• Every field has a meaning and a unit/allowed-values, not just a type. The cents-vs-dollars class of bug is designed out at contract time.
• Every quality SLA has a threshold, a check, and a breach action. "High quality" is not an SLA; "freshness < 6h, checked hourly, breach pages the owner" is.
• The evolution policy names the silent killer — meaning-change-under-stable-name — as breaking. Most contracts miss it and most data incidents are it.
• Consumers are enumerated, so "breaking" is defined and notifications have an address. Unknown consumers are flagged, not assumed away.
• The asset has a named owner and per-field classification. No owner, no contract.
• Existing-asset contracts mark aspirational vs met. Claiming a freshness SLA the pipeline doesn't hit is how the contract loses its authority on day one.

Not for:

• A synchronous REST/RPC API or webhook — that's api-contract-draft
• The physical schema migration (expand/backfill/contract) — that's migration-plan
• System-wide NFRs for a service — that's nfr-spec; this is one data asset's guarantee
• A private dataset with exactly one consumer inside the same team — a comment in the code may suffice

design-doc

Generate a Google-style engineering design doc (problem, goals/non-goals, options considered, recommended approach, risks, rollout) from a feature brief or short description.

Tier standard · v0.1.3 · SKILL.md · skill page

Use it when the user wants to draft a design doc, technical proposal, or one-pager for an engineering review.

A good result:

• Non-goals are real, not throat-clearing. If your non-goals list reads "we're not solving world hunger", delete it. Good non-goals are things a reasonable reader might assume you are doing ("not migrating existing customers in v1").
• Alternatives have a why-not, not just a description. Two sentences each: what is it, why didn't we pick it.
• Risks have mitigations. A bare list of "things that could go wrong" is anxiety, not engineering.
• Rollout criteria are concrete. "We'll monitor closely" is not a criterion. "Roll forward to 100% if p99 < 80ms for 48h after 10% rollout" is.

Hands off to: architecture-diagrams when the design is written and needs rendering.

event-contract-draft

Draft the contract for an event or message interface (Kafka topics, SNS/SQS, EventBridge, Pub/Sub, RabbitMQ, webhooks) as an AsyncAPI 3.0 document plus a short decisions page — past-tense event names, a required envelope with event id for deduplication, the partition key and the ordering it does and doesn't give, at-least-once delivery and how consumers stay idempotent, data minimisation with PII marked, additive-only versioning with dated deprecation, and retention, replay and dead-letter handling.

Tier standard · v0.1.3 · SKILL.md · skill page

Use it when the user wants to define events, design a Kafka topic or message schema, write an AsyncAPI spec, agree what a producer publishes and what consumers must do, or version an event safely.

Needs: Python 3 for its scripts (standard library only).

A good result:

• Every event name is a past-tense fact in the producer's domain, one type per schema.
• Every message has the full envelope, required, with a stable event id for deduplication.
• Every channel names its key, the order it gives and the order it doesn't. No global order.
• Each consumer's idempotency is stated: dedupe on id, revision check, or a natural key.
• Every field has a consumer; personal data that stays is marked; nothing "just in case".
• Breaking changes go through a new field or version with a deprecation date that came from the input or is listed as open.
• Retention, replay and dead-letter are stated per channel, with the DLQ owner named or open.
• The check result is reported only if it ran, and the document has no FAIL.
• Nothing invented: no team names, dates, volumes or retention the input didn't give, except as [assumption].
• Every question asked is answered in its own line first, before the contract.
• The user's draft stays theirs: each change to their names, fields or shapes is listed with the rule it fixes, and nothing else is changed.
• The document is whole: saved complete, or shown complete, never cut off.

Hands off to: data-contract when an analytics team or a trained model reads the topic as a dataset.

Not for:

• A request/response HTTP API — api-contract-draft
• A table, dataset or analytics stream's schema, freshness and quality SLAs — data-contract
• Deciding whether the system should be event-driven at all, or its components — design-doc

figma-diagrams

Work with Figma and FigJam files via the Figma REST API — read existing file structure, list frames/pages, post comments, and produce FigJam-importable diagram specs.

Tier standard · v0.1.3 · SKILL.md · skill page

Use it when the user mentions a Figma URL, asks to inspect/audit a Figma file, wants to comment on a design programmatically, or wants their architecture diagram in Figma.

Needs: Python 3 for its scripts plus requests==2.34.2; environment: FIGMA_TOKEN.

A good result:

• Never log the token. Scripts use os.environ["FIGMA_TOKEN"]; don't pass it on the command line.
• Don't dump 5 MB of JSON to the user. Filter to pages/frames/groups (3 levels) and summarize.
• Confirm before posting comments. A comment is visible to anyone with file access — show the user the exact text and the file URL before calling post_comment.py.
• Handle 429s. The Figma API rate-limits (~25 req/min for some endpoints). If a script returns 429, back off and retry; don't loop.

interactive-diagram

Turn a codebase, a system description, a process or a database schema into one self-contained interactive HTML diagram (architecture, workflow, data flow, lifecycle, ERD, sequence, class, tree, timeline or waterfall) where every box and arrow cites the file and line or the words it came from, anything inferred is drawn dashed as an assumption, and each cited line is checked against the repository before the page is written. Laid out automatically, opens offline with no CDN, and exports SVG, PNG and Mermaid.

Tier standard · v0.2.5 · SKILL.md · skill page

Use it when the user asks to "visualize", "map" or "make an interactive diagram of" a repo, a request path, a pipeline, an approval process, a set of tables, an incident's events or a slow trace, or wants a diagram they can click through and share as one file.

Needs: Python 3 for its scripts (standard library only).

A good result:

• Every part and connection cites its source or is drawn as an assumption. No exceptions for the "obvious" ones.
• Every file citation was checked against the repository, with the count in the reply.
• Nothing on the map comes only from a README, a plan or what such systems usually have.
• The map answers one stated question, and what was left out is said.
• One HTML file that works offline: no CDN, no external fonts, no network requests.
• The link and the takeaway lead the reply, with at most one short line about the build before them and no account of how it was made.

Not for:

• A Mermaid, PlantUML or C4 diagram to paste into a doc — use architecture-diagrams
• An as-is architecture write-up in C4 levels from infrastructure files — use reverse-architecture
• Fixing or rendering an existing Mermaid diagram; the agent does that well on its own, with npx @mermaid-js/mermaid-cli for images
• Charts of numbers, dashboards or metrics — this draws structure, not data

nfr-spec

Sweep a feature or system through the full non-functional requirements catalog — performance, throughput, availability, durability, privacy/retention, accessibility, i18n, observability, operability, compatibility, cost — forcing every category to a measurable target, an explicit n/a, or a tagged default.

Tier standard · v0.1.0 · SKILL.md · skill page

Use it when the user needs NFRs, quality attributes, "how fast/reliable does it need to be", SLO targets for a feature, or the requirements everyone forgets until they're incidents.

A good result:

• Every category lands in one of three states — target, n/a-with-reason, or tagged default. The ledger shows all of them; silence fails the doc.
• Every target has a percentile, a load condition, and a verification. A latency number without load is a screenshot of a quiet day.
• Availability matches the down-for-an-hour answer, not the marketing instinct. The cost of each extra nine is named when the target exceeds the archetype default.
• Every data class has a retention period and a deletion mechanism. "Indefinite" is written as the decision it is.
• Accessibility names level and scope — "WCAG 2.2 AA on all agent-facing screens, axe + manual screen-reader pass" — not "accessible".
• Cost has a number at target volume, or a tagged [assumption] placeholder that explicitly hands the sizing to capacity-cost-model. Either way the line is present — an NFR spec that's silent on cost has delegated it to the first invoice.

Hands off to: design-doc when the quality targets are set; threat-model when the design has a trust boundary worth attacking; test-plan-generator when the targets need verifying, not just stating.

Not for:

• Functional requirements — that's prd-draft
• Security threat depth — one posture line here, the analysis is threat-model
• Designing the architecture that meets the targets — design-doc
• Writing the verification tests themselves — hand the methods to test-plan-generator

reverse-architecture

Reverse-engineer a system's architecture from what already exists — a code repo, Terraform / CloudFormation / Pulumi / Bicep, Kubernetes manifests, docker-compose, a database schema, an OpenAPI spec, or a package manifest — and produce a renderable diagram (Mermaid / C4 / PlantUML) plus a written description suitable for handing to architecture-diagrams.

Tier standard · v0.1.0 · SKILL.md · skill page

Use it when the user wants to draw the system that exists, not one they're proposing — for onboarding docs, audit reviews, migration planning, or filling in a missing "as-is" architecture diagram.

A good result:

• Every node has a source-of-truth file path. No node may appear in the diagram without an evidence reference. "I think there's also a worker" is not a node.
• Edges have direction and protocol where the source reveals them. payments-api --HTTPS--> stripe-api beats payments-api → stripe.
• Group by deployment boundary, not by application-layer concern. Subgraphs are VPC / cluster / account, not "data layer" vs "service layer" — the latter is component-level, not container-level.
• Don't pretend you saw what you didn't. If config says REDIS_URL=… but no Redis is in IaC, mark it external (unverified) rather than silently drawing it as "managed Redis".
• Cite the README's claims rather than parrot them. "README claims X uses Kafka. Verified: kafka-go in go.mod and Confluent client config in config/prod.yaml:14." Or: "README claims X uses Kafka — not verified, no Kafka client found in dependencies."

Not for:

• When the user is proposing something new — that's architecture-diagrams from a written description, not this.
• When the system is too small to need diagramming (one binary, one DB, no external deps). Tell the user a sentence is enough.
• When the only source is a deployed environment with no code/IaC access — this skill reads files; it doesn't introspect live AWS accounts.

threat-model

Produce a STRIDE threat model from a design doc, architecture description, or feature spec — assets and trust boundaries first, threats anchored to boundary crossings with concrete attack scenarios, severity-ranked with verifiable mitigations.

Tier heavy · v0.1.0 · SKILL.md · skill page

Use it when the user asks to threat-model a design, run a security review of an architecture, ask "how could this be attacked", or needs security sign-off input before build.

A good result:

• Every threat is anchored to a named trust-boundary crossing or asset. An unanchored finding is checklist residue — cut it.
• Every threat narrates a scenario with actor, path, and result. "X is possible" is not a finding.
• Severity spread is honest. A model where everything is critical (or nothing is) hasn't ranked anything; the 🟥 set is what you'd halt the build for.
• Every recommended mitigation has a verification step a reviewer can run or check. Advice without verification is a wish.
• Existing mitigations are credited — and marked verified vs assumed. A model that ignores what the design already does right teaches the team to ignore the model.
• The insider and authz sweeps produced output — findings or an explicit reasoned all-clear, never silence.

Not for:

• Reviewing written code for vulnerabilities — that's devils-advocate (its security lens) or sonar-review
• Compliance attestation (SOC2, PCI evidence) — this models attacks, it doesn't certify controls
• Incident analysis after an exploit — that's postmortem-generator
• Pen-testing a live system — this is paper analysis; it tells the pen test where to aim

Loops

design

Take a ratified requirement to a recorded architectural decision — constraints, structure, diagrams, threats, then a panel that must agree before the decision is written down.

Cap: 3 returns before BLOCKED. LOOP.md

Included from core

Installed with this pack. Details: Core pack reference.

• brief-intake: Turn raw mess — a Slack thread, meeting transcript, Jira ticket, half-written Notion page, email chain, or paragraph of free-form context — into a structured brief that the downstream skill (adr-generator, design-doc, runbook-generator, exec-summary, slide-outliner) can consume without further intake.
• context-graph: Map the decisions behind a codebase from its ADRs, RFCs and design records — each record's status and date, what supersedes or amends what, which records cite which, the files and folders each decision governs, and with git the commits that implemented it and the commits that changed each decision's code since it was made, and who made them — then answer "why is it like this?" from the record and check the record is still true. Finds supersessions only one side records, current decisions pointing at code that is gone, code that has drifted from its decision, two current decisions governing the same path, and references to records that don't exist.
• council-review: Convene a council of distinct senior-engineer personas (Architect, Security, Operator/SRE, Pragmatist, User-Advocate, plus optional bench seats) to deliberate a decision, design, or code change — each takes an independent stance, the genuine disagreements are surfaced as named cruxes, and a Chair issues a reconciled verdict that records dissents and states what would change the decision. The "Claude Council."
• doc-critique: Review an existing document — ADR, design doc, runbook, exec summary, tech-comparison matrix, deck outline, decision log — and produce a structured critique against the same quality bars the skilldrop generators enforce. Categorizes findings by severity (blocker / major / minor / nit), points to the exact section/line, and suggests a concrete fix for each.
• output-hygiene: Review agent-written text before it ships and strip the machine artifacts it carries — invisible Unicode, non-breaking spaces, homoglyphs, harness-added provenance trailers, trailing chat closers — then flag the prose tells a script cannot catch, each quoted with a rewrite.

Edit this page on GitHub · View source