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.

1.19x

Quality

71%

Does it follow best practices?

Impact

98%

1.19x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./tests/ext_conformance/artifacts/agents-wshobson/documentation-generation/skills/openapi-spec-generation/SKILL.md

Evaluation results

100%

26%

Hotel Reservation API Specification

Design-first OpenAPI 3.1 spec

Criteria

Without context

With context

OpenAPI 3.1.0 version

100%

Semantic version in info

100%

Multiple server environments

100%

operationId on all endpoints

100%

bearerAuth JWT security scheme

100%

Security on all endpoints

100%

Pagination fields completeness

12%

100%

Error schema structure

75%

100%

Correct HTTP status codes

42%

100%

$ref reuse

100%

camelCase schema properties

100%

Specific schema formats

100%

readOnly fields

100%

Explicit nullable

100%

Tags usage

100%

23%

API Spec Quality Gate Setup

OpenAPI validation tooling setup

Criteria

Without context

With context

Uses spectral-cli package

100%

Uses redocly/cli package

100%

Spectral operationId rule

100%

Spectral security rule

70%

100%

Spectral path param snake_case rule

100%

Spectral schema camelCase rule

100%

Redocly MIME type restriction

100%

spectral lint command in script

100%

redocly lint command in script

100%

Lint report documents issues

100%

95%

10%

Generate Client SDKs for a SaaS Platform API

SDK generation from spec

Criteria

Without context

With context

Uses openapi-generator-cli

100%

Install command present

100%

TypeScript generator name

100%

TypeScript supportsES6 flag

100%

TypeScript npmName property

100%

Python generator used

100%

Python packageName property

100%

Correct output directories

100%

Input spec referenced

100%

sdk-manifest.md documents generators

100%

Repository: Dicklesworthstone/pi_agent_rust
Commit: 47823e3

Evaluated: about 1 month ago
Agent: Claude Code
Model: Claude Sonnet 4.6

Table of Contents

Hotel Reservation API Specification API Spec Quality Gate Setup Generate Client SDKs for a SaaS Platform API

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.