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.
68
61%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/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 relevant trigger scenarios, uses third-person voice correctly, and provides enough specificity to distinguish it from general API or documentation skills. The description is concise yet comprehensive.
| 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
22%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is essentially a large OpenAPI 3.1 YAML template with minimal instructional content around it. It lacks workflows for the stated use cases (generating specs from code, validation, SDK generation), explains concepts Claude already knows, and buries the reader in a massive inline example that should be a referenced file. The best practices section is useful but generic.
Suggestions
Replace the 350-line inline YAML template with a concise 20-30 line skeleton and move the full template to a reference file (e.g., references/complete-template.yaml)
Add explicit step-by-step workflows for the key use cases: creating a spec from scratch, generating from existing code, and validating an implementation against a spec — each with validation checkpoints
Remove the 'Core Concepts' section explaining OpenAPI structure and design approaches, as Claude already knows these well
Add concrete commands for validation (e.g., spectral lint, redocly lint) directly in the main skill file rather than deferring all tooling to a reference
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose, with a ~350-line YAML template that Claude could easily generate from a much shorter description. The 'Core Concepts' section explains basic OpenAPI structure and design approaches (design-first vs code-first) that Claude already knows well. The complete User Management API template, while valid, is far too long for a skill file and should be a referenced example. | 1 / 3 |
Actionability | The massive YAML template is concrete and copy-paste ready, which is good. However, there are no actual commands or steps for generating specs from code, validating specs, or generating SDKs — those are deferred to a reference file. The skill describes what a spec looks like rather than instructing how to create/maintain one. | 2 / 3 |
Workflow Clarity | There is no clear workflow or sequenced steps for any of the stated use cases (creating specs, validating implementations, generating SDKs). The skill is essentially a large template plus a best practices list, with no process for how to go from input to output, and no validation checkpoints despite the skill covering validation patterns. | 1 / 3 |
Progressive Disclosure | The skill does reference an external file (references/code-first-and-tooling.md) for additional templates, which is good. However, the main file itself is a monolithic wall of YAML that should have been the referenced content, with the SKILL.md serving as a concise overview with navigation to detailed templates. | 2 / 3 |
Total | 6 / 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 (537 lines); consider splitting into references/ and linking | Warning |
Total | 10 / 11 Passed | |
- Repository
- wshobson/agents
- Commit
70444e5
- 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.