tessl-labs/springboot-project-structure
Spring Boot project structure — package-by-feature, record DTOs, Flyway migrations, multi-profile config, actuator, proper test structure
84
76%
Does it follow best practices?
Impact
97%
4.04xAverage score across 5 eval scenarios
Passed
No known issues
Quality
Discovery
77%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 well-crafted description with excellent specificity listing concrete patterns and practices. It includes an explicit 'Use when' clause which is good for completeness. However, the trigger terms could be expanded to include more natural user language variations, and the scope 'any Spring Boot service' may be too broad, risking conflicts with more specialized Spring skills.
Suggestions
Add natural trigger term variations like 'Java backend', 'Spring application', 'microservice structure', 'project setup' to improve discoverability
Consider narrowing the 'Use when' clause to be more specific, such as 'Use when setting up a new Spring Boot project, organizing package structure, or establishing project conventions' to reduce potential conflicts with other Spring-focused skills
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions and patterns: package-by-feature layout, configuration classes in dedicated config package, multi-profile application.yml, record DTOs, MapStruct mapping, Flyway migrations, logback-spring.xml, actuator endpoints, and test directory mirroring. | 3 / 3 |
Completeness | Clearly answers both what (Spring Boot project structure best practices with specific patterns listed) and when ('Use when building any Spring Boot service') with an explicit trigger clause. | 3 / 3 |
Trigger Term Quality | Includes 'Spring Boot' which is a strong natural keyword, but lacks common variations users might say like 'Java backend', 'REST API', 'microservice', 'Spring application', or file extensions like '.java'. The technical terms (MapStruct, Flyway, logback) are specific but not what users typically request. | 2 / 3 |
Distinctiveness Conflict Risk | While Spring Boot is specific, 'building any Spring Boot service' is quite broad and could overlap with other Spring-related skills (e.g., Spring Security, Spring testing, Spring REST APIs). The trigger is somewhat generic within the Spring ecosystem. | 2 / 3 |
Total | 10 / 12 Passed |
Implementation
64%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a solid, production-ready Spring Boot project structure guide with excellent actionability—every section includes complete, executable code examples. The main weaknesses are verbosity (explanations of concepts Claude knows) and the monolithic structure that could benefit from progressive disclosure to separate reference material. Adding validation workflows for verifying project structure correctness would strengthen the skill.
Suggestions
Remove explanatory sections like 'Why package-by-feature, not package-by-layer' and 'Records are immutable, concise...' that explain concepts Claude already understands
Add a validation workflow section showing how to verify the project structure is correct (e.g., using the referenced verifiers, IDE inspections, or build checks)
Consider splitting detailed reference content (full MapStruct setup, complete logback-spring.xml examples, Flyway naming conventions) into linked reference files to reduce the main skill's token footprint
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is comprehensive but includes some explanatory content Claude already knows (e.g., explaining why package-by-feature is better, what records generate automatically). The 'Why package-by-feature' section and some Lombok explanations could be trimmed. | 2 / 3 |
Actionability | Excellent actionability with complete, executable code examples throughout—full directory structures, working Java code, complete YAML configurations, SQL migrations, and XML logging config. All examples are copy-paste ready. | 3 / 3 |
Workflow Clarity | The skill provides a comprehensive checklist at the end but lacks explicit validation steps or feedback loops. For a project structure skill, there's no guidance on verifying the structure is correct or how to catch misconfigurations early. | 2 / 3 |
Progressive Disclosure | Content is well-organized with clear sections and headers, but it's a monolithic document (~400 lines) that could benefit from splitting detailed examples (MapStruct config, Flyway migrations, logging) into separate reference files. The verifiers section at the end suggests external files exist but aren't leveraged for content organization. | 2 / 3 |
Total | 9 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
Reviewed
Table of Contents