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".
71
66%
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/api-development/api-contract-generator/skills/generating-api-contracts/SKILL.mdQuality
Discovery
89%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 solid skill description that clearly communicates its purpose and provides explicit trigger guidance. Its main weakness is that the capability description could be more specific about the range of concrete actions it performs beyond just 'generate'. The trigger terms and 'Use when' clause are well-crafted and distinctive.
Suggestions
Expand the capability list with more specific actions, e.g., 'Generate API contracts and OpenAPI specifications from code or design documents, including endpoint definitions, request/response schemas, authentication requirements, and example payloads.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (API contracts, OpenAPI specifications) and mentions generating from code or design documents, but doesn't list multiple concrete actions beyond 'generate'. Could specify actions like validating schemas, generating endpoint definitions, producing request/response examples, etc. | 2 / 3 |
Completeness | Clearly answers both 'what' (generate API contracts and OpenAPI specifications from code or design documents) and 'when' (explicit 'Use when' clause and 'Trigger with phrases like' providing concrete trigger guidance). | 3 / 3 |
Trigger Term Quality | Includes good natural trigger terms: 'generate API contract', 'create OpenAPI spec', 'document API contract', 'OpenAPI specifications', 'API contracts'. These are phrases users would naturally say when needing this skill. | 3 / 3 |
Distinctiveness Conflict Risk | The focus on API contracts and OpenAPI specifications is a clear niche. The specific trigger phrases ('generate API contract', 'create OpenAPI spec') are distinct and unlikely to conflict with general code generation or documentation skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
42%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill is well-organized with good progressive disclosure and a clear error handling table, but critically lacks actionable, executable content. The instructions read as high-level descriptions rather than concrete guidance — there are no code snippets, no YAML examples, no CLI commands, and no sample Pact contracts. For a skill about generating specific file formats (OpenAPI YAML, Pact JSON), the absence of any concrete examples of those formats is a significant gap.
Suggestions
Add a concrete OpenAPI YAML snippet showing the expected output structure (info, paths, components sections) so Claude has a template to follow rather than abstract descriptions.
Include at least one executable Pact consumer test example (e.g., in JavaScript or Python) showing the actual code for defining an interaction and running verification.
Add a validation checkpoint after step 2 (e.g., 'Run `npx @stoplight/spectral-cli lint openapi.yaml` and fix all errors before proceeding') to create a feedback loop for the generated spec.
Replace the prose-only Examples section with concrete input/output pairs showing a sample route handler and the corresponding generated OpenAPI path definition.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is moderately efficient but includes some unnecessary elaboration. The Overview section restates what Claude already understands about OpenAPI specs. The Prerequisites section lists tools Claude would already know about. However, the instructions themselves are reasonably dense and not excessively padded. | 2 / 3 |
Actionability | Despite listing 8 steps, the instructions are entirely descriptive with no executable code, no concrete commands, no YAML snippets showing OpenAPI structure, and no actual Pact test examples. Steps like 'Scan existing route handlers' and 'Generate OpenAPI 3.0 specification' describe what to do abstractly without showing how. The examples section also only describes scenarios in prose rather than providing concrete input/output pairs. | 1 / 3 |
Workflow Clarity | The 8 steps provide a reasonable sequence from extraction through generation and testing, and the error handling table adds useful troubleshooting. However, there are no explicit validation checkpoints between steps — for instance, no step to lint/validate the generated OpenAPI spec with Spectral before proceeding to Pact contract generation, despite mentioning Spectral in prerequisites. | 2 / 3 |
Progressive Disclosure | The skill effectively uses progressive disclosure with clear references to separate files: implementation.md for the full guide, errors.md for comprehensive error patterns, and examples.md for additional examples. References are one level deep and clearly signaled. The main file serves as a well-structured overview. | 3 / 3 |
Total | 8 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 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 | 9 / 11 Passed | |
- Commit
3e83543
- 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.