Skip to content
Get packs

API Designer

Guides an agent to design REST/GraphQL APIs, OpenAPI 3.1 specs, versioning, pagination and errors

Source Download skill
Repository
Jeffallan/claude-skills
Stars
12,176
Licence
MIT
Files
6 files

What it does

Once installed, the agent acts like a senior API architect when you ask it to design an API. It works through a set sequence: understand the domain, model resources, define endpoints, write an OpenAPI 3.1 specification, check it with a linter and mock server, and plan versioning and deprecation. It also loads reference notes on REST patterns, pagination, error formats (RFC 7807), and OpenAPI so its output follows consistent conventions.

Great for

  • Backend developers planning a new REST or GraphQL API before writing code
  • Teams that want an OpenAPI contract drafted and validated before implementation
  • Engineers standardising pagination, error responses and versioning across services

Skip it if

  • Writing the actual server implementation: the skill focuses on design and specification, not code generation for a framework
  • Non-technical users looking for a finished product: the output is technical specifications that still need a developer to review
  • Projects needing GraphQL schema depth: the description mentions GraphQL, but the included reference files cover REST, OpenAPI, versioning, pagination and errors rather than GraphQL schema design

Try asking

  • “Design a REST API for a library system with books, members and loans, and produce an OpenAPI 3.1 spec”
  • “Review my existing endpoints and suggest a versioning and deprecation plan that avoids breaking clients”
  • “Add cursor-based pagination and RFC 7807 error responses to my orders API”
  • “Create a mock server setup and lint command so I can test the contract before building”
Step-by-step guide: how to use API DesignerInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 6 original files, the MIT licence and an attribution note.

    api-designer.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip api-designer.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip api-designer.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Give the agent your data model and client needs up front; the workflow starts with domain analysis and gets better with real context.
  • Ask it to run the Redocly lint and Prism mock commands yourself, since the skill suggests them but the agent must execute them in your environment.
  • Review the generated spec for auth, rate limits and error codes, which the skill's own rules require but which depend on your actual system.

What's inside

  • references/error-handling.md
  • references/openapi.md
  • references/pagination.md
  • references/rest-patterns.md
  • references/versioning.md
  • SKILL.md

Redistributed unmodified from Jeffallan/claude-skills under the MIT licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.