API Design Principles Skill for Claude Code: REST and GraphQL Design Rules

Gives your assistant REST and GraphQL API design rules for naming, versioning, pagination, errors and documentation.

Installs: 30.9K; on skills.sh
Stars: 42.1K; on GitHub
Files: 5; besides SKILL.md
Updated: Oct 2026; last repo commit

This skill gives your assistant a set of REST and GraphQL design rules to use when it designs or reviews an API. It covers resource naming, HTTP method meaning, versioning, pagination, error formats, rate limits and documentation.

SKILL.md is a short summary. Longer patterns with worked examples sit in references/details.md, which the agent reads when the summary is not enough.

Good for

Backend developers designing a new REST or GraphQL API
Reviewers checking an API spec before implementation
Teams writing API standards or moving from REST to GraphQL

Install api-design-principles

Claude Code

Copy this prompt.

Install the api-design-principles skill in Claude Code. Run this command:

npx skills add https://github.com/wshobson/agents --skill api-design-principles

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards.

Sections in SKILL.md

When to Use This Skill
Core Concepts
1. RESTful Design Principles
2. GraphQL Design Principles
3. API Versioning Strategies
Detailed patterns and worked examples
Best Practices
REST APIs
GraphQL APIs
Common Pitfalls

Key facts

Author: Seth Hobson (GitHub: wshobson)
License: MIT
Installs on skills.sh: 30,892 (Nov 2, 2026)
GitHub stars: 42,081 for the whole repo (Nov 2, 2026)
What installs: 6 files including SKILL.md: 3 reference guides, an API design checklist and a FastAPI template
Part of: The backend-development plugin, which also holds 8 agents, 1 command and 8 other skills
Skill-only install: The README says the skills CLI or gh skill installs one skill without the plugin's agents, commands or hooks
Last commit: Oct 30, 2026 (repo)

What it includes

Seven situations: new APIs, refactors, standards, reviews and migrations
Designing new REST or GraphQL APIs, refactoring for usability, setting team standards, reviewing specs before building, moving between REST and GraphQL, writing docs and tuning for mobile or third parties.
Try: “Review this OpenAPI spec for naming and pagination problems.”
When to use
Resources are nouns; HTTP methods carry the action
GET reads, POST creates, PUT replaces, PATCH updates part of a resource, DELETE removes. URLs show resource hierarchy and names stay consistent.
RESTful design
Schema first: types, queries, mutations, subscriptions
Clients ask for exactly what they need from a single typed endpoint with introspection.
GraphQL design
URL, header or query parameter
Shows /api/v1/users, an Accept header with version=1, and /api/users?version=1.
Versioning strategies
references/details.md holds worked examples
REST: resource collections, pagination and filtering, error handling and status codes, HATEOAS. GraphQL: schema design, resolvers and DataLoader for N+1 queries.
Read · Detailed patterns
Seven rules from plural nouns to OpenAPI docs
Plural collections, stateless requests, correct status codes, versioning from day one, pagination, rate limiting and documentation.
REST best practices
Seven rules from schema-first to monitoring
Design the schema before resolvers, avoid N+1 with DataLoaders, validate input, return structured errors, use cursor pagination, deprecate with @deprecated and track query cost.
GraphQL best practices
Seven mistakes such as missing rate limits and breaking changes
Over- and under-fetching, breaking changes, inconsistent errors, missing rate limits, poor docs, ignoring HTTP semantics and mirroring the database schema.
Common pitfalls

From the official docs

Questions

What does the api-design-principles skill do?

It gives your assistant REST and GraphQL design rules to apply when it designs or reviews an API. It covers resource naming, HTTP methods, versioning, pagination, errors, rate limiting and documentation.

How do I install it?

Use the install box above. It installs only this skill. The wshobson/agents README also describes a plugin route, but that adds agents and commands you may not need.

Does it cover GraphQL as well as REST?

Yes. It has GraphQL design principles, best practices and a longer reference on schema design, resolvers, pagination, errors and N+1 solutions.

Does it write code for me?

It is guidance. The folder includes a FastAPI template and a design checklist, but SKILL.md points only to references/details.md for deeper patterns, so ask for the template if you want it.

What else is in the backend-development plugin?

The plugin folder holds 9 skills, 8 agents and a feature-development command. It covers architecture, CQRS, event sourcing, microservices, sagas and Temporal workflows.

Is it safe?

It is guidance text plus reference files, and SKILL.md does not tell the agent to run any script. The folder holds a FastAPI template file, so read it before you copy code from it.

Does it work in the Claude app?

The repo documents no Claude app route. The README covers Claude Code, Codex, Cursor and skills-only installs.

Information

updated Nov 2, 2026

Repository: wshobson/agents
Folder: plugins/backend-development/skills/api-design-principles

wshobson/agents skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 7

api-design-principles SKILL.md · github.com
wshobson/agents README · github.com
backend-development plugin.json · github.com
wshobson/agents LICENSE · github.com
api-design-principles on skills.sh · skills.sh
api-design-principles details.md · github.com
graphql-schema-design.md · github.com