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

61%

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

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

Quality

Content

36%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 concise but largely hollow: it offers generic process directives instead of executable OpenAPI patterns and leans on a reference file that is not actually bundled. Concrete examples or a real playbook file are needed.

Suggestions

Replace the generic Instructions with concrete, executable guidance for OpenAPI 3.1 generation, such as a minimal spec skeleton, key tooling commands, or structural validation steps.

Either add the missing 'resources/implementation-playbook.md' bundle file or remove the dangling reference so navigation is not broken.

Add an explicit validate-then-verify checkpoint in the workflow (e.g. linting the spec with a validator and confirming it loads) before declaring a spec complete.

Dimension	Reasoning	Score
Conciseness	The body is lean, but the Instructions section relies on generic boilerplate ('Clarify goals...', 'Apply relevant best practices...') that does not earn its tokens since it tells Claude nothing it does not already know.	3 / 5
Actionability	Provides only high-level hints with no concrete code, commands, or specific steps; the sole concrete pointer ('open resources/implementation-playbook.md') targets a file that does not exist in the bundle.	2 / 5
Workflow Clarity	The implied sequence (clarify, apply, provide steps) is poorly defined as a real workflow, and validation checkpoints are entirely absent despite the skill covering spec validation.	2 / 5
Progressive Disclosure	Sections are organized, but the only external reference points to a non-existent 'resources/implementation-playbook.md' (no references/ scripts/ or assets/ bundle dirs exist), undermining navigation.	3 / 5
	Total	10 / 20 Passed

Description

87%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 states concrete capabilities and gives explicit, natural trigger conditions with minimal conflict risk. The only weakness is keyword coverage that omits a few common synonyms like 'swagger'.

Dimension	Reasoning	Score
Specificity	Names the domain ('OpenAPI 3.1 specifications') and several concrete actions ('Generate and maintain' from 'code, design-first specs, and validation patterns'), with only minor coverage gaps versus a fully comprehensive action list.	4 / 5
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') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Includes natural terms users would say ('API documentation', 'SDKs', 'API contract compliance') but omits common synonyms such as 'swagger' or '.yaml/.json spec files'.	4 / 5
Distinctiveness Conflict Risk	Targets a clear niche (OpenAPI 3.1 spec generation) with distinct triggers, making conflict with unrelated skills unlikely.	5 / 5
	Total	18 / 20 Passed

Validation

93%

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

Validation for skill structure

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

	Total	15 / 16 Passed

Repository: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: plugins/AI-Agents-Safe-Coding-Skills-claude/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.