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

Discovery

85%

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 well-structured skill description that clearly articulates specific capabilities and includes explicit 'Use when' guidance. The main weakness is trigger term coverage - it uses technical terminology but misses common synonyms like 'swagger' that users frequently use interchangeably with OpenAPI.

Suggestions

Add common synonyms and variations to trigger terms: 'swagger', 'REST API spec', 'API schema', '.yaml/.json spec files'

Consider adding user intent phrases like 'document my API', 'generate API client', or 'validate API spec'

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions: 'Generate and maintain OpenAPI 3.1 specifications from code, design-first specs, and validation patterns' covers generation, maintenance, and multiple source types.	3 / 3
Completeness	Clearly 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 explicit trigger guidance.	3 / 3
Trigger Term Quality	Includes relevant terms like 'OpenAPI', 'API documentation', 'SDKs', 'API contract', but misses common variations users might say like 'swagger', 'REST API spec', 'API schema', or file extensions like '.yaml', '.json'.	2 / 3
Distinctiveness Conflict Risk	Clear niche focused specifically on OpenAPI 3.1 specifications with distinct triggers around API documentation, SDKs, and contract compliance - unlikely to conflict with general coding or documentation skills.	3 / 3
	Total	11 / 12 Passed

Implementation

64%

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

This skill provides highly actionable, executable templates and code examples for OpenAPI spec generation across multiple frameworks. However, it suffers from being overly long with massive inline templates that should be externalized, lacks clear workflow sequences with validation checkpoints, and includes some unnecessary explanatory content that Claude doesn't need.

Suggestions

Move the large template examples (Complete API Specification, FastAPI, tsoa) to separate referenced files like TEMPLATES.md or examples/ directory, keeping only a minimal quick-start example inline

Add an explicit workflow section with numbered steps and validation checkpoints, e.g., '1. Write spec 2. Validate with spectral 3. Fix errors 4. Generate SDK 5. Verify generated code'

Remove the 'When to Use This Skill' and 'Core Concepts' sections - Claude understands when to use OpenAPI specs and the design approaches without explanation

Dimension	Reasoning	Score
Conciseness	The skill is comprehensive but includes some unnecessary verbosity like the 'When to Use This Skill' section and the 'Core Concepts' table explaining design approaches that Claude already understands. The massive template examples could be trimmed or referenced externally.	2 / 3
Actionability	Provides fully executable, copy-paste ready code examples across multiple languages (Python/FastAPI, TypeScript/tsoa), complete YAML templates, and specific CLI commands for validation and SDK generation. All examples are concrete and runnable.	3 / 3
Workflow Clarity	While the skill covers multiple approaches (design-first, code-first, validation), it lacks explicit step-by-step workflows with validation checkpoints. The validation section shows commands but doesn't integrate them into a clear 'create -> validate -> fix -> regenerate' feedback loop.	2 / 3
Progressive Disclosure	The content is a monolithic wall of text with all templates inline rather than referenced. The 400+ line complete API specification template should be in a separate file. External resources are listed but internal content organization could benefit from splitting templates into separate referenced files.	2 / 3
	Total	9 / 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 (1025 lines); consider splitting into references/ and linking	Warning

	Total	10 / 11 Passed

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.