openapi-spec-generator
Openapi Spec Generator - Auto-activating skill for API Development. Triggers on: openapi spec generator, openapi spec generator Part of the API Development skill category.
36
Quality
3%
Does it follow best practices?
Impact
99%
1.04xAverage 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/openapi-spec-generator/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 severely underdeveloped, consisting mainly of the skill name repeated as trigger terms with no actual description of capabilities or usage guidance. It fails to explain what the skill does, when to use it, or provide natural trigger terms that users would actually say. The description appears to be auto-generated boilerplate rather than a thoughtful skill description.
Suggestions
Add specific actions the skill performs, e.g., 'Generates OpenAPI 3.0 specifications from API endpoints, creates YAML/JSON schema definitions, documents request/response models'
Include a 'Use when...' clause with natural trigger terms like 'swagger', 'API documentation', 'REST spec', 'endpoint schema', 'API definition file'
Remove the duplicate trigger term and expand to cover variations users might naturally say when needing this skill
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description only states 'Openapi Spec Generator' and 'API Development' without describing any concrete actions. There are no specific capabilities listed like 'generates OpenAPI specifications from code' or 'creates endpoint documentation'. | 1 / 3 |
Completeness | The description fails to answer 'what does this do' beyond the name itself, and there is no 'Use when...' clause or explicit guidance on when Claude should select this skill. Both what and when are very weak. | 1 / 3 |
Trigger Term Quality | The trigger terms are just 'openapi spec generator' repeated twice, which is redundant and misses natural variations users might say like 'swagger', 'API documentation', 'REST API spec', 'yaml spec', or 'API schema'. | 1 / 3 |
Distinctiveness Conflict Risk | While 'OpenAPI' is somewhat specific to a particular domain, the generic 'API Development' category and lack of specific triggers could cause overlap with other API-related skills. The mention of OpenAPI provides some distinctiveness. | 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 essentially a placeholder with no actionable content. It describes what an OpenAPI spec generator skill would do without providing any actual guidance, code examples, schema templates, or workflows for generating OpenAPI specifications. The content adds no value beyond what Claude already knows about OpenAPI.
Suggestions
Add concrete OpenAPI spec examples showing YAML/JSON structure for common patterns (paths, schemas, authentication)
Include a step-by-step workflow for generating specs: 1) Define endpoints, 2) Create schemas, 3) Add authentication, 4) Validate with a linter
Provide executable code or commands for validation (e.g., 'npx @redocly/cli lint openapi.yaml')
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 explains nothing specific about OpenAPI spec generation. Phrases like 'provides automated assistance' and 'follows industry best practices' are filler that Claude doesn't need. | 1 / 3 |
Actionability | No concrete code, commands, or executable guidance is provided. The skill describes what it does abstractly ('provides step-by-step guidance') but never actually provides any guidance, examples, or OpenAPI spec content. | 1 / 3 |
Workflow Clarity | No workflow, steps, or process is defined. The skill claims to provide 'step-by-step guidance' but contains zero actual steps for generating OpenAPI specs. | 1 / 3 |
Progressive Disclosure | No structure for discovery or navigation. The content is a flat list of vague claims with no references to detailed materials, examples, or related documentation. | 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.