generating-api-contracts

Generate API contracts and OpenAPI specifications from code or design documents. Use when documenting API contracts and specifications. Trigger with phrases like "generate API contract", "create OpenAPI spec", or "document API contract".

Quality

93%

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

Quality

Content

87%Weight 40%Scale 1-3

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

A concise, well-structured skill body with concrete field-level guidance and clean progressive disclosure to real reference files. Its main weakness is the workflow: the numbered steps omit explicit validation checkpoints even though validation (Spectral linting, example validation) is referenced elsewhere.

Suggestions

Insert an explicit validation checkpoint in the numbered workflow, e.g. after generating the spec: 'Lint with Spectral and auto-validate examples; fix and re-lint before proceeding.'

Add a short copy-paste OpenAPI skeleton (info/paths/components with one operation) so the spec-generation step is concrete and executable rather than descriptive.

Make the provider-verification step (step 7) a genuine feedback loop: 'If verification fails, update the provider to satisfy the contract, then re-verify.'

Dimension	Reasoning	Score
Conciseness	The body is lean and well-organized with no padding or explanation of concepts Claude already knows; each section (steps, output, error table, examples) earns its place.	3 / 3
Actionability	Steps give concrete, field-level guidance (specific OpenAPI keys, status codes 200/201/400/401/403/404/500, security schemes bearerAuth/apiKey/oauth2) and name tools (Grep, Read); for an instruction-only skill this guidance is actionable without code.	3 / 3
Workflow Clarity	The 8 steps are clearly sequenced, but validation checkpoints are only implicit — Spectral linting and example/schema auto-validation are mentioned as prerequisites or error fixes, never as explicit validate-then-proceed steps in the workflow.	2 / 3
Progressive Disclosure	Clear overview body with well-signaled one-level-deep references (implementation.md, errors.md, examples.md) plus the generate-contract.sh script, all of which exist as real bundle files.	3 / 3
	Total	11 / 12 Passed

Description

100%Weight 40%Scale 1-3

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

A well-crafted description that states concrete capabilities, gives an explicit 'Use when' clause, and lists natural trigger phrases in third-person voice. It closely matches the rubric's good examples with no notable fluff or over-claims.

Dimension	Reasoning	Score
Specificity	Names multiple concrete deliverables ('Generate API contracts and OpenAPI specifications from code or design documents'), specifying both outputs and source inputs rather than vague actions.	3 / 3
Completeness	Explicitly answers what it does ('Generate API contracts and OpenAPI specifications...') and when to use it ('Use when documenting API contracts and specifications') with explicit trigger guidance.	3 / 3
Trigger Term Quality	Provides three natural trigger phrases a user would say ('generate API contract', 'create OpenAPI spec', 'document API contract'), giving good coverage of likely phrasings.	3 / 3
Distinctiveness Conflict Risk	Targets a clear niche (API contracts / OpenAPI specs / Pact contract testing) with distinct triggers unlikely to fire for unrelated skills.	3 / 3
	Total	12 / 12 Passed

Validation

87%

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 — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	14 / 16 Passed

Repository: jeremylongshore/claude-code-plugins-plus-skills
Path: plugins/api-development/api-contract-generator/skills/generating-api-contracts/SKILL.md
Commit: 0540a62

Reviewed: 1 day 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.