architecture-general
Architecture decisions: layering, design patterns, microservices trade-offs, and domain-driven design
47
48%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/architecture-general/SKILL.mdQuality
Discovery
32%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description reads more like a topic list than a skill description. It lacks action verbs describing what the skill does, has no 'Use when...' clause, and doesn't clearly differentiate itself from general software engineering skills. The included terms are relevant but the description needs significant improvement in completeness and specificity.
Suggestions
Add concrete action verbs describing what the skill does, e.g., 'Evaluates architecture trade-offs, recommends design patterns, analyzes service boundaries, and models domains using DDD principles.'
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks about system architecture, service decomposition, choosing design patterns, layering strategies, or domain modeling.'
Include additional natural trigger terms users might say, such as 'system design', 'monolith', 'service boundaries', 'bounded contexts', 'DDD', 'CQRS', 'hexagonal architecture'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (architecture decisions) and lists some areas (layering, design patterns, microservices trade-offs, DDD), but these are still fairly abstract topics rather than concrete actions. No verbs describing what the skill actually does. | 2 / 3 |
Completeness | Only partially addresses 'what' (lists topics but no concrete actions) and completely lacks a 'when' clause. There is no explicit trigger guidance for when Claude should select this skill, which per the rubric should cap completeness at 2, but the 'what' is also weak enough to warrant a 1. | 1 / 3 |
Trigger Term Quality | Includes relevant keywords like 'architecture', 'design patterns', 'microservices', and 'domain-driven design' that users might naturally mention, but misses common variations like 'system design', 'software architecture', 'DDD', 'service boundaries', 'monolith vs microservices'. | 2 / 3 |
Distinctiveness Conflict Risk | Somewhat specific to software architecture decisions, but 'design patterns' and 'layering' could easily overlap with general coding or software engineering skills. The scope is broad enough to conflict with related skills. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
64%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured, concise architecture reference that efficiently covers layering, design patterns, microservices, and DDD. Its main weakness is the lack of concrete, actionable artifacts — no code examples, no ADR template, no decision-making workflow. It functions well as a quick-reference checklist but falls short of being a fully actionable guide.
Suggestions
Add a concrete ADR template example in a referenced file (e.g., `docs/decisions/TEMPLATE.md`) to make the 'Decisions to Document' section actionable.
Include at least one code example showing proper layering (e.g., a use case calling a repository interface with an infrastructure implementation) to ground the abstract guidance.
Add a brief decision-making workflow: e.g., 'When facing an architecture decision: 1. Document the context, 2. List alternatives, 3. Evaluate against trade-offs, 4. Record in ADR.'
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Every section is lean and information-dense. No unnecessary explanations of what architecture is or why it matters. The table format for design patterns is especially token-efficient. All content adds value Claude wouldn't inherently know about the user's preferred conventions. | 3 / 3 |
Actionability | The skill provides clear, specific guidance (e.g., 'dependencies flow inward only', 'no shared databases') but is entirely instructional with no concrete code examples, commands, or executable snippets. For an architecture guidance skill this is acceptable, but some concrete examples (e.g., a sample ADR template, a layering code snippet) would improve actionability. | 2 / 3 |
Workflow Clarity | The layering section implies a sequence and the ADR section describes what to document, but there's no explicit workflow for making architecture decisions (e.g., steps to evaluate trade-offs, when to create an ADR, how to validate a design). The content reads as a reference checklist rather than a guided process. | 2 / 3 |
Progressive Disclosure | The content is well-organized with clear section headers and a table, making it easy to scan. However, there are no references to supporting files (e.g., an ADR template, detailed microservices patterns guide, or examples). The mention of `docs/decisions/` for ADRs is good but no template or example is linked. For a standalone skill with no bundle, the organization is decent but could benefit from splitting detailed guidance into referenced files. | 2 / 3 |
Total | 9 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- ucdavis/ai-skills-registry
- Commit
c0b2e4b
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.