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

67%

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

50%Weight 40%Scale 1-3

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

The skill body is concise and well-organized but lacks actionable, executable guidance — the instructions stay at the level of generic process advice. The single referenced resource is also a dangling pointer to a missing file.

Suggestions

Replace the abstract Instructions with concrete, executable steps for OpenAPI generation (e.g., specific tool commands, a minimal spec skeleton, or validation invocations).

Add an explicit validation checkpoint in the workflow, such as running a spec validator against the generated output before declaring success.

Either create `resources/implementation-playbook.md` or remove the dangling reference so the signaled resource actually resolves.

Dimension	Reasoning	Score
Conciseness	The body is lean, well under 50 lines, and does not explain concepts Claude already knows (no preamble about what OpenAPI is); nearly every line carries load, so it earns the top conciseness anchor.	3 / 3
Actionability	The Instructions are abstract directives — "Apply relevant best practices and validate outcomes", "Provide actionable steps and verification" — with no concrete code, commands, or examples, matching the describes-rather-than-instructs anchor.	1 / 3
Workflow Clarity	A sequence is listed (clarify → apply → verify) and validation is mentioned, but the steps are generic rather than a task-specific OpenAPI workflow and lack explicit validation checkpoints, so it sits at the implicit-checkpoints level rather than the top.	2 / 3
Progressive Disclosure	Sections are organized and a one-level-deep reference is clearly signaled ("open `resources/implementation-playbook.md`"), but that referenced file does not exist in the bundle, so navigation is undermined rather than fully clean.	2 / 3
	Total	8 / 12 Passed

Description

85%Weight 40%Scale 1-3

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 states concrete capabilities, gives explicit "Use when" triggers, and occupies a clear niche. Its only weakness is trigger-term coverage, which omits common user phrasings like "Swagger" or "REST API docs".

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions and sources — "Generate and maintain OpenAPI 3.1 specifications from code, design-first specs, and validation patterns" — which matches the anchor for listing several specific actions rather than naming only a domain.	3 / 3
Completeness	Explicitly answers both what ("Generate and maintain OpenAPI 3.1 specifications...") and when ("Use when creating API documentation, generating SDKs, or ensuring API contract compliance"), matching the anchor that requires both with explicit triggers.	3 / 3
Trigger Term Quality	Includes relevant natural terms like "creating API documentation" and "generating SDKs", but misses common variations users would say such as "Swagger", "REST API docs", or ".yaml/.json spec files".	2 / 3
Distinctiveness Conflict Risk	The OpenAPI 3.1 specification niche has distinct triggers (API documentation, SDKs, contract compliance) and is unlikely to fire for unrelated skills, matching the clear-niche anchor.	3 / 3
	Total	11 / 12 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: e63f7dd

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