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

70%

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

57%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 but structurally heavy: the body delivers complete, executable templates and commands, yet duplicates the same API across three languages inline with no bundle files and no sequenced workflow tying generation, validation, and SDK generation together. It reads as a reference dump rather than a guided skill.

Suggestions

Move the full templates (YAML spec, FastAPI, tsoa) into references/ files and keep only a skeletal example plus one-level-deep pointers in SKILL.md, eliminating the triple-duplication of the same User API.

Add an explicit ordered workflow (e.g., choose approach → draft/annotate → `spectral lint` → fix and re-lint → `redocly bundle` → generate SDK) with validation checkpoints and a fix-and-retry feedback loop.

Trim the boilerplate Spectral/Redocly configuration to the custom rules that add value, since stock 'extends: recommended' rulesets are knowledge Claude already has.

Dimension	Reasoning	Score
Conciseness	The ~1000-line body inlines three near-complete parallel implementations of the same User API (a 460-line YAML spec, a full FastAPI app, and a full tsoa controller), plus standard Spectral/Redocly config Claude can derive itself — heavy padding and duplication. Not 1 because there is little prose over-explanation of known concepts; it is dense reference material rather than tutorial filler.	2 / 5
Actionability	Everything is copy-paste executable: complete OpenAPI 3.1 YAML, working FastAPI and tsoa code with an export snippet, heredoc-generated lint configs, and exact `spectral lint` / `redocly bundle` / `openapi-generator-cli generate` commands covering the common cases. Matches the fully-executable anchor exactly; no pseudocode gaps.	5 / 5
Workflow Clarity	The skill presents approaches, templates, and tools (design-first/code-first table, linting section) but never sequences them — there is no generate → lint → fix → bundle → generate-SDK flow with validation checkpoints or feedback loops. Validation tooling exists (Spectral/Redocly) yet is disconnected from any ordered process, matching the anchor-3 'sequence present but checkpoints implicit' case rather than 4's clear sequence with most checkpoints.	3 / 5
Progressive Disclosure	No bundle files exist (references/, scripts/, assets/ are absent), and the full multi-language templates and lint configs that clearly belong in separate reference files are inlined in SKILL.md. Section headers do provide navigable structure (## Templates, ## SDK Generation, ## Best Practices), so it sits at anchor 3 ('structure present but content that should be separate is inline') rather than 2's minimal structure.	3 / 5
	Total	13 / 20 Passed

Description

83%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 description: third-person, concise, explicitly answering both what the skill does and when to use it with concrete trigger phrases. The 'when' clause lists three natural usage scenarios, though synonym coverage (e.g., 'Swagger', 'spec') could be broader.

Dimension	Reasoning	Score
Specificity	Concrete third-person actions are stated ('Generate and maintain OpenAPI 3.1 specifications from code, design-first specs, and validation patterns') with named input sources, but coverage has minor gaps — 'validation patterns' is generic and no concrete output artifacts beyond the spec itself are named. Fits anchor 4 (several specific actions, minor gaps) rather than 5, which requires comprehensive concrete action coverage.	4 / 5
Completeness	Both questions are explicitly answered: what ('Generate and maintain OpenAPI 3.1 specifications from code, design-first specs, and validation patterns') and when (an explicit 'Use when...' clause with three concrete triggers). Not 4 because the when-clause is explicit and lists concrete trigger phrases, matching the anchor-5 example structure.	5 / 5
Trigger Term Quality	Natural user phrases appear ('creating API documentation', 'generating SDKs', 'ensuring API contract compliance') alongside the strong keyword 'OpenAPI 3.1'. Common synonyms a user might actually say — 'Swagger', 'REST API spec', 'OpenAPI spec' — are only partially implied, keeping it below anchor 5's comprehensive synonym/extension coverage.	4 / 5
Distinctiveness Conflict Risk	The 'OpenAPI 3.1 specifications' niche is clearly defined with distinct triggers (SDK generation, contract compliance), but 'creating API documentation' is broad enough to overlap with general documentation skills. Mostly distinct with minor overlap risk — anchor 4, not 5's 'minimal conflict risk'.	4 / 5
	Total	17 / 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: a65ce00

Reviewed: 6 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.