CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

hexagonal-architecture

Applies hexagonal (ports & adapters) architecture. Use when designing application structure, separating domain from infrastructure, creating testable boundaries, or when user mentions ports, adapters, hexagonal, or clean architecture.

Quality

81%

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

The canonical home for this skill is hexagonal-architecture in ericjohnolson/tessl-test

SKILL.md
Quality
Evals
Security

Quality

Content

75%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 body is a lean, well-structured conventions catalog: an unambiguous inside/outside decision rule, dependency-disqualification guidance, concrete naming conventions with real identifiers, terse anti-patterns, and a per-layer testing strategy. It stays actionable without padding; the residual gaps are the missing worked port/adapter example, the implicit rather than sequenced design order, and one redundant restatement in the testing section.

Suggestions

Add one small worked example of a port and its adapter (e.g., a MemberRepository port interface with a JPA adapter implementing it and mapping MemberDbo to the domain type) to ground the naming conventions and the ports rule in code.

State the design order explicitly — model the domain first, define ports, then implement adapters — instead of implying domain-first sequencing only inside the "Premature Database Design" anti-pattern.

Delete the closing sentence of the testing section ("Test the domain exhaustively with fast unit tests; test adapters against real infrastructure sparingly") since it repeats the three per-layer bullets.

DimensionReasoningScore

Conciseness

The body is a dense rulebook — a decision rule, a compact diagram, exact naming conventions, and six one-line anti-patterns — with no tutorial prose explaining known concepts. It falls short of anchor 5 only because the testing section's closing sentence ("Test the domain exhaustively with fast unit tests; test adapters against real infrastructure sparingly") restates the three per-layer bullets above it and could be trimmed.

4 / 5

Actionability

Concrete, executable guidance throughout: the decision rule ("Does it do I/O or run out-of-process?"), the dependency disqualification rule, exact naming conventions with real identifiers (MemberView, MemberDbo, request.asMember()), and a per-layer testing strategy. Below anchor 5 because no worked example of a port and its adapter is shown, leaving the central "Domain defines ports; adapters implement them" rule without a concrete illustration.

4 / 5

Workflow Clarity

There is no numbered multi-step sequence, but the core decision procedure is unambiguous and the skill involves no destructive or batch operations, so the validation cap does not apply. Below anchor 5 (and the simple-skill exception) because the design ordering — domain model first, then ports, then adapters — is only implied inside the "Premature Database Design" anti-pattern rather than presented as an explicit sequence.

4 / 5

Progressive Disclosure

A well-organized single-file skill with clear sections and no bundle files or external references; nothing is buried or nested. It misses anchor 5 because at roughly 82 lines it exceeds the under-50-line carve-out for reference-free skills, and the six-entry anti-pattern catalog is content that could reasonably live in a reference file; it is clearly above anchor 3 since the organization has no real gaps.

4 / 5

Total

16

/

20

Passed

Description

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

The description pairs a terse, clear "what" with an explicit and well-built "Use when" clause covering natural trigger terms (ports, adapters, hexagonal, clean architecture), so completeness and trigger quality are strong. The main weakness is that the capability statement itself is thin — a single "applies" action — leaving the enumerated design activities implied by the use-clause rather than stated as what the skill does.

Suggestions

Name concrete capabilities in the what-clause — e.g., "Structures code into domain, application, and adapter layers; defines domain-owned port interfaces; maps external types at the boundary" — so the skill's actions are explicit rather than implied by the use-clause.

Add one or two natural trigger variations users actually say, such as "onion architecture" or "keep business logic framework-independent", to round out keyword coverage.

DimensionReasoningScore

Specificity

The only explicit capability is the single action "Applies hexagonal (ports & adapters) architecture"; the concrete activities ("separating domain from infrastructure", "creating testable boundaries") live in the use-clause rather than as stated capabilities. This matches anchor 3 (domain named with 1-2 concrete actions, not comprehensive) — below 4 because no distinct list of capabilities is stated, above 2 because the domain is named precisely.

3 / 5

Completeness

It clearly answers "what" ("Applies hexagonal (ports & adapters) architecture") and explicitly answers "when" with a concrete "Use when..." clause listing trigger phrases, mirroring the anchor-5 example structure. Not 4, because the "when" is fully explicit rather than merely present with room for more specificity.

5 / 5

Trigger Term Quality

"ports", "adapters", "hexagonal", and "clean architecture" are terms users naturally say when they need this skill, giving good keyword coverage. It falls short of anchor 5's comprehensive coverage because sibling synonyms like "onion architecture" or "keep business logic framework-free" are missing.

4 / 5

Distinctiveness Conflict Risk

Hexagonal architecture is a clear niche with distinctive triggers (ports, adapters, hexagonal), so conflict risk is low. Minor overlap remains via "clean architecture" — a sibling concept that could belong to a separate skill — and the broad phrase "designing application structure", keeping it below anchor 5.

4 / 5

Total

16

/

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

saski/arnesto

Path

.agents/skills/hexagonal-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.