Enforce separation of concerns, dependency inversion, and resilience patterns across layered and distributed architectures. Use when designing new features, evaluating module boundaries, selecting architectural patterns, or resolving scalability bottlenecks.
68
62%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.github/skills/common/common-system-design/SKILL.mdQuality
Discovery
67%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 has good structural completeness with a clear 'Use when...' clause and identifies a specific domain (software architecture). However, it leans heavily on abstract architectural jargon rather than concrete actions or deliverables, and the trigger terms could better match natural user language. The scope, while narrower than generic coding skills, could still overlap with related design or code review skills.
Suggestions
Add more concrete actions/outputs such as 'review code for architectural violations', 'propose module decomposition', or 'generate dependency diagrams' to increase specificity.
Include more natural user-facing trigger terms like 'system design', 'microservices', 'clean architecture', 'how to structure', 'coupling', or 'monolith' to improve keyword coverage.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names specific architectural concepts (separation of concerns, dependency inversion, resilience patterns) and some actions (designing features, evaluating module boundaries), but these are more abstract principles than concrete actions. It doesn't list specific deliverables or outputs like 'generate architecture diagrams' or 'refactor modules'. | 2 / 3 |
Completeness | Clearly answers both 'what' (enforce separation of concerns, dependency inversion, resilience patterns across layered/distributed architectures) and 'when' with an explicit 'Use when...' clause covering four trigger scenarios (designing features, evaluating module boundaries, selecting patterns, resolving scalability bottlenecks). | 3 / 3 |
Trigger Term Quality | Includes some relevant terms like 'architectural patterns', 'scalability bottlenecks', 'module boundaries', and 'dependency inversion', but these lean toward technical jargon. Missing more natural user phrases like 'how should I structure my code', 'microservices', 'clean architecture', 'layered architecture', or 'system design'. | 2 / 3 |
Distinctiveness Conflict Risk | The scope is somewhat specific to software architecture, but terms like 'designing new features' and 'selecting architectural patterns' are broad enough to overlap with general software design or code review skills. The focus on 'layered and distributed architectures' helps narrow it, but could still conflict with microservices-specific or general design pattern skills. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
57%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill is well-structured and concise, with excellent progressive disclosure to reference files. However, it reads more like a glossary of architectural principles than an actionable skill — it lacks concrete examples, code snippets, ADR templates, or specific decision frameworks that would make it truly useful for Claude when designing or evaluating architectures. The workflow is present but lacks validation steps.
Suggestions
Add a concrete ADR template or example showing what a completed Architecture Decision Record looks like for a real scenario
Include at least one executable example — e.g., a code snippet showing dependency injection, an interface-based communication pattern, or a circuit breaker implementation
Add validation checkpoints to the workflow, such as 'Review dependency graph for circular dependencies' or 'Verify no layer skipping in the dependency direction'
Replace abstract definitions (e.g., 'Use interfaces for communication') with specific, actionable guidance (e.g., 'Define a port interface in the domain layer; implement adapters in the infrastructure layer')
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient, using bullet points and brief definitions without explaining concepts Claude already knows. Every section is tightly written with no unnecessary padding or verbose explanations. | 3 / 3 |
Actionability | The content is almost entirely abstract principles and definitions with no concrete code, commands, or executable examples. Guidance like 'Use interfaces for communication' and 'Inject dependencies, don't hardcode' describes rather than instructs — there are no specific implementation patterns, code snippets, or copy-paste ready artifacts. | 1 / 3 |
Workflow Clarity | The workflow section lists 5 steps in sequence, but lacks validation checkpoints or feedback loops. There's no guidance on what to do if bounded contexts are wrong, if CAP trade-offs reveal conflicts, or how to verify the architecture is sound before proceeding to documentation. | 2 / 3 |
Progressive Disclosure | The skill provides a clear overview with well-signaled one-level-deep references to specific topics (distributed-systems.md, resilience-patterns.md, implementation.md). Content is appropriately split between the overview and reference files with clear navigation. | 3 / 3 |
Total | 9 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
metadata_version | 'metadata.version' is missing | Warning |
metadata_field | 'metadata' should map string keys to string values | Warning |
Total | 9 / 11 Passed | |
4c72e76
Table of Contents
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.