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
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 repeats the skill name without providing any meaningful information about what the skill does or when it should be used. It lacks concrete actions, natural trigger terms, and explicit usage guidance, making it nearly useless for skill selection among multiple options.
Suggestions
Add specific concrete actions the skill performs, e.g., 'Generates OpenAPI/Swagger specification files, documents REST API endpoints, creates request/response schemas, and produces interactive API documentation.'
Add a 'Use when...' clause with natural trigger terms: 'Use when the user asks about Swagger, OpenAPI specs, API documentation, REST API docs, endpoint documentation, or .yaml/.json API definitions.'
Remove the redundant duplicate trigger term ('swagger doc creator' listed twice) and expand with varied natural language terms users would actually say.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names a domain ('API Development') and a tool name ('Swagger Doc Creator') but does not describe any concrete actions. There are no specific capabilities listed like 'generates OpenAPI specs', 'documents endpoints', or 'creates YAML/JSON swagger files'. | 1 / 3 |
Completeness | The description fails to answer 'what does this do' beyond the name itself, and the 'when' clause is just a redundant repetition of the skill name rather than meaningful trigger guidance. Both what and when are very weak. | 1 / 3 |
Trigger Term Quality | The only trigger terms listed are 'swagger doc creator' repeated twice. It misses natural user terms like 'OpenAPI', 'API documentation', 'swagger spec', 'REST API docs', '.yaml', 'endpoint documentation', etc. | 1 / 3 |
Distinctiveness Conflict Risk | The mention of 'Swagger' provides some specificity that distinguishes it from generic API or documentation skills, but the lack of concrete actions and the broad '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 instructional content. It repeatedly references 'swagger doc creator' without ever explaining what to do, how to create a Swagger/OpenAPI document, or providing any code, schemas, or examples. It fails on every dimension of the rubric.
Suggestions
Replace the abstract descriptions with concrete, executable content: include an example OpenAPI 3.0 YAML spec skeleton that Claude can use as a starting template.
Add a clear workflow: e.g., 1) Identify endpoints, 2) Define schemas, 3) Write the OpenAPI spec, 4) Validate with a tool like `swagger-cli validate spec.yaml`, 5) Fix errors and re-validate.
Remove all meta-description sections ('When to Use', 'Example Triggers', 'Capabilities') that describe the skill rather than teaching the task—these waste tokens and provide no actionable guidance.
Include at least one complete, copy-paste-ready OpenAPI spec example with request/response schemas, and reference external files for advanced topics like authentication schemes or pagination patterns.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is entirely filler and meta-description. It explains what the skill does in abstract terms without providing any actual technical content. Every section restates the same vague idea ('swagger doc creator') without adding substance. | 1 / 3 |
Actionability | There is zero concrete guidance—no code, no commands, no OpenAPI spec examples, no schemas, no tool usage. The skill describes rather than instructs, offering only vague promises like 'provides step-by-step guidance' without actually providing any. | 1 / 3 |
Workflow Clarity | No workflow, steps, or process is defined. The skill claims to provide 'step-by-step guidance' but contains no steps whatsoever. There are no validation checkpoints or sequenced instructions. | 1 / 3 |
Progressive Disclosure | The content is a flat, repetitive wall of meta-text with no meaningful structure. There are no references to detailed files, no quick-start section, and no navigation to deeper content. The sections are superficial headings over vacuous content. | 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
4dee593
- 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.