swagger-doc-creator
Swagger Doc Creator - Auto-activating skill for API Development. Triggers on: swagger doc creator, swagger doc creator Part of the API Development skill category.
36
Quality
3%
Does it follow best practices?
Impact
97%
0.97xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./planned-skills/generated/15-api-development/swagger-doc-creator/SKILL.mdQuality
Discovery
7%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 description is essentially a placeholder that provides almost no useful information for skill selection. It lacks any concrete actions, meaningful trigger terms, or guidance on when to use it. The only distinguishing element is the word 'Swagger' in the title, but without describing what the skill actually does with Swagger/OpenAPI, Claude cannot make informed decisions about when to select it.
Suggestions
Add specific capabilities like 'Generates OpenAPI/Swagger specifications from code, creates endpoint documentation, defines request/response schemas, and produces interactive API documentation'.
Replace the duplicate trigger terms with natural user phrases: 'Use when the user mentions API documentation, OpenAPI spec, swagger.yaml, REST API docs, endpoint documentation, or needs to document their API'.
Add a clear 'Use when...' clause that distinguishes this from general API development skills, such as 'Use when creating or updating API documentation files, not for API implementation or testing'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description only names the skill ('Swagger Doc Creator') without describing any concrete actions. There are no specific capabilities listed 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 'when should Claude use it' guidance. The 'Triggers on' section just repeats the skill name rather than providing meaningful trigger 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 a specific technology that provides some distinctiveness, the lack of detail about what the skill actually does and the generic 'API Development' category could cause overlap with other API-related skills. | 2 / 3 |
Total | 5 / 12 Passed |
Implementation
0%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is an empty template with no actual content. It contains only meta-descriptions of what a Swagger documentation skill might do, without any concrete guidance, code examples, OpenAPI specifications, or actionable instructions. The skill provides zero value as it teaches Claude nothing about creating Swagger documentation.
Suggestions
Add concrete OpenAPI/Swagger specification examples showing proper YAML/JSON structure for endpoints, parameters, and responses
Include executable code snippets for generating Swagger docs (e.g., using swagger-jsdoc, FastAPI, or similar tools)
Provide a clear workflow: 1) Define endpoints, 2) Add annotations/decorators, 3) Generate spec, 4) Validate with swagger-cli
Remove all meta-descriptions ('This skill provides...', 'When to Use...') and replace with actual technical content
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is entirely filler with no actual technical information. It explains what the skill does in abstract terms without providing any concrete guidance, wasting tokens on meta-descriptions Claude doesn't need. | 1 / 3 |
Actionability | No executable code, no concrete commands, no actual Swagger/OpenAPI examples. The content only describes what it could do rather than providing any actionable instructions for creating Swagger documentation. | 1 / 3 |
Workflow Clarity | No workflow is defined. Claims to provide 'step-by-step guidance' but contains zero actual steps. There are no validation checkpoints or any process to follow. | 1 / 3 |
Progressive Disclosure | No structure beyond boilerplate headings. No references to detailed documentation, no examples, no links to related resources. The content is a template shell with no substance to organize. | 1 / 3 |
Total | 4 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
- Commit
0c08951
- 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.