API Designer
Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture.
Before & after
Same prompt, same agent — the only difference is the skill.
That's a complex API with lots of moving parts. Before I sketch endpoints, I'd need to know: Who's your primary user? How many uploads per day are you expecting? Do you need real-time notifications? Will you have complex permissions (followers, private albums)? What's your data model for photos, comments, likes? Once we nail those, I can design the endpoints and versioning strategy.
REST API DESIGN: SocialPhoto v1
RESOURCE ENDPOINTS
Users
GET /api/v1/users/{id} → User profile (name, avatar, follower count)
PATCH /api/v1/users/{id} → Update profile
DELETE /api/v1/users/{id} → Deactivate account
Photos
POST /api/v1/photos → Upload (multipart/form-data, 5MB max)
GET /api/v1/photos/{id} → Fetch with comments count
PATCH /api/v1/photos/{id} → Update caption or visibility
DELETE /api/v1/photos/{id} → Soft delete
GET /api/v1/photos?user_id={id}&limit=20&offset=0 → Paginated feed
Comments
POST /api/v1/photos/{id}/comments → Add comment
GET /api/v1/photos/{id}/comments?limit=10 → Paginated
DELETE /api/v1/comments/{id} → Remove comment
Likes
POST /api/v1/photos/{id}/like → Toggle like (idempotent)
GET /api/v1/photos/{id}/likes?limit=50 → Liker list
ERROR HANDLING
• 400 Bad Request (invalid JSON, missing field)
• 401 Unauthorized (expired token)
• 403 Forbidden (not owner of resource)
• 404 Not Found (resource doesn't exist)
• 429 Too Many Requests (rate limited at 100 req/min)
• 500 Internal Server Error (DB down)
VERSIONING: URL-based (/v1/, /v2/) for clarity
AUTHENTICATION: Bearer JWT in Authorization header
PAGINATION: Cursor-based (offset + limit pattern above)
RATING: 200 photos/user/day soft limitAbout this skill
name: api-designer description: Use when Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture.
Api Designer
Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture. Invoke for resource modeling, versioning strategies, pagination patterns, error handling standards.
What you get
- Public GitHub repo
- the skills/api-designer folder with SKILL.md and references.
Customize your output
- Fork the repo and extend the skill's reference files for your own stack conventions.
Example output
Activates on a matching request (e.g. building or reviewing Api Designer code) and can chain with other skills in the pack.
Best for
Full-stack developers and engineering teams using Claude Code.
SKILL.md preview
---
name: api-designer
description: Use this skill when designing REST or GraphQL APIs, writing OpenAPI specifications, or planning API architecture.
version: 1.0.0
category: Development / Backend
author: AgentVolt
license: proprietary
tags:
- development
- backend
---
# Api Designer
Designs REST and GraphQL APIs with attention to resource modeling, versioning, and error semantics, and produces the OpenAPI or schema artifacts that document them.
## When to use
… (sign up to view the full skill)More development skills
View all Development skills →Golang Pro
Implements concurrent Go patterns with goroutines and channels, designs microservices over gRPC or REST, profiles performance with pprof.
Laravel Specialist
Build Laravel 12 and 13 apps: Eloquent models and relationships, Sanctum auth, Horizon queues, API resources, and Livewire interfaces.
Django Expert
Use when building Django web applications or REST APIs with Django REST Framework.
Microservices Architect
Designs distributed system architectures, decomposes monoliths into bounded-context services, recommends communication patterns, and produces service boundary diagrams and resilience strategies.