architecture-design
Skill1 starsChanged 51 days agoMITView on GitHub
Design or review a system architecture with explicit trade-offs, failure modes, a threat model, and break scenarios. Use for "how should I architect X" questions involving scale, distributed state, edge/cloud, ML, or agents. Not for scaffolding a single simple service.
33 other projects use a version of this.
Adopted by
Most recently taken up by
- sauljabin/agentskillstheir own version, first seen Nov 15, 2026
- ishandutta2007/Awesome-Claude-Skillstheir own version, first seen Nov 8, 2026
- shkodnik1917/claude-brainlabtheir own version, first seen Nov 8, 2026
- SWEStash/swe-workflow-skillstheir own version, first seen Nov 8, 2026
- celestialdust/achilles-skillstheir own version, first seen Nov 1, 2026
- Lixiuxiu559/AgentForgetheir own version, first seen Nov 1, 2026
Used with
Projects with it also use results-report, daily-coding and 9 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
Galaxy-DawnSkillresults-report
This skill should be used when the user asks to "write an experiment report", "summarize experimental results", "do experiment retrospection", "write a results report", "写实验总结报告", "写实验复盘", or mentions turning completed experiment artifacts into a structured, decision-oriented research report. It assumes strict analysis should come from `results-analysis` first.
Also in 3 projects that use this
Clay-HHKSkilldaily-coding
Daily coding assistant that auto-triggers when writing/modifying code, providing a core checklist.
Also in 3 projects that use this
Clay-HHKSkillkaggle-learner
This skill should be used when the user asks to "learn from Kaggle", "study Kaggle solutions", "analyze Kaggle competitions", or mentions Kaggle competition URLs. Provides access to extracted knowledge from winning Kaggle solutions across NLP, CV, time series, tabular, and multimodal domains.
Also in 3 projects that use this
kharlamenkodevSkillbug-detective
Also in 4 projects that use this
Google CloudSkillcitation-verification
Verify that citations in a document resolve to real records and that claimed titles match. Use before trusting a document's reference list.
Also in 4 projects that use this
MicrosoftSkillweb-design-reviewer
This skill enables visual inspection of websites running locally or remotely to identify and fix design issues. Triggers on requests like "review website design", "check the UI", "fix the layout", "find design problems". Detects issues with responsive design, accessibility, visual consistency, and layout breakage, then performs fixes at the source code level.
Also in 4 projects that use this
- +2 more from Clay-HHK
Other versions33 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 33
- Galaxy-Dawn/claude-scholar★ 5.9ksame name
- derHaken/SuperAntigravity★ 439same name
- bkywksj/knowledge-base★ 340same name
- shawnpang/startup-founder-skills★ 331same name
- thomast1906/github-copilot-agent-skills★ 203same name
- GenerativeAgents/claude-code-book-chapter8★ 114same name
- shkodnik1917/claude-brainlab★ 36same name
- kumaran-is/claude-code-onboarding★ 35same name
- Vepricov/claude-brainlab★ 35same name
- bmad-labs/skills★ 19same name
23 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository32 other files it gives its agents.
- agent-system-designSkill
- api-contract-designSkill
- architecture-optimizationSkill
- ci-speedupSkill
- code-handoffSkill
- cross-ai-handoffSkill
- crypto-storage-auditSkill
- database-designSkill
- dataset-sourcingSkill
- distributed-debuggerSkill
- embedded-constrained-codingSkill
- freedom-to-operate-analysisSkill
- frontend-architectureSkill
- github-masterSkill
- idea-finderSkill
- ieee-paper-drafterSkill
- memory-leak-hunterSkill
- ml-model-selectionSkill
- ml-security-auditSkill
- mobile-platform-architectureSkill
- observability-designSkill
- patent-drafterSkill
- patent-novelty-evaluatorSkill
- performance-optimizationSkill
- project-scaffoldingSkill
- researcher-evaluatorSkill
- researcherSkill
- safety-compliance-scopingSkill
- scale-refactorSkill
- secure-code-reviewSkill
- slow-query-optimizerSkill
- test-architectSkill
The file
We split this skill into the rules it gives an agent
7 rules. 0 are common, 6 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 27 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
Get the numbers, once: If load, latency, availability, or cost targets are missing, ask for them in a single message of at most three …
- Distinctive: line 14
Reviewing an existing design?: Read the design doc or code you were given before proposing anything.
- Very specific: line 15
Load the checklist with the requirements: Before step 4, read references/failure-modes.md from this skill's base directory.
- Distinctive: line 31
Write each as one line, for example: *"Ride requests are written to Postgres synchronously (consistency) and fanned out to drivers through …
- Distinctive: line 33
If a design can't say which side it picked, the decision was deferred to production.
- Distinctive: line 56
If any answer is "undefined," that is the design's weak point.
- Distinctive: line 72
Keep it as short as the stakes allow.
“Common” is measured: kept by at least 6 in 10 of the 27 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Architecture Design
A diagram of boxes and arrows is not an architecture. An architecture is a set of trade-offs someone decided on purpose, plus an account of how the system fails. This skill produces both.
1. Set scope and budget
- Match depth to the stakes. A prototype or internal tool gets the short form: requirements, the three most important trade-offs, the top five failure modes, and the weakest point. A production system, anything handling money or personal data, or anything with ML or edge components gets the full form below.
- Get the numbers, once. If load, latency, availability, or cost targets are missing, ask for them in a single message of at most three questions. If the user can't or won't answer, state your assumptions as numbers and continue. Don't stall.
- Reviewing an existing design? Read the design doc or code you were given before proposing anything. Don't redesign parts that already work; say what you'd keep.
- Load the checklist with the requirements. Before step 4, read
references/failure-modes.mdfrom this skill's base directory. It lists failure modes and threats by component type, so you check against it instead of recalling them from scratch.
2. Requirements
- Functional: what the system must do, in a few bullets.
- Non-functional, as numbers: throughput, latency target (with percentile), availability, data durability, consistency needs, cost ceiling, and power or bandwidth budget for edge parts. "Fast" and "scalable" aren't requirements.
3. Decide the trade-offs
Name each decision and what it gives up. At minimum:
- Consistency vs. availability when the network partitions, and where in the system that line sits.
- Synchronous vs. asynchronous calls between components, and what happens when a downstream service is slow.
- Edge vs. cloud placement, and what happens when the connection between them drops.
- Who owns each piece of state, and which copy wins when two disagree.
Write each as one line, for example: "Ride requests are written to Postgres synchronously (consistency) and fanned out to drivers through a queue (availability). A queue outage delays dispatch; it doesn't lose rides."
If a design can't say which side it picked, the decision was deferred to production.
4. Components, data flow, and failure modes
- Draw the components and data flow as a Mermaid diagram, and list what crosses each boundary (data, format, protocol).
- For each component, use the checklist to state what happens when it is down, slow, overloaded, or fed bad data, and whether the system degrades or fails. For any ML component, state the fallback for low-confidence or out-of-distribution input.
5. Threat model
For each trust boundary in the diagram: what can an attacker send across it, what control stops them, and what stays exposed after that control. Include the ML and sensor threats from the checklist if those components exist.
6. Observability
Name the few signals that would detect each top failure mode from step 4, and which ones page someone. A failure you can't detect will be found by users.
7. Break it before calling it done
Walk through three concrete scenarios and say what breaks first in each:
- 10× the expected peak load.
- The most important stateful component unavailable for 15 minutes.
- A malicious or malformed input on the most exposed path.
If any answer is "undefined," that is the design's weak point. Say so.
Output
# Architecture: <system>
## Requirements (numbers, with stated assumptions)
## Trade-offs (one line each: decision → what it gives up)
## Diagram (mermaid) and boundary data
## Failure modes (component → down / slow / bad data → behavior)
## Threat model (boundary → attack → control → residual risk)
## Observability (signal → failure it detects → pages?)
## Break scenarios (scenario → what breaks first)
## Weakest pointKeep it as short as the stakes allow. A table row beats a paragraph.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

