common-system-design
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. (triggers: architecture, design, system, scalability, microservice, module boundary, coupling)
76
69%
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
82%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a reasonably well-structured skill description that covers both what and when with explicit triggers. Its main weakness is that the capabilities described are somewhat abstract (principles and patterns rather than concrete deliverables) and some trigger terms are broad enough to risk overlap with other skills. The explicit trigger list and 'Use when' clause are strong structural elements.
Suggestions
Replace abstract principle names with concrete actions the skill performs, e.g., 'Generates architecture diagrams, recommends module decomposition strategies, reviews code for coupling violations' instead of 'enforce separation of concerns'.
Narrow overly broad triggers like 'design' and 'system' to more specific variants like 'system design', 'software architecture', 'service decomposition' to reduce conflict risk with unrelated skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names a domain (architecture/design) and mentions some actions like 'designing new features', 'evaluating module boundaries', 'selecting architectural patterns', and 'resolving scalability bottlenecks', but these are fairly high-level and not concrete deliverables. Terms like 'enforce separation of concerns' and 'dependency inversion' describe principles rather than specific actions the skill performs. | 2 / 3 |
Completeness | The description clearly answers both 'what' (enforce separation of concerns, dependency inversion, resilience patterns across layered/distributed architectures) and 'when' (designing new features, evaluating module boundaries, selecting architectural patterns, resolving scalability bottlenecks) with an explicit 'Use when' clause and trigger terms. | 3 / 3 |
Trigger Term Quality | The description includes an explicit trigger list with natural terms users would say: 'architecture', 'design', 'system', 'scalability', 'microservice', 'module boundary', 'coupling'. These are terms developers naturally use when seeking architectural guidance, providing good keyword coverage. | 3 / 3 |
Distinctiveness Conflict Risk | While the architectural focus is somewhat specific, terms like 'design', 'system', and 'scalability' are broad enough to potentially overlap with other skills (e.g., database design, API design, performance optimization). The mention of 'microservice' and 'module boundary' helps narrow the niche, but 'architecture' and 'design' are quite generic triggers. | 2 / 3 |
Total | 10 / 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, serving as a good architectural overview with appropriate references to deeper material. However, it suffers significantly from a lack of actionability — it reads as a checklist of principles rather than executable guidance. Adding concrete examples (e.g., an ADR template, a sample module boundary definition, or a circuit breaker implementation snippet) would dramatically improve its utility.
Suggestions
Add a concrete ADR template or example showing what a completed Architecture Decision Record looks like for the workflow step 5.
Include at least one concrete, executable example — such as a dependency injection pattern in code, a sample event-driven communication setup, or a circuit breaker implementation — to move from abstract principles to actionable guidance.
Add validation criteria or checkpoints to the workflow (e.g., 'Verify no circular dependencies exist between modules before proceeding to step 3').
| 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 skill is entirely abstract guidance with no concrete code, commands, specific examples, or executable artifacts. It describes principles and patterns at a high level but never shows how to implement them — no ADR template, no code snippets, no concrete module boundary example. | 1 / 3 |
Workflow Clarity | The 5-step workflow for evaluating architecture is listed with a clear sequence, but lacks validation checkpoints, feedback loops, or criteria for determining success at each step. For architectural decisions that can have significant downstream impact, the absence of explicit validation/review steps is a gap. | 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. | 3 / 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
- HoangNguyen0403/agent-skills-standard
- Commit
19a1140
- 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.