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 concisely covers specific capabilities, includes natural trigger terms, and clearly delineates both what the skill does and when to use it. The mention of 'OpenAPI 3.1' provides excellent distinctiveness, and the 'Use when...' clause covers the key scenarios effectively. It uses proper third-person voice throughout.
| 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 specs from code, design-first specs, 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', 'validation'. These cover common terms a user working with API specs would naturally use. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with the specific mention of 'OpenAPI 3.1 specifications' and related triggers like 'SDK generation' and 'API contract compliance'. 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 dominated by a massive inline OpenAPI template that Claude could generate on its own, while the actually useful content (code-first generation, validation, SDK generation workflows) is deferred to a reference file. It lacks any clear workflow or step-by-step process for the tasks it claims to support, and includes basic concepts and generic best practices that waste tokens. The skill would benefit from being restructured around actionable workflows with the template moved to a reference file.
Suggestions
Replace the massive inline YAML template with a brief skeleton (10-15 lines) and move the full template to a reference file, since Claude can generate complete OpenAPI specs from minimal guidance.
Add explicit step-by-step workflows for the main use cases (e.g., 'Creating a spec from scratch', 'Generating from existing code', 'Validating a spec') with validation checkpoints at each stage.
Remove the 'Core Concepts' section explaining OpenAPI structure and design approaches—Claude already knows these well.
Remove or drastically condense the generic do's/don'ts list, keeping only project-specific conventions that Claude wouldn't already know.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose, with a massive inline YAML template (~300 lines) that Claude could easily generate from a brief description. The 'Core Concepts' section explains basic OpenAPI structure and design approaches (design-first vs code-first) that Claude already knows well. The do's/don'ts are generic API design advice Claude doesn't need. | 1 / 3 |
Actionability | The complete YAML template is concrete and copy-paste ready, which is good. However, it's essentially just one large example spec rather than actionable guidance on how to generate or maintain specs. The actual generation workflows (code-first, validation, SDK generation) are deferred to a reference file with only bullet-point summaries. | 2 / 3 |
Workflow Clarity | There is no clear workflow or sequenced steps for generating, validating, or maintaining OpenAPI specs. The skill lists 'When to Use' scenarios but never provides a step-by-step process for any of them. Validation and linting are mentioned only as references to an external file, with no inline validation checkpoints. | 1 / 3 |
Progressive Disclosure | The skill does reference an external file for code-first patterns and tooling, which is appropriate. However, the main file itself is a monolithic wall of YAML that should have been the reference material, while the SKILL.md should have been a concise overview with workflows. The structure is inverted—detailed content is inline while actionable workflows are deferred. | 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
27a7ed9
- 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.