Skip to content
Get packs

Guide · Agent skill

How to use the API Design Principles agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The api-design-principles skill is a set of API design guidance packaged for an AI coding agent. Once it is installed, the agent follows established rules for designing web APIs, the interfaces that let apps talk to servers. This guide explains what the skill does, how to install it, how to trigger it with plain requests, and what to watch for before you use its template in real code.

API Design Principleswshobson/agents · MIT

Quick start

  1. 1Download the ZIP. Get the api-design-principles ZIP from this skill's page on the directory.
  2. 2Unzip into a skills folder. Extract it to ~/.claude/skills/ for personal use, or to a project's .claude/skills/ folder for one project.
  3. 3Or upload in the Claude apps. Go to Settings → Capabilities → Skills and upload the skill there.
  4. 4Describe your API task. Ask for help designing, reviewing or standardizing an API in plain language.
  5. 5Check against the checklist. Ask the agent to review your design against assets/api-design-checklist.md.
  6. 6Adapt the template carefully. If you run the FastAPI template, fix the CORS and TrustedHost settings first.

What the skill makes the agent do

An agent skill is a folder of instructions and reference files that an AI agent loads when a task matches the skill's description. This skill covers REST and GraphQL design. When it applies, the agent works from its rules rather than general habits.

For REST, the skill covers conventions such as plural resource names, correct HTTP methods and status codes, pagination, and versioning. For GraphQL, it covers schema practices such as avoiding N+1 queries with DataLoaders and using cursor-based pagination.

  • Resource names are nouns and collections are plural, such as /users rather than /user.
  • HTTP methods carry the action: GET to retrieve, POST to create, PUT to replace, PATCH for partial updates, DELETE to remove.
  • Versioning options include URL, header and query parameter styles.
  • The skill can offer a starter FastAPI template with pagination, filtering, and error handling as a reference.

Install the api-design-principles skill

Download the ZIP from the skill's page on this directory and unzip it. For a personal setup, place the folder in ~/.claude/skills/. To limit it to one project, place it in that project's .claude/skills/ folder.

In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

  • Personal install: ~/.claude/skills/api-design-principles/
  • Project install: .claude/skills/api-design-principles/ inside your project

Trigger the skill with natural requests

You do not need a special command. The skill is meant to load when your request matches its description: designing new APIs, reviewing API specifications, or establishing API design standards. Describe the task in plain language and name the style you use if it matters.

Be specific about the stage of work. A request to review a draft spec gets different output than a request to design an endpoint from scratch.

  • Design a REST API for a library system with users, books and loans. Use the api-design-principles guidance.
  • Review this OpenAPI spec against REST conventions and list problems with the status codes and naming.
  • Our team needs API standards for pagination and error formats. Draft a short standard.
  • I am moving our REST endpoints to GraphQL. What trade-offs should I weigh?

Use the checklist and template

The assets folder includes a design checklist covering resource design, HTTP methods, status codes and pagination. Ask the agent to run an API design through it before implementation.

The rest-api-template.py file is a reference FastAPI template. Running it requires Python and FastAPI/Pydantic. The skill itself does not need API keys or accounts.

  • Checklist: assets/api-design-checklist.md
  • Template: assets/rest-api-template.py
  • Reference patterns: references/rest-best-practices.md, references/graphql-schema-design.md and references/details.md

Safety notes before you deploy

The skill does not run scripts and does not use the network. The template is a different matter: its CORS and TrustedHost settings allow all origins and hosts, and this is marked as a TODO in the code.

Restrict those settings before any real deployment. Treat the template as a starting point to read and adapt, not a finished service.

  • Set CORS to the specific origins your clients use.
  • Limit TrustedHost to your actual hostnames.
  • The skill gives design guidance, not a deployable service.

What people use it for

  • Designing a new REST API with resource-oriented endpoints and nested collections.
  • Reviewing an existing OpenAPI spec for naming, status code and pagination problems.
  • Setting shared API standards for a backend team.
  • Planning a migration from REST to GraphQL with a checklist of trade-offs.
  • Building a reference FastAPI service with pagination, filtering and error handling.

Frequently asked questions

Is the api-design-principles skill free?

The skill is published under the MIT licence, as listed on this page. The source does not mention pricing, so check the repository for the licence text before you rely on it.

What do I need to use it?

The skill itself needs no API keys or accounts. If you run the template script, you need Python and FastAPI/Pydantic.

How do I install an agent skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. In the Claude apps, you can upload it under Settings → Capabilities → Skills.

Does the skill run code or access the internet?

According to this listing, it runs no scripts and uses no network. The FastAPI template is separate code you would run yourself.

Is the FastAPI template ready for production?

No. Its CORS and TrustedHost settings allow all origins and hosts and are marked TODO. Restrict them before real deployment.

Can it help with GraphQL as well as REST?

Yes. The skill covers GraphQL schema practices such as avoiding N+1 queries with DataLoaders, using cursor-based pagination, and structuring mutation errors.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Choose this skill if you are a backend developer designing a REST or GraphQL API, or a team that wants shared API standards and a checklist before building. Skip it if you need a finished, deployable API, since it gives design guidance rather than a service, and do not ship the template without restricting its CORS and TrustedHost settings.

Download the skill