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.
52
58%
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 ./.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 is structurally well-formed with a clear 'what' and 'when' clause, which is its strongest aspect. However, the capabilities described are somewhat abstract and jargon-heavy rather than listing concrete deliverables, and the trigger terms lean technical rather than matching natural user language. The scope is broad enough that it could overlap with adjacent skills around code design, refactoring, or system design.
Suggestions
Add more natural trigger terms users would actually say, such as 'system design', 'microservices', 'clean architecture', 'how to structure', 'coupling/cohesion', or 'monolith'.
Replace abstract verbs like 'enforce' with concrete actions/outputs, e.g., 'Review module dependencies and suggest refactoring, generate architecture diagrams, recommend resilience patterns like circuit breakers and retries'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names specific architectural concepts (separation of concerns, dependency inversion, resilience patterns) and mentions layered/distributed architectures, but the actions are somewhat abstract ('enforce', 'designing', 'evaluating', 'selecting', 'resolving') rather than concrete deliverables 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 boundaries, selecting patterns, resolving 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 app', 'microservices', 'clean architecture', 'coupling', 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 coding skills, code review skills, or design pattern skills. It could conflict with more focused skills around microservices, API design, or code structure. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
50%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, effectively organizing architectural concepts into scannable sections without unnecessary verbosity. However, it reads more like a glossary of architectural principles than an actionable skill — it lacks concrete examples, executable guidance, specific decision frameworks, or templates (e.g., an ADR template) that would make it truly useful. The referenced bundle files are missing, undermining the progressive disclosure structure.
Suggestions
Add concrete, actionable examples for key patterns — e.g., a sample ADR template, a specific dependency injection code snippet, or a decision matrix for choosing between sync REST vs async events.
Include a concrete example of evaluating architecture for a new feature, walking through the 5-step workflow with a realistic scenario to demonstrate how to apply the principles.
Provide the referenced bundle files (references/implementation.md, references/distributed-systems.md, references/resilience-patterns.md) or remove the broken references.
Add validation checkpoints to the workflow, such as 'Review dependency direction against Clean Architecture diagram' or 'Verify no circular dependencies before proceeding.'
| 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 provides abstract principles and pattern names but no concrete, executable code, commands, or specific examples. Guidance like 'Use interfaces for communication' and 'Inject dependencies, don't hardcode' describes rather than instructs with actionable specifics. | 1 / 3 |
Workflow Clarity | The workflow section lists 5 sequential steps which provides a clear sequence, but lacks validation checkpoints, feedback loops, or concrete verification steps. For architectural decisions that can have significant downstream impact, there's no explicit validation or review mechanism beyond 'document in ADR.' | 2 / 3 |
Progressive Disclosure | The skill references multiple external files (references/implementation.md, references/distributed-systems.md, references/resilience-patterns.md) with clear signaling, but no bundle files are provided, meaning these references are broken. The structure is appropriate but the referenced content doesn't exist to support the body. | 2 / 3 |
Total | 8 / 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 | |
- Repository
- HoangNguyen0403/agent-skills-standard
- Commit
556618c
- 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.