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

76%

Does it follow best practices?

Impact

98%

1.19x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

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

The canonical home for this skill is openapi-spec-generation in wshobson/agents

Quality

Content

61%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.

Highly actionable templates and tooling commands, but the skill is a monolithic ~1020-line file with no progressive disclosure via reference files and no explicit generate-validate workflow with checkpoints.

Suggestions

Move the complete API spec template (Template 1) and the FastAPI/tsoa code templates into separate reference files under references/, leaving concise excerpts and "See references/..." pointers in SKILL.md to improve progressive disclosure and token efficiency.

Add an explicit end-to-end workflow section (e.g., 1. draft spec, 2. lint with Spectral/Redocly, 3. fix and re-lint, 4. generate SDK) with a validation checkpoint and retry loop rather than presenting linting only as a standalone template.

Trim the inline full-spec example to the minimal skeleton plus a link to the complete reference, reducing conciseness cost while keeping the body actionable.

Dimension	Reasoning	Score
Conciseness	Prose is mostly lean and free of basic-concept padding, but a ~460-line complete YAML spec plus two large code templates are inlined verbatim, which is more token volume than the overview warrants.	3 / 5
Actionability	Provides fully executable, copy-paste-ready material across YAML, Python/FastAPI, TypeScript/tsoa, Spectral/Redocly linting, and OpenAPI Generator commands covering the common cases.	5 / 5
Workflow Clarity	Content is organized as parallel templates and a design-approaches table rather than a sequenced generate-then-validate workflow, and validation appears as a standalone template rather than an explicit checkpoint with error-recovery feedback.	3 / 5
Progressive Disclosure	No bundle files exist and all content sits in a single monolithic SKILL.md; the full spec and code templates clearly belong in separate reference files, yet no references are signaled.	2 / 5
	Total	13 / 20 Passed

Description

92%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.

A strong, third-person description that clearly pairs a concrete capability statement with explicit 'Use when' trigger guidance. The only minor gap is keyword breadth (missing file extensions and common synonyms).

Dimension	Reasoning	Score
Specificity	"Generate and maintain OpenAPI 3.1 specifications from code, design-first specs, and validation patterns" lists multiple concrete actions with explicit input sources, matching the comprehensive-coverage anchor.	5 / 5
Completeness	It explicitly states the what ("Generate and maintain OpenAPI 3.1 specifications...") and the when ("Use when creating API documentation, generating SDKs, or ensuring API contract compliance") with concrete trigger phrases.	5 / 5
Trigger Term Quality	"creating API documentation, generating SDKs, or ensuring API contract compliance" covers several natural phrases users would say, but omits file extensions (.yaml/.json) and synonyms like 'Swagger', so it is not quite comprehensive.	4 / 5
Distinctiveness Conflict Risk	The OpenAPI 3.1 specification-generation niche is specific with distinct triggers, giving minimal overlap risk with unrelated skills.	5 / 5
	Total	19 / 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
skill_md_line_count	SKILL.md is long (1025 lines); consider splitting into references/ and linking	Warning

	Total	15 / 16 Passed

Repository: Dicklesworthstone/pi_agent_rust
Path: tests/ext_conformance/artifacts/agents-wshobson/documentation-generation/skills/openapi-spec-generation/SKILL.md
Commit: 6453c0b

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