122-java-type-design
Use when you need to review, improve, or refactor Java code for type design quality — including establishing clear type hierarchies, applying consistent naming conventions, eliminating primitive obsession with domain-specific value objects, leveraging generic type parameters, creating type-safe wrappers, designing fluent interfaces, ensuring precision-appropriate numeric types (BigDecimal for financial calculations), and improving type contrast through interfaces and method signature alignment. Part of the skills-for-java project
77
71%
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 ./skills/122-java-type-design/SKILL.mdQuality
Discovery
85%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 strong skill description that clearly defines a specific niche (Java type design quality) with numerous concrete actions and an explicit 'Use when' trigger clause. Its main weakness is that some trigger terms lean toward technical jargon that users may not naturally use, and the description is quite long, which slightly reduces clarity. The description also uses second person 'you need to' in the trigger clause rather than third person voice.
Suggestions
Add more natural user-facing trigger terms alongside the technical ones, e.g., 'when the user asks about better type safety, cleaner Java types, or reducing use of raw primitives'
Switch from second person ('Use when you need to') to third person voice ('Reviews and refactors Java code for type design quality. Use when...')
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description lists multiple specific concrete actions: establishing type hierarchies, applying naming conventions, eliminating primitive obsession with value objects, leveraging generic type parameters, creating type-safe wrappers, designing fluent interfaces, ensuring precision-appropriate numeric types (BigDecimal for financial calculations), and improving type contrast through interfaces. | 3 / 3 |
Completeness | The description explicitly answers both 'what' (review, improve, or refactor Java code for type design quality with a detailed list of specific activities) and 'when' (opens with 'Use when you need to review, improve, or refactor Java code for type design quality'), providing clear trigger guidance. | 3 / 3 |
Trigger Term Quality | Contains relevant technical keywords like 'Java code', 'type design', 'refactor', 'primitive obsession', 'BigDecimal', 'fluent interfaces', 'value objects', and 'generic type parameters'. However, some of these are more jargon-heavy than what a typical user would naturally say — users might say 'improve my Java types' or 'better type safety' rather than 'type contrast through interfaces and method signature alignment'. | 2 / 3 |
Distinctiveness Conflict Risk | The description carves out a very specific niche — Java type design quality — with distinct triggers like 'primitive obsession', 'value objects', 'type-safe wrappers', 'BigDecimal for financial calculations', and 'fluent interfaces'. This is unlikely to conflict with general Java coding skills or other language-specific skills. | 3 / 3 |
Total | 11 / 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 has good structure and progressive disclosure, with a clear reference to detailed guidance and a reasonable compile/verify safety workflow. However, it lacks any concrete code examples in the body itself, making it feel like a table of contents rather than actionable guidance. The bullet list of covered topics is verbose without adding executable value.
Suggestions
Add at least 2-3 inline before/after code examples for the most common patterns (e.g., primitive obsession → value object, raw String → EmailAddress) so the skill is actionable without requiring the reference file.
Define a clearer multi-step workflow for the actual refactoring process: e.g., 1) identify primitive obsession candidates, 2) create value objects, 3) compile, 4) update usages, 5) verify — with validation at each step.
Trim the 'What is covered' bullet list to focus on the top 5-6 most important patterns, or convert it into a compact table linking each pattern to its reference section.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The 'What is covered' bullet list is somewhat verbose and reads like a feature catalog rather than actionable guidance. The introductory sentence about 'typography concepts to code structure' is vague filler. However, the constraints section is reasonably tight. | 2 / 3 |
Actionability | The constraints section provides concrete commands (./mvnw compile, mvn clean verify) which is good, but the skill body contains zero code examples — no good/bad patterns, no executable snippets. All actual guidance is deferred to the reference file, leaving the skill itself as mostly a table of contents. | 2 / 3 |
Workflow Clarity | There is a clear compile-before/verify-after workflow with an explicit blocking condition on compilation failure, which is good. However, the middle steps (the actual type design improvement process) are completely unspecified — there's no sequence for how to analyze, prioritize, or apply changes, and no validation checkpoint between individual refactoring steps. | 2 / 3 |
Progressive Disclosure | The skill provides a clear overview with a well-signaled single-level reference to the detailed guide (references/122-java-type-design.md). The 'When to use' section aids discovery. Content is appropriately split between overview and reference. | 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
- jabrena/cursor-rules-java
- Commit
9ec21dd
- 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.