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".
68
62%
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, validate endpoint schemas, produce request/response examples, and define authentication requirements.'
| 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 documentation, 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
35%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides a well-structured outline for API contract generation with good section organization and a useful error handling table, but critically lacks executable code examples—no OpenAPI YAML snippets, no Pact JSON examples, no shell commands. The instructions read as a high-level process description rather than actionable guidance Claude can follow. Referenced bundle files (implementation.md, errors.md, examples.md) don't exist, undermining the progressive disclosure strategy.
Suggestions
Add concrete, executable examples: include a minimal OpenAPI YAML snippet showing the expected output structure, a Pact consumer test code block, and actual CLI commands (e.g., `npx spectral lint openapi.yaml`).
Add explicit validation checkpoints in the workflow: after step 2, add 'Run `npx spectral lint openapi.yaml` and fix all errors before proceeding'; after step 6, add 'Run Pact verification and confirm all interactions pass'.
Either provide the referenced bundle files (implementation.md, errors.md, examples.md) or inline the most critical content—currently the references point to nothing.
Remove the prerequisites section or reduce it to a single line; Claude doesn't need to be told what Swagger Editor or Spectral are.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill includes some unnecessary verbosity—the overview paragraph restates what the title and description already convey, and the prerequisites section lists general tooling knowledge Claude already possesses. However, the instructions and tables are reasonably efficient. | 2 / 3 |
Actionability | Despite listing 8 steps, the skill provides no executable code, no concrete YAML snippets for OpenAPI specs, no Pact contract examples, and no actual commands. Every instruction is descriptive rather than executable—'Scan existing route handlers', 'Generate OpenAPI 3.0 specification', 'Create Pact consumer contract tests' are all abstract directives without copy-paste-ready implementations. | 1 / 3 |
Workflow Clarity | The 8 steps provide a reasonable sequence, and the error handling table adds some validation guidance. However, there are no explicit validation checkpoints within the workflow itself—no 'run Spectral lint and fix before proceeding' step, no feedback loops for spec validation, and the critical verify-before-commit step is only mentioned in the error table rather than the workflow. | 2 / 3 |
Progressive Disclosure | The skill references external files (implementation.md, errors.md, examples.md) which is good structure, but no bundle files are provided, meaning those references lead nowhere. The main file itself is moderately well-organized with clear sections, but the inline content is somewhat long for an overview that's supposed to point to detailed materials. | 2 / 3 |
Total | 7 / 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
3a2d27d
- 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.