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

—

Does it follow best practices?

Impact

98%

1.19x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Quality

Content

50%

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

The body is highly actionable with complete executable templates and tooling commands, but it is a token-heavy monolith that inlines reference-grade material rather than splitting it across files, and it lacks an explicit validated workflow for spec generation. Conciseness and progressive disclosure are the weakest dimensions.

Suggestions

Move the large templates (full YAML spec, FastAPI, tsoa) into separate reference files under references/ and link to them one level deep, keeping SKILL.md a lean overview — this improves both conciseness and progressive_disclosure.

Add an explicit sequenced workflow with validation checkpoints (e.g., draft spec → run 'spectral lint' → fix errors → re-lint → 'redocly bundle' → generate SDK) to raise workflow_clarity.

Trim the 'Core Concepts' structure recap and inline examples that restate OpenAPI 3.1 knowledge Claude already has, keeping only what is non-obvious or project-specific.

Dimension	Reasoning	Score
Conciseness	The ~1020-line body inlines four enormous templates (a 460-line YAML spec, ~190-line FastAPI, ~180-line tsoa) plus full validation/SDK sections, far beyond 'could be tightened'; it is a token-heavy monolith with content that belongs in reference files rather than the overview.	1 / 3
Actionability	Provides fully executable, copy-paste-ready code and commands — complete YAML template, FastAPI and tsoa generators, Spectral/Redocly rulesets, and OpenAPI Generator invocations — matching the highest actionability anchor.	3 / 3
Workflow Clarity	Section order implies a loose sequence (structure → templates → validate → generate SDKs) and validation commands exist, but there is no explicit step-by-step workflow with validation checkpoints or fix-and-retry feedback loops for spec generation/validation, so it does not reach the top anchor.	2 / 3
Progressive Disclosure	Section headers organize the content, but everything is inline in a single 1000+ line file with no external reference files (none exist in the bundle), so content that should be split out (templates, SDK generation, validation) is not progressively disclosed.	2 / 3
	Total	8 / 12 Passed

Description

100%

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 names concrete capabilities and provides an explicit 'Use when' trigger covering documentation, SDKs, and contract compliance. It fully answers both 'what' and 'when' with natural trigger terms and a distinctive niche.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'Generate and maintain OpenAPI 3.1 specifications', 'creating API documentation', 'generating SDKs', 'ensuring API contract compliance' — matching the comprehensive-action anchor rather than the partial-coverage anchor below.	3 / 3
Completeness	Explicitly states both what ('Generate and maintain OpenAPI 3.1 specifications from code, design-first specs, and validation patterns') and when via a literal 'Use when...' clause, matching the highest anchor exactly.	3 / 3
Trigger Term Quality	Natural user-facing terms 'API documentation', 'SDKs', 'API contract compliance', and 'OpenAPI 3.1' cover the common phrasings a user would say, satisfying the good-coverage anchor; falls short only of including synonyms like 'Swagger'.	3 / 3
Distinctiveness Conflict Risk	The OpenAPI 3.1 spec-generation niche with specific triggers (SDKs, API documentation, contract compliance) is clearly distinguishable and unlikely to fire for unrelated skills.	3 / 3
	Total	12 / 12 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
Commit: e9f9b67

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