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.
80
71%
Does it follow best practices?
Impact
98%
1.19xAverage score across 3 eval scenarios
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.mdQuality
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 specification generation and maintenance. It includes an explicit 'Use when' clause with natural trigger terms, lists concrete actions, and occupies a distinct niche. The description is concise yet comprehensive, following the pattern of good examples in the rubric.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'generate and maintain OpenAPI 3.1 specifications from code', 'design-first specs', 'validation patterns', 'creating API documentation', 'generating SDKs', 'ensuring API contract compliance'. | 3 / 3 |
Completeness | Clearly answers both what ('Generate and maintain OpenAPI 3.1 specifications from code, design-first specs, and validation patterns') and when ('Use when creating API documentation, generating SDKs, or ensuring API contract compliance') with an explicit 'Use when' clause. | 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 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 bloated - the bulk of the content is boilerplate templates that Claude can generate from minimal guidance, and the same User Management API is repeated three times in different frameworks. The content would be far more effective as a concise overview with references to separate template files.
Suggestions
Reduce the main SKILL.md to ~50-80 lines covering key patterns, gotchas, and tool commands, then move the full YAML spec, FastAPI, and tsoa templates into separate referenced files (e.g., templates/openapi-yaml.md, templates/fastapi.md).
Remove explanations of concepts Claude already knows (OpenAPI structure, design approaches table, what $ref does) and focus on project-specific conventions or non-obvious patterns.
Add an explicit sequential workflow: 'Design spec → Validate with Spectral → Fix errors → Re-validate → Generate SDK → Verify generated code' with clear checkpoints.
Consolidate the three duplicate User Management API examples into one canonical template, noting only the framework-specific annotations/decorators needed for code-first generation.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose - the complete API specification template alone is ~300 lines of YAML that Claude could generate on its own. The Python FastAPI and TypeScript tsoa templates largely duplicate the same User Management API in different languages. The 'Core Concepts' section explains OpenAPI structure and design approaches that Claude already knows well. Most of this content is reference material that doesn't add novel knowledge. | 1 / 3 |
Actionability | The content is highly actionable with fully executable code examples: complete OpenAPI YAML specs, working FastAPI Python code, TypeScript tsoa controllers, bash commands for validation tools (Spectral, Redocly), and SDK generation commands. All examples are copy-paste ready. | 3 / 3 |
Workflow Clarity | The validation section provides concrete linting commands but lacks a clear sequential workflow with validation checkpoints. There's no explicit process like 'write spec → validate → fix errors → re-validate → generate SDK.' The skill presents templates and tools but doesn't sequence them into a coherent workflow with feedback loops. | 2 / 3 |
Progressive Disclosure | This is a monolithic wall of content with ~600+ lines inline. The massive YAML template, three full code-first templates, validation configs, and SDK generation commands should be split into separate referenced files. There are no internal cross-references or navigation aids beyond flat section headers. | 1 / 3 |
Total | 7 / 12 Passed |
Validation
90%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
47823e3
- Reviewed
Table of Contents
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.