How to use the API Designer agent skill: setup and examples

What the api-designer skill makes the agent do

Once installed, the agent follows a fixed sequence when you ask it to design an API: it analyzes the domain, models resources, defines endpoints, writes an OpenAPI 3.1 specification, validates and mocks it, and plans versioning and deprecation.

The skill also loads reference notes on REST patterns, versioning, pagination, error handling (RFC 7807) and OpenAPI, so the output follows consistent conventions such as resource-oriented URIs and a single error format.

• Resource modeling and relationships
• Endpoint URIs, HTTP methods and request/response schemas
• An OpenAPI 3.1 specification in YAML
• Pagination, error and versioning guidance

How to install the api-designer skill

Download the ZIP file for skills/api-designer from our page. Then choose one of the two installation options below.

For a personal install, unzip the file into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. Alternatively, in the Claude apps go to Settings → Capabilities → Skills and upload the ZIP there.

• Personal: ~/.claude/skills/
• Project only: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

How to trigger the skill with natural requests

You do not need a special command. The skill is meant to be invoked when your request involves designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture. Requests that mention resource modeling, versioning strategies, pagination patterns or error handling standards are the best matches.

Give the agent context: the business domain, the main entities, who the clients are and any authentication needs. The more concrete the domain, the more specific the resulting design.

• "Design a REST API for a library system with books, members and loans."
• "Write an OpenAPI 3.1 spec for our order service and include cursor pagination."
• "Plan versioning and deprecation for our existing customers API."
• "Standardise error responses across our services using RFC 7807."

What the skill needs and the safety notes

The design work itself needs nothing beyond the skill. The suggested validation and mock commands use Node.js and npx to run @redocly/cli and @stoplight/prism-cli, so Node.js must be installed if you want to run those checks.

The skill does not run scripts and does not use the network, according to its listing. Review the output before you rely on it, because the specification is a draft that a developer should check.

• Required for validation and mocking: Node.js with npx
• Runs scripts: no
• Uses network: no
• Output still needs developer review

Example workflow: from request to validated spec

A typical session starts with a domain description. The agent works through its sequence and produces a resource model, endpoint list and an OpenAPI 3.1 file. You can then ask it to lint the file with the Redocly command and to start a Prism mock server so clients can test against the contract.

Ask for the error catalog and versioning plan in the same request so the design stays consistent. The skill's output checklist expects a resource model, endpoint specifications, authentication flows, an error catalog, pagination patterns and a versioning strategy.

Tips for better results

Name the conventions you want, such as snake_case or camelCase, because the skill asks you to pick one and apply it everywhere. State your pagination preference (cursor, offset or keyset) if you have one.

Use the reference notes as a checklist when you review the output. The skill's rules say to avoid verbs in URIs, return consistent response structures and document authentication and rate limiting.

• State your naming convention up front
• Specify pagination and authentication needs
• Review rate limiting and deprecation policy before sign-off