openapi-spec-generation

Generate and maintain OpenAPI 3.1 specifications from code, design-first specs, and validation patterns. Use when creating API documentation, generating SDKs, or ensuring API contract compliance.

Quality

51%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./plugins/AI-Agents-Safe-Coding-Skills/skills/openapi-spec-generation/SKILL.md

The canonical home for this skill is openapi-spec-generation in rmyndharis/antigravity-skills

Quality

Content

18%Scale 1-5

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 that defers all meaningful content to a resource file that doesn't exist in the bundle. The body contains no concrete guidance, no executable examples, no workflow steps, and no OpenAPI-specific patterns. It reads as a generic template rather than a skill that would help Claude generate or validate OpenAPI specifications.

Suggestions

Add concrete, executable examples showing how to structure an OpenAPI 3.1 spec (e.g., a minimal spec with paths, schemas, and responses in YAML/JSON).

Define a clear workflow with validation steps, e.g.: 1. Identify endpoints → 2. Define schemas → 3. Write paths → 4. Validate with a linter command → 5. Fix errors and re-validate.

Replace the generic instruction bullets ('Clarify goals', 'Apply best practices') with OpenAPI-specific actionable guidance such as naming conventions, $ref usage patterns, and common pitfalls.

Either provide the referenced `resources/implementation-playbook.md` bundle file or inline the essential patterns directly in the SKILL.md.

Dimension	Reasoning	Score
Conciseness	The 'Use this skill when' and 'Do not use this skill when' sections add moderate padding without providing actionable value. The instructions section is generic and could apply to almost any skill. However, it's not excessively verbose overall.	3 / 5
Actionability	The content provides no concrete code, commands, examples, or specific guidance for generating OpenAPI specs. Instructions like 'Clarify goals, constraints, and required inputs' and 'Apply relevant best practices' are entirely vague and non-actionable. Everything is deferred to a resource file that doesn't exist in the bundle.	1 / 5
Workflow Clarity	There is no defined workflow, no sequenced steps, and no validation checkpoints. The four bullet points in Instructions are generic platitudes rather than a meaningful process. For a skill involving spec generation and validation, this is critically insufficient.	1 / 5
Progressive Disclosure	The skill references `resources/implementation-playbook.md` for detailed patterns, which is a reasonable disclosure strategy. However, no bundle files are provided, meaning the reference leads nowhere. The SKILL.md itself contains almost no substantive content to serve as an overview, making the disclosure structure hollow.	2 / 5
	Total	7 / 20 Passed

Description

83%Scale 1-5

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-structured skill description that clearly communicates both what the skill does and when to use it. The explicit 'Use when...' clause with concrete trigger scenarios is a strong point. The main weakness is missing some common synonyms (especially 'Swagger') and file format references that users might naturally mention.

Suggestions

Add 'Swagger' as a synonym since many users still use that term interchangeably with OpenAPI, and include file extensions like '.yaml' or '.json'.

Consider adding more specific actions like 'validate schemas', 'generate YAML/JSON specs', or 'document REST endpoints' to improve specificity.

Dimension	Reasoning	Score
Specificity	Lists several specific actions: 'generate and maintain OpenAPI 3.1 specifications from code', 'design-first specs', and 'validation patterns'. It covers multiple concrete activities but could be more comprehensive (e.g., mentioning specific outputs like YAML/JSON files, endpoint documentation, schema generation).	4 / 5
Completeness	Clearly answers both 'what' (generate and maintain OpenAPI 3.1 specifications from code, design-first specs, and validation patterns) and 'when' (Use when creating API documentation, generating SDKs, or ensuring API contract compliance) with explicit trigger phrases.	5 / 5
Trigger Term Quality	Includes good natural keywords like 'OpenAPI', 'API documentation', 'SDKs', 'API contract', and 'specifications'. Missing some common synonyms and variations like 'Swagger', 'REST API', '.yaml', '.json', 'API spec', or 'schema' that users might naturally use.	4 / 5
Distinctiveness Conflict Risk	Fairly distinct with the specific mention of 'OpenAPI 3.1' and related activities. Minor overlap risk with general API documentation skills or SDK generation tools, but the OpenAPI focus narrows it well. Mentioning 'Swagger' as a synonym could help further distinguish it.	4 / 5
	Total	17 / 20 Passed

Validation

90%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 10 / 11 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	10 / 11 Passed

Repository: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: plugins/AI-Agents-Safe-Coding-Skills/skills/openapi-spec-generation/SKILL.md
Commit: 57c135b

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

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.