Source: wshobson/agents · Maintainer: community: Seth Hobson · License: MIT · Checked: 24 October 2026
What is the api-design-principles skill?
The api-design-principles skill gives a coding agent a set of rules for designing REST and GraphQL APIs: resource naming, HTTP method semantics, status codes, pagination, versioning and error formats. It is for developers who ask Claude Code, Codex or Cursor to design or review an API and want the result to follow consistent conventions instead of whatever the model guesses.
It lives in the backend-development plugin of wshobson/agents, a large catalog whose README says it holds 94 plugins, 202 agents, 185 skills and 105 commands for Claude Code, Codex, Cursor and other tools. The skill's description reads: "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."
As of 24 October 2026, its skills.sh page listed 30.3K installs (snapshot, 24 October 2026).
What does it do?
The skill is model-invoked: the agent loads it when your request matches the description, such as designing a new API, reviewing an OpenAPI spec or writing team API standards. The SKILL.md lists more triggers, including refactoring an API for usability, migrating from REST to GraphQL, and optimizing an API for mobile or third-party clients.
The SKILL.md itself is short. It covers:
- REST basics. Resources are plural nouns, HTTP methods carry the action, and
GET,PUTandDELETEare idempotent. - GraphQL basics. Schema first, queries for reads, mutations for writes, subscriptions for real-time updates.
- Versioning. URL (
/api/v1/users), header and query parameter versioning, with an example of each. - Best practices. Seven rules each for REST (statelessness, correct status codes, pagination, rate limits, OpenAPI docs) and GraphQL (DataLoaders against N+1 queries, cursor pagination, the
@deprecateddirective, query complexity monitoring). - Common pitfalls. Inconsistent error formats, missing rate limits, ignoring HTTP semantics, and an API that mirrors the database schema.
The detail sits in supporting files that the agent reads only when it needs them:
| File | What it holds |
|---|---|
references/details.md |
Worked patterns: resource collections, pagination and filtering, error responses, HATEOAS, GraphQL schema and resolver design |
references/rest-best-practices.md |
URL structure, each HTTP method, filtering and sorting, offset, cursor and Link header pagination, versioning |
references/graphql-schema-design.md |
Modular schemas, interfaces and unions, Relay pagination, mutation payloads, subscriptions, scalars, directives, errors |
assets/api-design-checklist.md |
A pre-implementation review checklist, from resource design to monitoring, plus GraphQL-specific checks |
assets/rest-api-template.py |
A FastAPI starter with Pydantic models, pagination, error handling, CORS and trusted host middleware |
The checklist is the most reusable piece. It asks, for example, whether you return 429 Too Many Requests when a rate limit is hit, whether rate limit headers are included and whether an OpenAPI spec is generated.
How do you install it?
The repo README documents several install routes, including these. Pick one per tool so the skill doesn't load twice.
Just this skill. The command from skills.sh uses the skills CLI:
npx skills add https://github.com/wshobson/agents --skill api-design-principles
The README also lists GitHub CLI's skill installer, which needs GitHub CLI 2.90 or later:
gh skill install wshobson/agents api-design-principles
Both install only the skill, without the plugin's agents or commands, under the bare skill name. In Claude Code that means .claude/skills/api-design-principles/ in a project or ~/.claude/skills/api-design-principles/ for all projects, the standard Claude Code skill locations. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.
The whole backend-development plugin in Claude Code. Run these inside a session:
/plugin marketplace add wshobson/agents
/plugin install backend-development@claude-code-workflows
The plugin (version 1.3.2 in its manifest) also brings eight agents, such as backend-architect and graphql-architect, a feature-development command and eight more skills, including architecture-patterns and microservices-patterns. Plugin skills are namespaced, so this one appears as /backend-development:api-design-principles.
Codex plugin. The README gives the same pattern for Codex:
codex plugin marketplace add wshobson/agents
codex plugin add backend-development@claude-code-workflows
claude.ai. The MIT License allows copies, so you can zip the folder and upload it under Customize > Skills, as described in Anthropic's skills help article.
How do you use it?
Give the agent a concrete domain and say who the clients are. The skill has no inputs of its own, so the quality of the result depends on how much context you provide.
Example prompts (suggestions, not quotes from the repo):
Design a REST API for a bookings service: customers, rooms, reservations. Include pagination, filtering by date and a consistent error format.Review openapi.yaml against the API design checklist and list every failed item with a fix.We have a REST API for orders. Sketch the GraphQL schema we would migrate to, with Relay pagination and input/payload mutations.Write our team's API design standards as a Markdown doc: naming, versioning, errors, rate limits.Scaffold a FastAPI service for products from the skill's REST template and tighten the CORS settings for api.example.com.
Requirements: none beyond your agent. The skill has no dependencies and no API keys. If you use the template, you need Python with FastAPI and Pydantic installed in your own project.
Tips and limits
- Python first. The REST examples and the template use FastAPI, and the GraphQL resolver examples are Python too. The agent can translate the rules to other stacks, but expect Python when it reaches for an example.
- Fix the template's open defaults.
rest-api-template.pyships withallow_origins=["*"]andallowed_hosts=["*"], each marked with a TODO to restrict in production. Ask the agent to set real values before you deploy. - One versioning recommendation. The REST reference labels URL versioning "Recommended" and lists header and query parameter versioning as alternatives. If your team already uses header versioning, say so in the prompt.
- No scripts. The skill runs nothing and writes no files of its own. The agent writes code only when you ask it to.
- Security audits. On 24 October 2026 the skills.sh page showed Pass from Gen Agent Trust Hub, Socket and Snyk.
- License. MIT, from the repo's LICENSE file (copyright 2024 Seth Hobson). You can copy and change it as long as you keep the notice.
Save it in your Kipt library
In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Kipt reads the SKILL.md along with the references and assets folders; for a link to a repo with many skills it shows a list to pick from. It saves the skill as Markdown in your own private GitHub repo, and every skill you keep there installs into Claude Code or Codex with one command:
npx skills add https://github.com/<you>/<repo>.git --all -g
Kipt is not affiliated with Seth Hobson or wshobson/agents.
Similar skills
- API design skill: Addy Osmani's single-file skill on stable interfaces, idempotency keys and additive changes, with TypeScript examples.
- Architecture patterns skill: the sibling skill in the same plugin, for Clean Architecture, hexagonal architecture and DDD behind the API.
- Postgres best practices skill: for the database your API reads from.
- Improve codebase architecture skill: for reshaping the modules an API sits on.