CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

68

Quality

62%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./.github/skills/common/common-system-design/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

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.

DimensionReasoningScore

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')

DimensionReasoningScore

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.

Validation9 / 11 Passed

Validation for skill structure

CriteriaDescriptionResult

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
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.