openapi

Swagger + Speakeasy SDK/MCP pipeline (make swagger, sdk-all), api/custom merge. Trigger: openapi, swagger, sdk-all, MCP.

Quality

79%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.cursor/skills/openapi/SKILL.md

Quality

Content

80%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The content is exceptionally concise, well-structured, and actionable with concrete make targets and file paths. Its main gap is the absence of an explicit validation feedback loop for the batch generation/merge pipeline, which caps workflow clarity at 3.

Suggestions

Add an explicit validation feedback loop for the generation/merge pipeline, e.g. 'If `make sdk-all` validation fails: fix the Swagger annotations, re-run `make swagger`, then `make sdk-all` again.'

Spell out the key make-target arguments (e.g. which languages `sdk-all` covers) so commands are fully copy-paste ready without consulting AGENTS.md.

Note how to confirm the regenerated SDKs/MCP are correct (a smoke test or diff check) as a final checkpoint after `make sdk-all`.

Dimension	Reasoning	Score
Conciseness	The body is lean and assumes Claude's competence — every section is tight bullet guidance with no padding or explanation of concepts Claude already knows, matching the score 5 anchor.	5 / 5
Actionability	Provides concrete executable commands ('make swagger', 'make sdk-all', 'make speakeasy-validate', 'make merge-custom') with real file paths, but a few targets rely on the reader to infer exact flags/args, keeping it just below copy-paste-ready score 5.	4 / 5
Workflow Clarity	The Standard sequence is clearly ordered and validation exists (sdk-all 'validates' plus speakeasy-validate), but there is no explicit validate->fix->retry feedback loop, and the rubric caps batch/generation operations at 3 without one.	3 / 5
Progressive Disclosure	A short (<50 line) single-purpose skill with no bundle files and no need for external references, but with well-organized labeled sections, qualifying for the score 5 simple-skill exception.	5 / 5
	Total	17 / 20 Passed

Description

78%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description concisely covers what the skill does and when to use it via an explicit trigger clause, with a distinct niche and concrete actions. It is held back from top marks only by jargon-dense phrasing and a lack of natural-synonym variations.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions ('make swagger', 'sdk-all', 'api/custom merge', 'MCP') with minor coverage gaps, matching the 'lists several specific actions; minor gaps' anchor rather than score 3's 1-2 actions.	4 / 5
Completeness	States both a clear 'what' (Swagger + Speakeasy SDK/MCP pipeline) and an explicit 'when' via the 'Trigger:' clause, but the dense jargon in the what keeps it below the clearly-explicit score 5 anchor.	4 / 5
Trigger Term Quality	Provides good keyword coverage via 'Trigger: openapi, swagger, sdk-all, MCP' that users would naturally say, though it leans on proper-noun jargon and lacks synonyms/variations, fitting score 4 over 5.	4 / 5
Distinctiveness Conflict Risk	Targets a clear niche with distinct triggers (openapi, swagger, sdk-all, MCP) and minimal conflict risk, matching the score 5 anchor.	5 / 5
	Total	17 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: flexprice/flexprice
Path: .cursor/skills/openapi/SKILL.md
Commit: 862cb79

Reviewed: 4 days ago

Table of Contents

Discovery Implementation Validation

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.