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.

Install with Tessl CLI

npx tessl i github:wshobson/agents --skill openapi-spec-generation

What are skills?

Review — 75%

Does it follow best practices?

If you maintain this skill, you can automatically optimize it using the tessl CLI to improve its score:

npx tessl skill review --optimize ./path/to/skill

Learn more

Evaluation — 98%

Agent success when using this skill

Validation — 10 / 11 Passed

Validation for skill structure

SKILL.md

Review

Evals

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%

Without context: $0.4999 · 2m 20s · 13 turns · 14 in / 9,808 out tokens

With context: $0.6628 · 2m 20s · 22 turns · 268 in / 8,806 out tokens

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%

Without context: $0.8400 · 3m 30s · 30 turns · 30 in / 12,354 out tokens

With context: $1.4136 · 4m 39s · 45 turns · 445 in / 14,904 out tokens

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%

Without context: $0.6862 · 2m 24s · 29 turns · 28 in / 7,831 out tokens

With context: $1.0539 · 3m 4s · 32 turns · 79 in / 10,167 out tokens

Evaluated: 3 days ago
Agent: Claude Code

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.