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

71%

Does it follow best practices?

Impact

98%

1.19x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Optimize this skill with Tessl

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

Quality

Discovery

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.

This is a strong skill description that clearly defines its scope around OpenAPI 3.1 specifications, lists concrete actions, includes natural trigger terms developers would use, and has an explicit 'Use when' clause with specific scenarios. It is concise, uses third-person voice correctly, and would be easily distinguishable from other skills in a large skill library.

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions: 'generate and maintain OpenAPI 3.1 specifications', 'creating API documentation', 'generating SDKs', 'ensuring API contract compliance'. Also mentions specific inputs: 'from code, design-first specs, and validation patterns'.	3 / 3
Completeness	Clearly answers both 'what' (generate and maintain OpenAPI 3.1 specs from code, design-first specs, and validation patterns) and 'when' (explicit 'Use when creating API documentation, generating SDKs, or ensuring API contract compliance').	3 / 3
Trigger Term Quality	Includes strong natural keywords users would say: 'OpenAPI', '3.1', 'API documentation', 'SDKs', 'API contract', 'specifications', 'design-first'. These are terms developers naturally use when working with API specs.	3 / 3
Distinctiveness Conflict Risk	Highly distinctive with a clear niche around OpenAPI 3.1 specifications specifically. The combination of 'OpenAPI', 'SDK generation', and 'API contract compliance' creates a well-defined scope unlikely to conflict with general coding or documentation skills.	3 / 3
	Total	12 / 12 Passed

Implementation

42%

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

The skill provides comprehensive, executable examples for OpenAPI spec generation across multiple languages and tools, which is its primary strength. However, it is severely over-long and monolithic — the full API spec templates, complete code-first examples, and tool configurations should be split into referenced files. The content also explains many concepts Claude already knows (design approaches table, basic OpenAPI structure) and lacks a clear workflow connecting spec creation, validation, error correction, and SDK generation.

Suggestions

Extract the large templates (YAML spec, Python/FastAPI, TypeScript/tsoa, validation configs) into separate referenced files and keep only a concise overview with links in the main SKILL.md.

Remove the 'Core Concepts' section (OpenAPI structure, design approaches table) — Claude already knows these fundamentals.

Add an explicit end-to-end workflow with validation checkpoints: write/generate spec → lint with Spectral → fix errors → re-lint → bundle → generate SDK → verify generated code.

Trim the best practices section to only non-obvious guidance; items like 'use semantic versioning' and 'document errors' are standard knowledge.

Dimension	Reasoning	Score
Conciseness	Extremely verbose - the massive YAML template (~300 lines) and full Python/TypeScript code-first examples are things Claude can generate on its own. The skill explains basic concepts like design approaches (design-first vs code-first) and includes a full User Management API spec that doesn't teach anything Claude doesn't already know. The content could be reduced by 80%+ while preserving all unique value.	1 / 3
Actionability	The content is highly actionable with complete, executable code examples across multiple languages (YAML spec, Python/FastAPI, TypeScript/tsoa), working CLI commands for validation tools (Spectral, Redocly), and SDK generation commands that are copy-paste ready.	3 / 3
Workflow Clarity	While individual templates are clear, there's no explicit workflow connecting the steps (e.g., write spec → validate → fix errors → generate SDK). The validation section has commands but lacks a feedback loop for fixing errors. The 'When to Use' section lists scenarios but doesn't sequence them into a process.	2 / 3
Progressive Disclosure	This is a monolithic wall of content with ~600+ lines all inline. The massive YAML template, full Python file, full TypeScript file, and validation configs should all be in separate referenced files. There's no overview-then-drill-down structure; everything is dumped into a single document.	1 / 3
	Total	7 / 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

Repository: Dicklesworthstone/pi_agent_rust
Commit: 6e3d68c

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.