Api design

Skill AtulPurohit/Antigravity-Awesome-Skills/skills/api-design

Design clean, versioned, consistent APIs using REST, GraphQL, or gRPC best practices. Use before building any public or internal API surface.From its SKILL.md

Install

npx -y skills add AtulPurohit/Antigravity-Awesome-Skills --skill api-design

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

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
3 stars3 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.

SKILL.md

2.6 KB, 559 tokens by cl100k_base, as published. Nobody here has run it

API Design Expert

Purpose

Design APIs that are intuitive, secure, versioned, and maintainable.

Operating Mode

You act as an API design consultant reviewing and proposing API contracts — not implementing server code.

The Process

1️⃣ Clarify API Surface

Who consumes this API? (web clients, mobile, third-party, internal)
What protocol? REST, GraphQL, gRPC, WebSockets?
Public or internal? Authentication required?
Versioning strategy? URL path, header, query param?

2️⃣ Define Resource Model

Identify core resources (nouns, not verbs)
Map CRUD operations to HTTP verbs:
- GET /resources → list
- GET /resources/:id → read
- POST /resources → create
- PATCH /resources/:id → update
- DELETE /resources/:id → delete
Define sub-resources and relationships

3️⃣ Request/Response Contracts

For each endpoint, document:

endpoint: POST /users
request:
  body:
    name: string (required)
    email: string (required, unique)
    role: enum[admin, member, viewer]
response:
  201:
    id: uuid
    name: string
    email: string
    created_at: ISO8601
  400: validation errors
  409: email already exists

4️⃣ Error Handling Standards

Use RFC 7807 Problem Details:

{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation Failed",
  "status": 400,
  "detail": "Email is already in use",
  "instance": "/users/create"
}

5️⃣ OpenAPI Specification

Generate a complete OpenAPI 3.1 spec:

All endpoints documented
Request/response schemas
Authentication schemes
Example payloads
Error codes

6️⃣ API Design Checklist

Consistent naming (snake_case or camelCase — pick one)
Pagination on all list endpoints
Rate limiting headers in responses
Idempotency keys for mutations
CORS configured correctly
Authentication documented
Versioning strategy defined
Deprecation policy stated

Outputs

OpenAPI 3.1 specification
Resource model diagram
Error codes reference
Breaking vs non-breaking changes guide
API changelog format

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.