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.
55
61%
Does it follow best practices?
Impact
—
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 specifications with concrete actions, natural trigger terms, and an explicit 'Use when' clause. It effectively distinguishes itself from general API or documentation skills by specifying the OpenAPI standard version and covering multiple use cases (documentation, SDKs, contract compliance).
| 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' clause covering API documentation, SDK generation, and 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 the specific focus on OpenAPI 3.1 specifications. The combination of 'OpenAPI', 'SDK generation', and 'API contract compliance' creates a clear niche that is unlikely to conflict with general documentation or coding 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 reads more like a general overview or cheat sheet about OpenAPI specifications rather than actionable guidance for Claude. It explains concepts Claude already knows (OpenAPI structure, design approaches), provides no executable commands or concrete workflows, and defers all substantive content to a referenced file that doesn't exist in the bundle. The best practices section is generic advice rather than specific, actionable instructions.
Suggestions
Replace the 'Core Concepts' section with concrete, executable workflows: e.g., specific commands to generate a spec from code using a named tool, validate a spec, or generate an SDK.
Add a clear multi-step workflow with validation checkpoints, such as: 1) Generate spec → 2) Validate with `npx @redocly/cli lint spec.yaml` → 3) Fix errors → 4) Re-validate → 5) Generate SDK.
Remove the design approaches table and OpenAPI structure overview—Claude already knows these. Use the saved space for copy-paste-ready templates and concrete examples.
Either include the `references/details.md` file in the bundle or inline the most critical templates and examples directly in the skill body.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill includes some unnecessary content like the 'When to Use This Skill' bullet list (Claude can infer applicability), the 'Core Concepts' section explaining OpenAPI structure (Claude already knows this), and the design approaches table which is general knowledge. However, it's not excessively verbose. | 2 / 3 |
Actionability | The skill provides no executable commands, no concrete code for generating or validating specs, and no specific tool usage. The YAML snippet is just a structural overview Claude already knows. The actual templates and worked examples are deferred to a referenced file that doesn't exist in the bundle, leaving the main skill with only vague do's and don'ts. | 1 / 3 |
Workflow Clarity | There is no sequenced workflow for any of the stated use cases (generating specs, validating implementations, generating SDKs). No validation checkpoints, no feedback loops, and no step-by-step process is defined. The content is purely descriptive rather than procedural. | 1 / 3 |
Progressive Disclosure | The skill references `references/details.md` for templates and worked examples, which is a reasonable one-level-deep reference. However, no bundle files are provided, so the reference is unverifiable and potentially broken. The main file itself contains too much general knowledge content inline while deferring all the actionable content elsewhere. | 2 / 3 |
Total | 6 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- wshobson/agents
- Commit
cf6059d
- 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.