Guide · Agent skill
How to use the Architecture Designer agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Architecture Designer is an agent skill that makes your AI agent behave like a senior software architect when you ask about system design. It is aimed at engineers and tech leads who are planning a new service or system, or reviewing an existing one, and want a structured design document with the trade-offs made explicit. After following this guide you will know what the skill is, how to install it, how to trigger it with plain requests, and what to check before relying on its output.
Architecture DesignerJeffallan/claude-skills · MIT Download the skill Quick start
- 1Download the ZIP. Download the architecture-designer ZIP from this skill page.
- 2Unzip the folder. Unzip it so the architecture-designer folder contains SKILL.md and the references folder.
- 3Place it where the agent can find it. Copy the folder to ~/.claude/skills/ for personal use, or to a project's .claude/skills/ folder for one project.
- 4Or upload it in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill.
- 5Describe your architecture task. Ask in plain language, for example to design a system, compare monolith and microservices, or write an ADR, and include requirements and constraints.
- 6Review the output with your team. Check the requirements summary, diagram, ADRs and risk list with people who know the system before acting on them.
What an agent skill is and what this one does
An agent skill is a folder of instructions and reference files that an AI agent can load when a task matches the skill's description. This skill is triggered by requests about high-level system architecture, such as designing a new system, reviewing an existing design, or making an architectural decision.
When active, the agent gathers requirements, compares patterns such as monolith versus microservices, weighs technology trade-offs, and produces a structured design. The source describes the output as a requirements summary, a Mermaid architecture diagram, ADRs for key decisions, technology recommendations with rationale, and a list of risks with mitigations.
- Compares architectural patterns, including monolith, modular monolith, microservices, serverless and event-driven
- Writes Architecture Decision Records (ADRs) for significant decisions
- Produces Mermaid architecture diagrams
- Loads reference templates for ADRs, system design, database selection, architecture patterns and non-functional requirements when they are relevant
Install the architecture-designer skill
Download the ZIP from the skill's page on this directory and unzip it. The skill is a folder containing SKILL.md and a references folder with five files: adr-template.md, architecture-patterns.md, database-selection.md, nfr-checklist.md and system-design.md.
For a personal install, place the unzipped folder in ~/.claude/skills/. To limit the skill to one project, place it in that project's .claude/skills/ folder instead.
If you use the Claude apps, you can upload the skill instead. Go to Settings → Capabilities → Skills and upload it there.
- Personal install: ~/.claude/skills/architecture-designer
- Project install: .claude/skills/architecture-designer inside your project
- Claude apps: Settings → Capabilities → Skills
Trigger the skill with natural requests
You do not need a special command. The skill is selected from the wording of your request, so describe the architecture task in plain language. The skill's own trigger terms include architecture, system design, design pattern, microservices, scalability, ADR, technical design and infrastructure.
Give the agent context. Requirements, scale expectations and existing constraints lead to much better output than a one-line question, because the skill starts by gathering requirements.
- "Design an architecture for a booking service that needs to handle peak traffic on weekends."
- "Should we split our monolith into microservices? Compare the options and write an ADR."
- "Review this existing architecture and list the trade-offs and risks."
- "Write an ADR for choosing PostgreSQL as the primary store for our orders."
What a typical session produces
The skill's core workflow is: understand requirements, identify patterns, design with trade-offs documented and a diagram, document key decisions as ADRs, then review with stakeholders. If review fails, the workflow returns to the design step with recorded feedback.
The source includes an example Mermaid diagram of a client, API gateway, auth service, order service, orders database, message queue and notification service. Its ADR example records a decision to use PostgreSQL for order storage, with status, context, decision, alternatives and consequences sections.
graph TD
Client["Client (Web/Mobile)"] --> Gateway["API Gateway"]
Gateway --> AuthSvc["Auth Service"]
Gateway --> OrderSvc["Order Service"]
OrderSvc --> DB[("Orders DB\n(PostgreSQL)")]
OrderSvc --> Queue["Message Queue\n(RabbitMQ)"]
Queue --> NotifySvc["Notification Service"]Safety notes: scripts and network access
According to the listing, this skill does not run scripts and does not use the network. It lists no requirements. Even so, review any skill's files before installing it, and treat the output as advice to check rather than a finished decision.
- Runs scripts: no
- Uses network: no
- Requires: nothing listed
- The skill's constraints say to consider security explicitly, but security review still belongs to your team
Tips for better architecture output
The skill's own rules say to understand requirements before designing, consider non-functional requirements explicitly, and avoid over-engineering for hypothetical scale. Feed it real numbers and real constraints where you have them, and ask it to name the alternatives it rejected.
Use the output as a draft. Stakeholders who know the system should check requirements and risks before anything is approved.
- State functional and non-functional requirements, including scale, latency and compliance constraints
- Ask for alternatives and trade-offs, not only a recommendation
- Ask for the ADR to be saved as a file so the team can review and version it
- Share the Mermaid diagram with your team and update it as the design changes
What people use it for
- Planning a new service and getting a structured design document with a diagram and risk list
- Comparing a monolith against microservices for a growing codebase and recording the decision as an ADR
- Writing consistent ADR write-ups for important technical choices such as a database
- Reviewing an existing architecture to make its trade-offs and failure modes explicit
- Planning scalability for a system expected to grow
Frequently asked questions
How do I install the architecture designer skill?
Download the ZIP from this skill's page and unzip it. Place the folder in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder for one project. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.
Does the architecture designer skill require anything else to run?
The listing states that it requires nothing and does not run scripts or use the network. It is a set of instructions and reference files the agent reads.
Is the architecture designer skill free?
The skill is published under the MIT licence. The source does not list pricing, so check the licence terms and your own agent platform's terms for any costs.
Can it replace a software architect?
No. The output is advisory and can be wrong for your constraints if requirements are not checked by people who know the system. Stakeholder review is part of the skill's own workflow.
What is the difference between this skill and a code-level design pattern skill?
This skill covers high-level system architecture, such as patterns like monolith versus microservices, technology trade-offs and ADRs. Its description says it is distinct from code-level design patterns and database-only design tasks, so use a different skill or resource for those.
Why doesn't my agent use the skill?
The skill is chosen from your request's wording, so try including terms like system design, architecture, ADR or microservices. Also confirm the folder is in the correct location and contains SKILL.md at its top level.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are an engineer or tech lead who wants a structured, consistent design document and explicit ADRs for a new system or an architecture review. Pick something else for code-level patterns, small refactors, pure database schema work, or if you need a finished, approved architecture without expert review.
Download the skill