spring-boot-openapi-documentation
Generate comprehensive REST API documentation using SpringDoc OpenAPI 3.0 and Swagger UI in Spring Boot 3.x applications. Use when setting up API documentation, configuring Swagger UI, adding OpenAPI annotations, implementing security documentation, or enhancing REST endpoints with examples and schemas.
Install with Tessl CLI
npx tessl i github:giuseppe-trisciuoglio/developer-kit --skill spring-boot-openapi-documentation80
Does it follow best practices?
If you maintain this skill, you can automatically optimize it using the tessl CLI to improve its score:
npx tessl skill review --optimize ./path/to/skillValidation for skill structure
Discovery
100%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 skill description that excels across all dimensions. It uses third person voice correctly, provides specific concrete actions, includes comprehensive trigger terms that users would naturally use, and has an explicit 'Use when...' clause. The technology-specific focus (Spring Boot 3.x, SpringDoc OpenAPI 3.0, Swagger UI) makes it highly distinctive.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'Generate comprehensive REST API documentation', 'setting up API documentation', 'configuring Swagger UI', 'adding OpenAPI annotations', 'implementing security documentation', 'enhancing REST endpoints with examples and schemas'. | 3 / 3 |
Completeness | Clearly answers both what ('Generate comprehensive REST API documentation using SpringDoc OpenAPI 3.0 and Swagger UI') AND when with explicit 'Use when...' clause covering multiple trigger scenarios. | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural terms users would say: 'REST API documentation', 'SpringDoc', 'OpenAPI', 'Swagger UI', 'Spring Boot', 'API documentation', 'annotations', 'security documentation', 'endpoints', 'schemas'. | 3 / 3 |
Distinctiveness Conflict Risk | Very specific niche targeting Spring Boot 3.x with SpringDoc OpenAPI 3.0 and Swagger UI - unlikely to conflict with generic documentation skills or other framework-specific skills due to explicit technology stack mentions. | 3 / 3 |
Total | 12 / 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 skill provides highly actionable, executable code examples for SpringDoc OpenAPI integration with excellent coverage of common use cases. However, it suffers from verbosity in introductory sections and lacks a clear step-by-step workflow with validation checkpoints. The document would benefit from trimming redundant content and adding explicit verification steps.
Suggestions
Remove or significantly condense the 'When to Use' section - Claude can infer appropriate use cases from the skill title and content
Add a 'Quick Start Workflow' section with numbered steps and explicit validation: '1. Add dependency → 2. Add config → 3. Start app → 4. Verify: visit http://localhost:8080/swagger-ui/index.html'
Move 'Best Practices' and 'Common Annotations Reference' to separate reference files to reduce main document length
Remove version comments like '// Use latest stable version' - Claude knows to use current versions
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is comprehensive but includes some unnecessary verbosity, such as the extensive 'When to Use' section listing 15 bullet points that Claude could infer, and the 'Best Practices' section with 10 items that largely restate what's already shown in examples. The version comments like '// Use latest stable version' add noise. | 2 / 3 |
Actionability | Excellent actionable content with fully executable, copy-paste ready code examples throughout. Maven/Gradle dependencies, configuration files, and complete controller implementations are all concrete and immediately usable. | 3 / 3 |
Workflow Clarity | While individual code examples are clear, there's no explicit workflow sequence for setting up SpringDoc from scratch. Missing validation checkpoints - no guidance on verifying the setup works (e.g., 'After adding dependencies, start the app and verify Swagger UI loads at...'). | 2 / 3 |
Progressive Disclosure | References to external files exist (references/troubleshooting.md, references/springdoc-official.md) which is good, but the main document is quite long (~400 lines) with content that could be split out. The 'Common Annotations Reference' and 'Best Practices' sections could be separate reference files. | 2 / 3 |
Total | 9 / 12 Passed |
Validation
68%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 / 16 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (624 lines); consider splitting into references/ and linking | Warning |
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
metadata_version | 'metadata' field is not a dictionary | Warning |
license_field | 'license' field is missing | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 11 / 16 Passed | |
- 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.