senior-architect
by alirezarezvanisenior-architect is a Software Architecture skill for system design, ADRs, stack decisions, scalability reviews, dependency analysis, and architecture diagrams using included Python scripts and references.
This skill scores 84/100, making it a solid listing candidate for directory users who want an agent to perform architecture design, review, and analysis with reusable workflows and supporting scripts. It provides enough trigger guidance, reference material, and executable tooling to be more useful than a generic prompt, though users should note the lack of install instructions and the heuristic nature of the analysis tools.
- Strong triggerability: the frontmatter explicitly lists common user intents such as system architecture design, microservices vs monolith evaluation, database choice, dependency analysis, ADRs, and diagram generation.
- Good operational substance: SKILL.md includes quick-start commands, tool overviews, decision workflows, common commands, and links to reference documentation.
- Meaningful agent leverage: three scripts support architecture diagram generation, dependency analysis, and project architecture assessment, while references provide pattern trade-offs, system design workflows, and technology decision matrices.
- No install command or README is present in the skill path, so users may need to infer how to copy or run it within their Agent/Claude skills setup.
- The analysis scripts appear heuristic and pattern-based, so outputs should be treated as architectural review aids rather than definitive system assessments.
Overview of senior-architect skill
What senior-architect is for
senior-architect is a Software Architecture skill for turning vague system-design questions into structured architecture decisions, diagrams, dependency reviews, and implementation trade-offs. It is best suited for users who need an architecture plan, ADR-style reasoning, stack comparison, scalability review, or codebase-level architecture assessment rather than a generic brainstorming answer.
Best-fit users and jobs
Use the senior-architect skill when you are deciding between monolith, modular monolith, microservices, event-driven, CQRS, hexagonal, or clean architecture patterns. It is also useful for teams reviewing an existing repository because the included Python scripts can scan project structure, infer architectural layers, detect coupling, and generate Mermaid, PlantUML, or ASCII diagrams.
What makes it different
The skill combines prompt guidance with concrete repository tooling. Its references cover architecture patterns, system design workflows, and technology decision matrices; its scripts provide project diagram generation, dependency analysis, and architecture assessment. That makes it more practical than a plain “act as a senior architect” prompt when you need evidence from a codebase.
Important adoption constraints
The scripts are heuristic scanners, not formal architecture validators. They work best on conventional project structures and common ecosystems such as Node, Python, Go, Rust, Java, Docker, and Kubernetes. For highly custom monorepos, generated output should be treated as a starting point for review, not a final decision.
How to Use senior-architect skill
senior-architect install and first files to read
Install from the GitHub skill directory with:
npx skills add alirezarezvani/claude-skills --skill senior-architect
After install, read SKILL.md first for trigger scope and command examples. Then inspect:
references/architecture_patterns.mdfor pattern trade-offs and “when not to use” guidancereferences/system_design_workflows.mdfor capacity planning, API design, migration, and scalability workflowsreferences/tech_decision_guide.mdfor database, caching, queue, auth, frontend, cloud, and API style choicesscripts/architecture_diagram_generator.pyscripts/dependency_analyzer.pyscripts/project_architect.py
This reading path helps you understand both the reasoning framework and the runnable analysis tools before relying on the output.
Inputs that produce better architecture output
The senior-architect skill works best when you provide both business context and technical constraints. A weak prompt is: “Design a scalable backend.” A stronger prompt is:
Use senior-architect for Software Architecture. Design an architecture for a B2B analytics app with 50k tenants, 5M daily events, PostgreSQL today, Python/FastAPI backend, React frontend, AWS deployment, 99.9% availability target, small team of 6, and a requirement to support tenant-level data isolation. Compare modular monolith vs microservices, include risks, ADR summary, and a Mermaid component diagram.
Useful inputs include expected users, request volume, read/write ratio, latency target, availability target, data retention, compliance needs, team size, deployment environment, current stack, migration constraints, and decisions already rejected.
Practical senior-architect usage workflow
For a new system, start with the reference workflows: clarify functional requirements, estimate scale, identify non-functional requirements, then ask for candidate architectures with trade-offs. For an existing codebase, run the scripts before asking for recommendations:
python scripts/architecture_diagram_generator.py ./my-project --format mermaid
python scripts/dependency_analyzer.py ./my-project --output json
python scripts/project_architect.py ./my-project --verbose
Paste the most relevant findings into your prompt: detected pattern, coupling score, circular dependencies, missing layers, package manager, and any recommendations. This gives the model grounded evidence instead of forcing it to infer architecture from a vague description.
Prompt pattern for decisions and reviews
For design decisions, ask for an explicit decision format: context, options, decision criteria, recommended option, rejected alternatives, risks, migration plan, and open questions. For reviews, ask the skill to separate “observed facts” from “interpretation” and “recommended changes.” This reduces overconfident architecture advice and makes the output easier to convert into an ADR, roadmap item, or engineering proposal.
senior-architect skill FAQ
Is senior-architect only for large systems?
No. It can help small teams choose a simple architecture and avoid premature microservices. The included architecture pattern reference explicitly covers monolith and modular monolith trade-offs, so the skill is useful when the best answer is “keep it simpler.”
How is it better than an ordinary architecture prompt?
A normal prompt depends mostly on what you remember to include. The senior-architect skill adds reusable decision workflows, pattern references, technology comparison matrices, and codebase scanning scripts. That combination is especially valuable when you need repeatable architecture review rather than one-off advice.
Can beginners use this senior-architect skill?
Yes, but beginners should use it as a guided decision aid, not as an authority. Ask it to explain trade-offs, define terms, and label assumptions. If you do not know your scale, availability target, or operational constraints, ask the skill to list the missing questions before it recommends a design.
When should I not use it?
Do not use it as the sole source for security-critical, compliance-heavy, or production migration decisions. It is also not a replacement for profiling, load testing, cloud cost modeling, or expert review of a unique domain. For low-level implementation bugs, a language-specific debugging skill may be a better fit.
How to Improve senior-architect skill
Improve senior-architect inputs with measurable constraints
The most common failure mode is architecture advice that sounds plausible but is not actionable. Improve results by adding numbers: users, requests per second, storage growth, peak multiplier, latency budget, uptime target, team size, release frequency, and cost ceiling. Even rough estimates are better than adjectives like “high scale” or “enterprise grade.”
Use repository evidence before asking for changes
For existing projects, include script output and a short file-tree summary. Mention whether the code uses controllers/services/repositories, domain/application/infrastructure folders, Docker, Kubernetes, message queues, or multiple deployable services. This helps senior-architect distinguish intentional architecture from accidental folder naming.
Iterate from broad design to concrete artifacts
Do not stop at the first architecture proposal. Ask follow-ups for an ADR, Mermaid diagram, migration sequence, risk register, database choice, API boundary, or service ownership model. A good iteration path is: high-level design → trade-off comparison → chosen architecture → diagram → ADR → phased implementation plan.
Watch for overengineering and missing assumptions
If the output recommends microservices, event sourcing, CQRS, or distributed messaging, ask why the added operational complexity is justified. If assumptions are missing, request a revised answer that states unknowns and offers a simpler default. The best senior-architect usage keeps the design aligned with team capability, not just theoretical scalability.