generating-api-contracts
tessl i github:jeremylongshore/claude-code-plugins-plus-skills --skill generating-api-contractsGenerate 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".
Validation
81%| Criteria | Description | Result |
|---|---|---|
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
metadata_version | 'metadata' field is not a dictionary | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 13 / 16 Passed | |
Implementation
7%This skill content is largely boilerplate with minimal actionable guidance for generating API contracts. It lacks concrete examples of OpenAPI specifications, executable code for contract generation, and clear workflows. The content describes what to do at a high level but fails to show how to do it.
Suggestions
Add a concrete, executable example showing how to generate an OpenAPI 3.0 spec from code, including actual YAML/JSON output
Fix the duplicate numbered lists and create a clear sequential workflow with validation steps (e.g., 'validate spec with openapi-generator validate')
Remove redundant introductory sentences and generic prerequisites; focus on specific tools and commands for contract generation
Include at least one complete input/output example showing source code transforming into an OpenAPI specification
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Contains significant padding and redundancy ('This skill provides automated assistance' repeated twice), explains obvious concepts Claude knows (what prerequisites are, basic API concepts), and includes generic boilerplate that doesn't add value. | 1 / 3 |
Actionability | Provides only vague, abstract guidance with no concrete code examples, no executable commands, and no specific OpenAPI schema examples. Instructions like 'Define resource models' and 'Document request/response schemas' describe rather than instruct. | 1 / 3 |
Workflow Clarity | Steps are poorly organized with duplicate numbering (two separate lists both starting at 1), no clear sequence between phases, and no validation checkpoints. Missing feedback loops for verifying generated contracts are valid. | 1 / 3 |
Progressive Disclosure | References external files (implementation.md, errors.md, examples.md) which is appropriate structure, but the main content is poorly organized and the references feel like placeholders rather than well-signaled navigation to specific content. | 2 / 3 |
Total | 5 / 12 Passed |
Activation
90%This is a well-structured description that clearly defines its purpose and provides explicit trigger phrases. The main weakness is that the capability list could be more comprehensive, specifying additional actions like validation, schema generation, or endpoint documentation. The description effectively uses third person voice and provides good trigger term coverage.
Suggestions
Expand the capabilities list with more specific actions such as 'validate existing specs', 'generate schema definitions', or 'create endpoint documentation'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (API contracts, OpenAPI specifications) and mentions actions (generate, create, document) with input sources (code or design documents), but doesn't list comprehensive specific actions like validation, versioning, or endpoint documentation. | 2 / 3 |
Completeness | Clearly answers both what (generate API contracts and OpenAPI specifications from code or design documents) and when (documenting API contracts, with explicit trigger phrases provided). | 3 / 3 |
Trigger Term Quality | Includes explicit trigger phrases users would naturally say: 'generate API contract', 'create OpenAPI spec', 'document API contract'. Also mentions 'OpenAPI specifications' and 'API contracts' as natural keywords. | 3 / 3 |
Distinctiveness Conflict Risk | Clear niche focused specifically on API contracts and OpenAPI specs with distinct triggers. Unlikely to conflict with general documentation or code generation skills due to specific terminology. | 3 / 3 |
Total | 11 / 12 Passed |
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.