GitHub: https://github.com/sirius-zuo/architect-skills
It's a set of LLM agent skills focused on software architecture analysis and review. The repo includes two main skills plus shared resources:
- architect-design-review: Reviews an approved design spec before implementation starts. It generates architecture diagrams (Mermaid.js), evaluates against a comprehensive set of principles, and produces a beautiful HTML report.
- architect-codebase-review: Analyzes an existing codebase, maps its current architecture (with real evidence from the code), evaluates it, and proposes recommended improvements with revised diagrams.
Both skills output self-contained HTML reports with embedded interactive Mermaid diagrams, saved to docs/architecture/review/. No heavy dependencies—just an internet connection for Mermaid rendering via CDN.
Core Features That Make It Stand Out
- Dynamic, Extensible Review Framework All evaluation criteria live in a single architect-shared/architecture-principles.md file. Each ## section (e.g., Separation of Concerns, Scalability, Data Architecture, Observability, Security, Reliability, Domain-Driven Design elements, AI Architecture, Multi-Tenancy, etc.) becomes a report section automatically.
- Add new domains by simply adding a new heading with "Applies to: design, codebase" markers.
- Findings are classified as ✅ Strength, ⚠️ Concern, or ❌ Risk, with clear signals of violation. This keeps everything maintainable and evolving without forking skills.
- Rich Architecture Diagrams
- Always generates: System Context and Component diagrams.
- Proposes additional ones (Application, Data, Sequence, Integration, Deployment) based on project context and waits for your confirmation.
- Current-state (for codebase reviews) + recommended future-state diagrams. Diagrams use real names from your spec or code, with careful syntax validation to avoid Mermaid headaches.
- Agent-Native Workflows Designed for tools like Claude Code (with slash-command support and automatic hooks, e.g., run after spec approval). Easy integration for Cursor, Copilot, etc., via rules files.
- Strict content isolation and non-goals (no modifying code, no running tests, read-only where appropriate).
- Handles different project sizes with context management.
- Produces clean, actionable reports with executive summaries, findings, and prioritized recommendations.
Why This Matters Now
Modern software is complex. Microservices, event-driven systems, AI components, multi-tenancy, cloud-native deployments—getting the architecture right upfront saves massive refactoring pain later. Human architects are expensive and not always available for every feature or legacy review. These skills bring systematic, principle-based review into your daily AI-assisted workflow.
Imagine:
- After brainstorming a new feature spec, your agent automatically runs a design review and flags issues like missing caching strategy, poor separation of concerns, or unversioned APIs.
- For legacy projects, a codebase review quickly surfaces god modules, circular dependencies, observability gaps, or deployment anti-patterns, complete with "before/after" diagrams.
It's MIT-licensed, lightweight (mostly shell + Markdown), and community-extensible.
Quick Start (Claude Code recommended)
Bash
git clone https://github.com/sirius-zuo/architect-skills.git
cd architect-skills
./install.sh claude
Add a hook to your ~/.claude/CLAUDE.md for automatic design reviews. For other agents, copy the relevant SKILL.md + shared files into rules directories and prompt accordingly. Full instructions in the README.
Example Principles Covered (partial list)
- Separation of Concerns, Cohesion & Coupling, Layered/Hexagonal Architecture
- Scalability (statelessness, caching, async, partitioning)
- Observability, Security (OWASP-aware), Reliability & Resilience
- Data Architecture, Cost Efficiency (FinOps), Operability
- Deployment, Event-Driven, AI Architecture, Multi-Tenancy, Governance, and more.
No more "it works on my machine" architecture. This encourages explicit decisions, trade-off documentation, and drift detection.
If you're building serious software—web apps, services, libraries, AI systems—this can be a game-changer for consistency and long-term maintainability. Even solo devs or small teams benefit hugely.
Star it if you find it useful, contribute new principles or diagram rules, or share your review reports (anonymized, of course). Feedback welcome—especially on real-world usage!
What are your biggest architecture pain points with AI coding agents? Have you tried similar skills? Let's discuss in the comments.
Link again: https://github.com/sirius-zuo/architect-skills
Top comments (1)
The architecture-principles.md as single source of truth is the right move — operator authors the rules the model can't pick, findings get classified ✅/⚠️/❌ against a structured spec. That works for catching the obvious cases. The harder cases sit one floor up.
Where the system stops being a real second view: the principles file is operator-authored (genuinely outside the model's control path), but the evaluation against those principles is still LLM judgment over LLM-written architecture. If both the design spec and the review pass run through the same model class, you've moved the work into a structured form without changing who's checking whom. Works for principles the model is reliably bad at remembering ("did you specify observability?") — less reliable for principles it can confidently fake ("yes, separation of concerns is good here").
The structural extension I'd reach for: keep the principles file as the operator-authored spec, but pair each principle with a deterministic analyzer where one exists — coupling-graph for separation of concerns, log-statement density for observability, dependency-direction check for hexagonal layering. LLM stays useful for surfacing candidate violations, but the verdict comes from a check that doesn't depend on the model agreeing with itself. That's the structural fix that turns "structured review" into actual drift detection.