swagger-doc-creator
Install with Tessl CLI
npx tessl i github:jeremylongshore/claude-code-plugins-plus-skills --skill swagger-doc-creatorSwagger Doc Creator - Auto-activating skill for API Development. Triggers on: swagger doc creator, swagger doc creator Part of the API Development skill category.
Overall
score
19%
Does it follow best practices?
Validation for skill structure
Activation
7%This description is essentially a placeholder with minimal useful content. It relies entirely on the skill name for context, provides no concrete capabilities, and the trigger terms are just the skill name duplicated. Claude would struggle to know when to select this skill over other API-related tools.
Suggestions
Add specific actions the skill performs, e.g., 'Generates OpenAPI/Swagger specifications, documents REST endpoints, creates request/response schemas, and validates API documentation.'
Include a 'Use when...' clause with natural trigger terms like 'API documentation', 'OpenAPI spec', 'document my endpoints', 'swagger.yaml', 'REST API docs'.
Remove the duplicate trigger term and expand with variations users would naturally say when needing API documentation help.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description only names the skill ('Swagger Doc Creator') and mentions 'API Development' but provides no concrete actions like 'generates OpenAPI specifications', 'documents endpoints', or 'creates schema definitions'. | 1 / 3 |
Completeness | The description fails to answer 'what does this do' beyond the name, and provides no explicit 'when to use' guidance. The 'Triggers on' section just repeats the skill name rather than describing usage scenarios. | 1 / 3 |
Trigger Term Quality | The trigger terms are just the skill name repeated twice ('swagger doc creator, swagger doc creator'). Missing natural user terms like 'API documentation', 'OpenAPI', 'REST API docs', 'endpoint documentation', or 'swagger.yaml'. | 1 / 3 |
Distinctiveness Conflict Risk | While 'Swagger' is somewhat specific to OpenAPI documentation, the vague 'API Development' category and lack of specific triggers could cause overlap with other API-related skills. The Swagger mention provides some distinctiveness. | 2 / 3 |
Total | 5 / 12 Passed |
Implementation
0%This skill content is essentially a placeholder template with no actual instructional value. It contains only meta-descriptions of what a skill should do without providing any concrete guidance on creating Swagger documentation. Claude gains nothing actionable from this content - no OpenAPI spec examples, no annotation patterns, no tooling commands.
Suggestions
Add concrete OpenAPI/Swagger specification examples showing actual YAML/JSON syntax for common API patterns (endpoints, parameters, responses, schemas)
Include executable code examples for generating Swagger docs using popular tools (e.g., swagger-jsdoc annotations, FastAPI automatic docs, springdoc-openapi)
Provide a clear workflow: 1) Define schemas, 2) Annotate endpoints, 3) Generate spec, 4) Validate with swagger-cli or similar tool
Remove all generic boilerplate ('provides automated assistance', 'follows best practices') and replace with specific, actionable content
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is padded with generic boilerplate that provides no actual value. Phrases like 'provides automated assistance' and 'follows industry best practices' are meaningless filler that Claude doesn't need. | 1 / 3 |
Actionability | There is zero concrete guidance - no code examples, no actual Swagger/OpenAPI syntax, no commands, no specific instructions. The entire content describes what the skill supposedly does without showing how to do anything. | 1 / 3 |
Workflow Clarity | No workflow is defined. There are no steps for creating Swagger documentation, no validation checkpoints, and no actual process to follow. 'Provides step-by-step guidance' is claimed but never delivered. | 1 / 3 |
Progressive Disclosure | The content is a monolithic block of vague descriptions with no structure for actual learning. No references to detailed documentation, examples, or related files. The sections present are organizational theater without substance. | 1 / 3 |
Total | 4 / 12 Passed |
Validation
69%Validation — 11 / 16 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
description_trigger_hint | Description may be missing an explicit 'when to use' trigger hint (e.g., 'Use when...') | Warning |
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
metadata_version | 'metadata' field is not a dictionary | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
body_steps | No step-by-step structure detected (no ordered list); consider adding a simple workflow | 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.