Openapi spec design
Curated, auditable, benchmark-ready Agent Skills library for Claude Code, Codex, OpenCode, Cursor, and more.
npx -y skills add shinzoxD/knackbox --skill openapi-spec-designAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- 27 days oldThe repository was created 27 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
- 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Design and review OpenAPI specifications for clarity, consistency, and evolution. Use whenever the user writes OpenAPI or Swagger YAML/JSON, reviews API specs, or asks how to document REST endpoints for code generation and client SDKs.
The file declares its own license as Apache-2.0. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.
SKILL.md
1.6 KB, as published. Nobody here has run it
OpenAPI Spec Design
The spec is a contract. Optimize for accurate types, examples, error shapes, and non-breaking evolution.
Checklist
- openapi version, info, servers
- paths: methods, operationId, tags, summary
- parameters vs requestBody clarity
- schemas: required fields, enums, formats, nullable
- responses: success + error components
- securitySchemes and per-operation security
- examples that match schemas
- deprecation flags and changelog alignment
Output format
## OpenAPI review / design
### Issues
1. …
### Recommended components
…
### Example path sketch
```yaml
# snippet
## Rules
1. operationId stable and unique for codegen.
2. Do not mark fields required if servers omit them.
3. Reuse components.schemas; avoid copy-paste drift.
4. Document auth failures (401/403) consistently.
5. Breaking schema changes need versioning strategy.
6. Examples must validate against the schema mentally.
## Edge cases
- **File uploads:** multipart content types.
- **Webhooks:** callbacks section.
- **Polymorphism:** oneOf/anyOf discriminators carefully.