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?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./plugins/documentation-generation/skills/openapi-spec-generation/SKILL.md

Quality

Discovery

100%

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 strong skill description that clearly defines its scope around OpenAPI 3.1 specifications with concrete actions and explicit trigger guidance. It uses appropriate third-person voice, includes natural developer terminology, and has a well-defined niche that distinguishes it from general API or documentation skills.

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions: 'generate and maintain OpenAPI 3.1 specifications', 'creating API documentation', 'generating SDKs', 'ensuring API contract compliance'. Also mentions specific inputs: 'from code, design-first specs, and validation patterns'.	3 / 3
Completeness	Clearly answers both 'what' (generate and maintain OpenAPI 3.1 specs from code, design-first specs, and validation patterns) and 'when' (explicit 'Use when' clause covering API documentation, SDK generation, and API contract compliance).	3 / 3
Trigger Term Quality	Includes strong natural keywords users would say: 'OpenAPI', '3.1', 'API documentation', 'SDKs', 'API contract', 'specifications', 'design-first'. These are terms developers naturally use when working with API specs.	3 / 3
Distinctiveness Conflict Risk	Highly distinctive with a clear niche around OpenAPI 3.1 specifications specifically. The combination of 'OpenAPI', 'SDK generation', and 'API contract compliance' creates a well-defined scope unlikely to conflict with general documentation or coding skills.	3 / 3
	Total	12 / 12 Passed

Implementation

22%

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

This skill is primarily a large OpenAPI 3.1 YAML template with minimal instructional content around it. It lacks workflow guidance for the multiple use cases it claims to support (validation, SDK generation, design-first vs code-first approaches), and the massive inline template bloats the token budget without adding knowledge Claude doesn't already possess. The referenced bundle file for advanced patterns doesn't exist, further reducing its utility.

Suggestions

Replace the monolithic YAML template with a concise skeleton (20-30 lines) showing key patterns ($ref usage, security schemes, pagination), and move the full template to a referenced file.

Add explicit step-by-step workflows for the primary use cases: creating a spec from scratch, generating from existing code, and validating an implementation against a spec, each with validation checkpoints.

Create the referenced 'references/code-first-and-tooling.md' bundle file, or remove the reference if it won't exist.

Remove the 'Core Concepts' section (design approaches table, basic OpenAPI structure) as Claude already knows these; focus tokens on non-obvious patterns and project-specific conventions.

Dimension	Reasoning	Score
Conciseness	The skill is extremely verbose at ~400+ lines, with the vast majority being a monolithic YAML template that Claude could generate on its own. The 'When to Use This Skill' and 'Core Concepts' sections explain things Claude already knows (design-first vs code-first, basic OpenAPI structure). The complete User Management API template is a reference document, not efficient instruction.	1 / 3
Actionability	The complete YAML template is concrete and copy-paste ready, which is good. However, the skill lacks executable commands for validation, generation, or any workflow steps. References to code-first generation and tooling are deferred to a bundle file that doesn't exist, reducing actionability for those use cases.	2 / 3
Workflow Clarity	There is no clear workflow or sequenced steps for any of the stated use cases (creating specs, validating implementations, generating SDKs). The skill is essentially a template dump with best practices listed as bullet points, with no validation checkpoints or feedback loops for spec creation/maintenance.	1 / 3
Progressive Disclosure	The skill references 'references/code-first-and-tooling.md' for advanced patterns, which is a good structural choice. However, no bundle files are provided, so this reference is broken. The main file itself is a monolithic wall of YAML that should have been the referenced file, with the SKILL.md providing a concise overview and workflow.	2 / 3
	Total	6 / 12 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
skill_md_line_count	SKILL.md is long (537 lines); consider splitting into references/ and linking	Warning

	Total	10 / 11 Passed

Repository: wshobson/agents
Commit: 112197c

Reviewed: about 11 hours 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.