openapi-to-typescript
Converts OpenAPI 3.0 JSON/YAML to TypeScript interfaces and type guards. This skill should be used when the user asks to generate types from OpenAPI, convert schema to TS, create API interfaces, or generate TypeScript types from an API specification.
88
82%
Does it follow best practices?
Impact
100%
1.51xAverage score across 3 eval scenarios
Passed
No known issues
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 well-crafted skill description that excels across all dimensions. It uses third person voice, specifies concrete inputs and outputs, includes natural trigger terms users would actually say, and has an explicit 'Use when' clause with multiple trigger scenarios. The description is concise yet comprehensive, making it easy for Claude to select this skill appropriately.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'Converts OpenAPI 3.0 JSON/YAML to TypeScript interfaces and type guards' - clearly specifies input format (OpenAPI 3.0 JSON/YAML) and outputs (TypeScript interfaces, type guards). | 3 / 3 |
Completeness | Clearly answers both what ('Converts OpenAPI 3.0 JSON/YAML to TypeScript interfaces and type guards') AND when ('should be used when the user asks to generate types from OpenAPI, convert schema to TS, create API interfaces, or generate TypeScript types from an API specification'). | 3 / 3 |
Trigger Term Quality | Includes natural keywords users would say: 'generate types from OpenAPI', 'convert schema to TS', 'create API interfaces', 'generate TypeScript types', 'API specification'. Good coverage of variations including abbreviation 'TS'. | 3 / 3 |
Distinctiveness Conflict Risk | Clear niche with distinct triggers - specifically targets OpenAPI to TypeScript conversion. The combination of 'OpenAPI', 'TypeScript', 'type guards', and 'interfaces' creates a unique fingerprint unlikely to conflict with general code generation or other schema tools. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
64%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides excellent actionability with concrete, executable TypeScript examples and comprehensive type mapping guidance. However, it's somewhat verbose for a skill file, combining reference documentation with workflow instructions. The workflow could benefit from explicit validation steps after code generation (e.g., verify TypeScript compiles).
Suggestions
Add a validation step after generation: 'Run `tsc --noEmit types/api.ts` to verify output compiles correctly'
Move the detailed type mapping tables and complete example to a separate REFERENCE.md file, keeping SKILL.md as a concise overview
Remove the 'When to Use' section as it duplicates the skill description metadata
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient but includes some redundancy. The 'When to Use' section duplicates the description, and some explanations (like the type mapping tables) could be more compact. However, it avoids explaining basic concepts Claude knows. | 2 / 3 |
Actionability | Provides fully executable TypeScript code examples, complete input/output demonstrations, specific type mapping tables, and copy-paste ready type guards. The complete example section shows exact transformation from OpenAPI JSON to TypeScript output. | 3 / 3 |
Workflow Clarity | The 7-step workflow is clearly sequenced, but lacks explicit validation checkpoints beyond the initial OpenAPI validation. No feedback loop for handling generation errors or verifying the output TypeScript compiles correctly. | 2 / 3 |
Progressive Disclosure | Content is well-organized with clear sections and headers, but it's a monolithic document (~200 lines) that could benefit from splitting detailed reference material (type mapping tables, complete examples) into separate files while keeping the SKILL.md as a concise overview. | 2 / 3 |
Total | 9 / 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
- softaworks/agent-toolkit
- Commit
3027f20
- 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.