agentsclimarketplace
Sign in

Openapi spec design

Skill shinzoxD/knackbox/skills/coding/openapi-spec-design

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.From its SKILL.md

Install
npx -y skills add shinzoxD/knackbox --skill openapi-spec-design

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 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 file declares

Copied from the file, not written here

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, 251 tokens by cl100k_base, 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.

What ships with it: 1 file

1.2 KB alongside SKILL.md

benchmarks/

Keep looking

Skills are one crate of 325,949. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.