senior-architect
Makes and records architecture decisions (pattern, database, monolith vs services) as ADRs, backed by coupling and diagram tools
Install / Use
npx skills add borghei/Claude-Skills --skill senior-architectInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Data & AnalyticsSupported Platforms
Our assessment of senior-architect
senior-architect scores 87/100 on our quality scale, 400th of 608 Data & Analytics skills we index.
Its SKILL.md is 9.6 KB long, well organised into 12 sections with 1 code example: a thorough specification that gives an agent plenty to work with.
It has 817 GitHub stars, a meaningful sign that others use it.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so senior-architect is actively maintained.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-11-10. Automated pattern scan on 2026-11-10. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
senior-architect compared with similar skills
All 4 of these similar skills score higher than senior-architect; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| senior-architect (this skill)by borghei | 87 | 817 | 57d ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 117.6k | 9d ago | CLAUDE.md |
| Claude-Code-Game-Studiosby Donchitos | 100 | 39.9k | 8d ago | CLAUDE.md |
| x402by browser-use | 100 | 121.0k | 4d ago | SKILL.md |
| algorithmic-artby anthropics | 100 | 177.9k | 56d ago | SKILL.md |
Frequently asked questions
- How do I install senior-architect?
- Run
npx skills add borghei/Claude-Skills --skill senior-architect. The install tabs above show the steps for each supported agent. - Which AI agents does senior-architect work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is senior-architect safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is senior-architect still maintained?
- The repository was last updated about 2 months ago, so senior-architect is actively maintained.
Skill content
View source on GitHubname: senior-architect description: > Makes and records architecture decisions (pattern, database, monolith vs services) as ADRs, backed by coupling and diagram tools. Use when writing an ADR, choosing an architecture or database, or reviewing system structure. license: MIT + Commons Clause metadata: version: 1.2.0 author: borghei category: engineering domain: system-design updated: 2026-11-08 tags: [system-design, distributed-systems, architecture, adr, scalability]
Senior Architect
Architecture design and analysis tools for making informed technical decisions: visualize system structure, analyze dependencies and coupling, detect architectural patterns, and run decision workflows for databases, patterns, and monolith-vs-microservices trade-offs.
Decision Workflow
The value of this skill is the decision and its record; the tools supply evidence.
- Frame the decision: one question (for example "split billing out of the monolith?"), the constraints (team size, deployment cadence, data consistency, budget) and who decides.
- Gather evidence from the code:
dependency_analyzer.pyfor coupling and cycles,project_architect.pyfor the current pattern and layer violations,architecture_diagram_generator.pyfor a current-state diagram. Low confidence orunknownlayers mean the structure does not follow naming conventions; read the code rather than trusting the label. - Run the matching workflow in references/decision_workflows.md: database selection, pattern selection, or monolith vs microservices. Write down at least two real options and the cost of each.
- Write the ADR (template in the same reference): context, options, decision, consequences, and the signal that would make you revisit it.
- Done when the ADR is accepted by the people who will own the result, and the evidence it cites can be regenerated by rerunning the tools.
Not this skill: cloud-provider service design (see engineering/aws-solution-architect, engineering/azure-cloud-architect, engineering/gcp-cloud-architect), choosing between frameworks or vendors (see engineering/tech-stack-evaluator), and backend implementation (see engineering/senior-backend).
Core Capabilities
- Diagram generation — produce component, layer, and deployment diagrams in Mermaid, PlantUML, or ASCII from a project directory.
- Dependency analysis — map the dependency tree, score coupling (0-100), and detect circular dependencies across npm, pip, Poetry, Go modules, and Cargo.
- Pattern detection — assess an existing codebase for layered/MVC/hexagonal/clean/microservices patterns, layer violations, god classes, and mixed concerns.
- Database selection — match data characteristics, scale, and consistency needs to SQL/NoSQL options with an ADR template.
- Pattern & topology selection — choose an architecture pattern by team size, deployment, and data-boundary requirements.
- Monolith vs microservices — apply decision checklists and a modular-monolith-first hybrid strategy.
When to Use
- Designing a new system or refactoring existing architecture.
- Evaluating microservices vs monolith, or choosing a database.
- Writing an ADR, planning for scalability, or reviewing a system design.
- Generating architecture diagrams for documentation or team review.
Clarify First
Before generating diagrams or an assessment, settle the inputs below. When one is missing or vague and would change the result, ask about it; when it wouldn't, use a sensible default and say which one you used.
- Project root: the codebase directory to analyze (drives pattern detection, dependency scoring, and diagram contents).
- Diagram type & format: component / layer / deployment in Mermaid / PlantUML / ASCII (sets what the generator emits).
- Architecture decision in question: e.g. database choice or monolith vs microservices (selects the decision workflow and ADR).
Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, produce it and state your assumptions at the top.
Tools Overview
| Tool | Purpose | Command |
|------|---------|---------|
| architecture_diagram_generator.py | Component, layer or deployment diagrams (Mermaid, PlantUML, ASCII) from a project directory | python3 scripts/architecture_diagram_generator.py ./project --format mermaid --type component |
| dependency_analyzer.py | Coupling score (0-100) and circular dependencies across npm, pip, Poetry, Go modules and Cargo | python3 scripts/dependency_analyzer.py ./project --output json --check circular |
| project_architect.py | Pattern detection, layer violations and code smells, with a confidence score | python3 scripts/project_architect.py ./project --check layers --verbose |
Exit codes: 0 report (or check passed); 1 a --check gate failed (cycles found, coupling above 70); 2 missing or unreadable project path. --output json applies to the --check gates too. Detection is name-based: folders called services/ or domain/ are read as layers, so treat a low confidence score as "no clear pattern", not as a finding.
Quick Start
# from engineering/senior-architect/ (a small layered Python app with one deliberate back-reference)
python3 scripts/project_architect.py assets/sample_layered_app # Layered, 55% confidence
python3 scripts/dependency_analyzer.py assets/sample_layered_app --output json --check circular # exit 1: one cycle
python3 scripts/architecture_diagram_generator.py assets/sample_layered_app --format mermaid --type layer
The cycle is controllers -> services -> repositories -> controllers: the repository imports the controller, which is the kind of finding an ADR or a refactor ticket should record.
Reference Documentation
Load the reference that matches the task — keep this file lean and pull detail on demand:
- references/architecture_patterns.md — 9 architecture patterns (monolith, modular monolith, microservices, event-driven, CQRS, event sourcing, hexagonal, clean, API gateway) with trade-offs and code examples. Read when asked "which pattern?", "microservices vs monolith", "event-driven", or "CQRS".
- references/system_design_workflows.md — 6 step-by-step workflows: design interview, capacity planning, API design, database schema design, scalability assessment, migration planning. Read when asked "how to design?", "capacity planning", "API design", or "migration".
- references/tech_decision_guide.md — decision frameworks and comparison matrices for database, caching, message queue, auth, frontend framework, cloud provider, and API style. Read when asked "which database/framework/cloud/cache?".
- references/decision_workflows.md — the database-selection, architecture-pattern-selection, and monolith-vs-microservices decision workflows with matrices, checklists, and the ADR template. Read when making a documented architecture decision.
- references/tools-and-usage.md — detailed per-tool usage, example outputs, full flag tables, common-command catalog, tech-stack coverage, troubleshooting table, and success criteria. Read when running the scripts or interpreting their output.
Anti-Patterns
Mistake: Choosing microservices for a small team or an unclear domain. Why it matters: Service boundaries drawn before the domain is understood get redrawn at the cost of distributed-systems complexity. Instead: Start with a modular monolith with enforced module boundaries, and extract a service when a boundary has proved stable and has its own scaling or release need.
Mistake: A decision with no written record. Why it matters: Six months later nobody remembers why, so the decision is relitigated or silently reversed. Instead: Write a short ADR with the options considered and the trigger for revisiting it.
Mistake: Treating tool output as the architecture review. Why it matters: Coupling scores and pattern labels are heuristics; they miss runtime coupling such as shared databases and synchronous call chains. Instead: Use the tools to find where to look, then review data ownership and call paths by hand.
Files
| File | Purpose |
|------|---------|
| scripts/architecture_diagram_generator.py, scripts/dependency_analyzer.py, scripts/project_architect.py | Stdlib CLIs |
| references/decision_workflows.md | Decision workflows and the ADR template |
| assets/sample_layered_app/ | Controllers, services, repositories and models with a repository-to-controller import cycle |
| references/tools-and-usage.md | Full flags, example outputs and troubleshooting |
Scope & Limitations
Covers: system-level architecture analysis (pattern detection, layer validation, component diagramming) for existing codebases; technology-agnostic dependency analysis across npm, pip, Poetry, Go modules, and Cargo; architecture decision workflows (database, pattern, monolith-vs-microservices); diagram generation in Mermaid, PlantUML, and ASCII.
Does NOT cover:
- Runtime performance profiling or load testing — use
senior-devops(capacity planning) andsenior-qa(performance test harnesses). - Security vulnerability scanning of dependencies — use
senior-securityorsenior-secopsfor CVE/SAST/DAST. - Frontend component architecture and design-system auditing — use
senior-frontendanddesign-auditor. - CI/CD pipeline design and deployment orchestration — use
senior-devopsandrelease-orchestrator.
Related Skills
taste-skill
117.6kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Claude-Code-Game-Studios
39.9kTurn Claude Code into a full game dev studio — 49 AI agents, 75 workflow skills, and a complete coordination system mirroring real studio hierarchy.
x402
121.0kSet up Browser Use Cloud payments with x402 — pay per request from a crypto wallet (USDC on Base mainnet), no signup or API key.
algorithmic-art
177.9kCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
