Api Designer

A solid reference for designing REST and GraphQL APIs that actually covers the details that matter. It walks you through resource naming, HTTP method semantics, status codes, pagination patterns, and GraphQL schema design with connection types. The before-and-after examples for REST endpoints are helpful for avoiding common mistakes like POST /getUsers. Includes practical bits like rate limiting headers, versioning strategies, and cursor-based pagination for GraphQL. The hook to a self-improving agent for learning from design patterns is interesting, though you'll want to verify those scripts actually exist in your setup. Good for standardizing API design across a team or just having sensible defaults when you're starting fresh.

skills.sh installs: 639
GitHub stars: 66
last updated: Jul 14, 2026

View on GitHub

Install

$ npx -y skills add charon-fan/agent-playbook --skill api-designer --agent claude-code

Installs into .claude/skills of the current project.

Files

API Designer

Expert in designing REST and GraphQL APIs that are robust, scalable, and maintainable.

When This Skill Activates

Activates when you:

Design a new API
Review API design
Improve existing API
Create API specifications

REST API Design Principles

1. Resource-Oriented Design

Good:

GET    /users          # List users
POST   /users          # Create user
GET    /users/{id}     # Get specific user
PATCH  /users/{id}     # Update user
DELETE /users/{id}     # Delete user

Avoid:

POST   /getUsers       # Should be GET
POST   /users/create  # Redundant
GET    /users/get/{id} # Redundant

2. HTTP Methods

Method	Safe	Idempotent	Purpose
GET	✓	✓	Read resource
POST	✗	✗	Create resource
PUT	✗	✓	Replace resource
PATCH	✗	✗	Update resource
DELETE	✗	✓	Delete resource

3. Status Codes

SKILL.md on GitHub

Details

Repository: github.com/charon-fan/agent-playbook
Categories: Backend & APIs, AI & Agent Building
First seen: May 16, 2026