CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

clean-architecture

Structure software around the Dependency Rule: source code dependencies point inward from frameworks to use cases to entities. Use when the user mentions "architecture layers", "dependency rule", "ports and adapters", "hexagonal architecture", "use case boundary", "onion architecture", "screaming architecture", or "framework independence". Also trigger when decoupling business logic from databases or frameworks, defining module boundaries, or debating where to put business rules. Covers component principles, boundaries, and SOLID. For code quality, see clean-code. For domain modeling, see domain-driven-design.

Quality

75%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/clean-architecture/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

53%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The content is well-structured as a reference — real one-level-deep bundle files, dense application tables, diagnostic checklists, and concrete pattern examples. Its main weaknesses are token efficiency (it re-teaches SOLID and clean-architecture fundamentals Claude already knows and includes padding like an author biography) and the absence of an explicitly sequenced workflow connecting the diagnostic, scoring, and remediation steps.

Suggestions

Cut the 'About the Author' and 'Further Reading' sections and compress the 'Why it works' paragraphs and SOLID/component-principle definitions, trusting Claude's existing knowledge of these fundamentals; keep only the non-obvious judgments and the application/mistake/diagnostic tables.

Add an explicit workflow section that sequences the existing pieces: run the Quick Diagnostic checklist → apply the Scoring rubric (0-10) → report score with specific improvements to reach 10/10.

Lean down the inline 'Key insights' bullets per section (they largely duplicate the reference files) so SKILL.md functions as a true overview pointing to references/*.md.

DimensionReasoningScore

Conciseness

The body re-explains concepts Claude already knows at length: full SOLID definitions ("LSP: subtypes must be usable through the base type interface"), component principles (REP/CCP/CRP/ADP), repository pattern basics, and "Why it works" rationale paragraphs for each section. It also carries clearly padded sections unrelated to skill execution — an "About the Author" biography of Robert C. Martin and a book-marketing "Further Reading" section — matching anchor 2 (noticeably verbose; several unnecessary explanations or padded sections) rather than 3, since well over a third of the ~200-line body re-teaches known material.

2 / 5

Actionability

For an instruction-only skill, the guidance is concrete: named interface patterns ("`UserRepository` interface in Use Cases; `PostgresUserRepository` in Adapters"), specific request models ("`CreateOrderRequest { items, customerId }`"), a stability formula ("I = Ce / (Ca + Ce)"), and a Common Mistakes table with concrete fixes. It falls short of 5 because examples are one-line illustrative fragments rather than complete, copy-ready code or commands with minor gaps covered.

4 / 5

Workflow Clarity

The pieces of a procedure exist — a Quick Diagnostic checklist ("If No → Action") and a Scoring protocol ("rate it 0-10... Always provide the current score and specific improvements needed to reach 10/10") — but no explicit sequence ties them together; the reader must infer diagnose → score → recommend. This matches anchor 3 (sequence present but checkpoints implicit/not assembled into a stated workflow); the diagnostic checklist keeps it above 2.

3 / 5

Progressive Disclosure

Structure is good: six reference files exist, each is linked one level deep from its section ("See: [references/dependency-rule.md]") and indexed in a Reference Files section with descriptions, and no reference points to further files. It falls short of 5 because the SKILL.md body itself runs ~200 lines with substantial conceptual content (key insights, why-it-works, definitions) that substantially duplicates the reference files, so the split between overview and detail is not as clean as the anchor-5 quick-start pattern.

4 / 5

Total

13

/

20

Passed

Description

86%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A well-constructed description: explicit what/when structure, rich synonym-level trigger coverage, and thoughtful cross-skill disambiguation. Its only weakness is that capability description leans on one core action plus a topic list rather than enumerating several concrete actions.

DimensionReasoningScore

Specificity

The description gives one concrete action — "Structure software around the Dependency Rule: source code dependencies point inward from frameworks to use cases to entities" — plus a topic scope statement ("Covers component principles, boundaries, and SOLID"), but topic names are not concrete actions. It clearly matches anchor 3 (domain plus 1-2 concrete actions, not comprehensive) rather than 4, which requires several distinct actions like the PDF example's "extracts text, fills forms, converts pages".

3 / 5

Completeness

It explicitly answers both questions: the "what" is stated first ("Structure software around the Dependency Rule..."), and the "when" uses a literal "Use when the user mentions [phrase list]" clause with concrete trigger phrases plus additional "Also trigger when..." conditions. This is the anchor-5 example pattern verbatim; score 4 would require the "when" to be less explicit, which it is not.

5 / 5

Trigger Term Quality

Trigger coverage is comprehensive with abundant synonyms users actually say: "architecture layers", "dependency rule", "ports and adapters", "hexagonal architecture", "use case boundary", "onion architecture", "screaming architecture", "framework independence", plus behavioral triggers like "decoupling business logic from databases" and "debating where to put business rules". This matches the anchor-5 pattern of comprehensive natural terms including synonyms (no file extensions are relevant for a conceptual skill).

5 / 5

Distinctiveness Conflict Risk

The niche is clear (clean architecture with distinctive triggers like "hexagonal/onion/screaming architecture") and it proactively routes near-conflicts ("For code quality, see clean-code. For domain modeling, see domain-driven-design"). However, claiming "Covers... SOLID" and "boundaries" leaves minor overlap with a code-quality skill like clean-code, which is only partially disambiguated, placing it between anchors 4 and 5 rather than clearly at 5.

4 / 5

Total

17

/

20

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

valeriibeck-star/claude-skills

Path

skills/clean-architecture/SKILL.md

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.