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

56%

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 ./skills/openapi-spec-generation/SKILL.md

Quality

Content

28%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is well-structured and lean, but it lacks any concrete, executable OpenAPI guidance and relies on generic platitudes. Its single external reference points to a missing file, undermining both actionability and navigation.

Suggestions

Replace the generic Instructions platitudes with at least one concrete, copy-pasteable OpenAPI snippet (e.g., a minimal valid 3.1 spec skeleton or a validation command).

Create the referenced 'resources/implementation-playbook.md' or remove the dangling reference so progressive disclosure resolves to real content.

Add an explicit validation checkpoint in the workflow (e.g., 'validate the spec with a linter before saving') rather than the vague 'validate outcomes' step.

Dimension	Reasoning	Score
Conciseness	The body is short and avoids explaining OpenAPI basics, but the Instructions bullets ('Apply relevant best practices and validate outcomes', 'Provide actionable steps and verification') are generic platitudes not specific to OpenAPI, so not every token earns its place.	3 / 5
Actionability	No concrete code, commands, or executable examples appear; guidance is abstract ('Apply relevant best practices', 'Provide actionable steps and verification') and the only concrete pointer ('open resources/implementation-playbook.md') targets a file that does not exist.	1 / 5
Workflow Clarity	A rough generic sequence exists ('Clarify goals...', 'Apply best practices and validate outcomes', 'Provide actionable steps and verification') but steps are poorly defined for actual spec generation and validation checkpoints are absent rather than explicit.	2 / 5
Progressive Disclosure	Section structure is clean (Use when / Do not use when / Instructions / Resources) with a clearly signaled one-level reference, but the referenced 'resources/implementation-playbook.md' does not exist in the bundle, so navigation fails to resolve.	3 / 5
	Total	9 / 20 Passed

Description

83%Weight 40%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.

The description is strong: it pairs a concrete capability statement with an explicit 'Use when' trigger clause covering multiple natural scenarios. It is specific, well-triggered, and clearly distinct, with only minor gaps in keyword synonyms and a slightly broad trigger phrase.

Dimension	Reasoning	Score
Specificity	Quotes several concrete actions ('Generate and maintain OpenAPI 3.1 specifications', 'generating SDKs', 'ensuring API contract compliance') across distinct inputs and outputs, but 'maintain' and 'ensure compliance' are slightly abstract, leaving minor coverage gaps versus the comprehensive anchor 5.	4 / 5
Completeness	Explicitly 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 concrete trigger phrases, matching the anchor 5 example structure.	5 / 5
Trigger Term Quality	Includes natural terms users would say ('API documentation', 'generating SDKs', 'API contract compliance', 'OpenAPI') with good coverage, but omits common synonyms/extensions like 'Swagger' or '.yaml/.json spec files' that would reach the comprehensive anchor 5.	4 / 5
Distinctiveness Conflict Risk	The OpenAPI 3.1 spec-generation niche is fairly distinct with specific triggers, but the broad phrase 'creating API documentation' creates minor overlap risk with general documentation skills, keeping it just below the minimal-conflict anchor 5.	4 / 5
	Total	17 / 20 Passed

Validation

100%

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: rmyndharis/antigravity-skills
Path: skills/openapi-spec-generation/SKILL.md
Commit: 3eff4af

Reviewed: 23 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.