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 an agent skill that makes your AI coding agent follow a structured method when you ask it to design or review an API, covering both REST and GraphQL. This guide explains what the skill does, how to install it, how to trigger it with plain requests, and what to watch out for. By the end you will be able to add the skill, ask for help with an API design, and know what the agent should be checking.
API Design Principlessickn33/agentic-awesome-skills · MIT Download the skill Quick start
- 1Download the ZIP. Get the api-design-principles ZIP from the page where you found this guide.
- 2Unzip into a skills folder. Place the api-design-principles folder in ~/.claude/skills/ for personal use or .claude/skills/ inside a project.
- 3Or upload in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill.
- 4Describe your API task. Ask in plain language, naming the consumers, the API style you are considering and any constraints.
- 5Answer the clarifying questions. The agent should ask about consumers, use cases and constraints before choosing a design. Answer them so it can plan errors, versioning, pagination and auth.
- 6Review against the checklist. Check the resulting design against assets/api-design-checklist.md and your own testing before implementing.
What is an agent skill and what does this one do?
An agent skill is a folder of instructions and reference files that an AI agent can load when a task matches the skill's description. This one is named api-design-principles and is built around the SKILL.md file.
When the skill applies, the agent works in four steps: define who will consume the API and why, choose REST or GraphQL and model resources or types, specify errors, versioning, pagination and authentication, then validate the design with examples and review it for consistency.
- Clarifies consumers, use cases and constraints first
- Chooses an API style and models resources or types
- Plans error handling, versioning, pagination and auth
- Checks the design with examples and a consistency review
What files does the skill include?
The skill bundles reference material the agent can draw on. Nothing has to be run to get the guidance; the agent reads these files as needed.
- SKILL.md: the main instructions and when to use the skill
- resources/implementation-playbook.md: detailed patterns, checklists and templates
- references/rest-best-practices.md: REST URL structure, methods and status codes
- references/graphql-schema-design.md: GraphQL schema organization and type design patterns
- assets/api-design-checklist.md: a pre-implementation review checklist
- assets/rest-api-template.py: a sample FastAPI template
How do you install the skill?
Download the ZIP for this skill from the page where you found this guide. Unzip it so the api-design-principles folder sits in one of the locations below.
For a personal setup, unzip into ~/.claude/skills/. For a single project, unzip into the project's .claude/skills/ folder. In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/api-design-principles
- Project: .claude/skills/api-design-principles inside your repository
- Claude apps: Settings → Capabilities → Skills, then upload
How do you trigger the skill with a natural request?
You do not need a special command. Describe the API task in plain language and mention what you are working on. The skill is meant for designing new REST or GraphQL APIs, refactoring existing ones, setting team standards, reviewing specifications before implementation, migrating between paradigms, writing developer-facing API docs, and optimizing for mobile or third-party use.
Give the agent context: who calls the API, what they need to do, and what cannot change. The skill asks for this first and will stop to ask if required inputs are missing.
- Design a REST API for a booking system used by mobile clients and a partner integration.
- Review this OpenAPI spec for consistency before we implement it.
- We want to move our orders API to GraphQL. Which parts should change first?
- Create a shared API design checklist for our team and check this endpoint against it.
What does a good result look like?
Expect the agent to ask about consumers and constraints before recommending a design, then to address errors, versioning, pagination and authentication explicitly. For REST, it should follow the conventions in the reference notes: plural nouns, shallow nesting, correct HTTP methods and status codes. For GraphQL, it should cover non-null types, modular schema structure and authorization.
Review the output against the checklist yourself. The skill's own limitations say the output is not a substitute for testing or expert review.
What about the sample FastAPI template?
The file assets/rest-api-template.py is a teaching mock. It runs in memory only, with no persistence, no authentication and no password storage. Use it to study the shape of an API, not as a starting point for production.
To run the template you need Python and FastAPI. Its imports imply pydantic and email-validator are also needed. The skill itself does not cover framework-specific implementation.
- Requires Python and FastAPI only if you want to run the template
- Imports imply pydantic and email-validator
What are the safety notes?
The skill does not run scripts and does not use the network, according to its metadata. It is made of instructions and reference files only.
Its own guidance says not to use it for infrastructure-only work with no API contracts, or for public interfaces you cannot change or version. Its GraphQL notes also state that declaring an @auth directive does not enforce access; you must implement authorization server-side.
- Runs scripts: no
- Uses network: no
- Do not copy the sample template into production
What people use it for
- Planning a new REST API for a mobile app and a third-party integration
- Reviewing an existing API spec for naming and status code consistency
- Writing a shared API design standard and review checklist for a team
- Assessing whether a REST API should move to GraphQL and which parts to change first
Frequently asked questions
How do I install the api-design-principles skill?
Download the ZIP from the page where you found this guide and unzip it into ~/.claude/skills/ for personal use or into .claude/skills/ inside a project. In the Claude apps, you can upload it under Settings → Capabilities → Skills.
Is the api-design-principles skill free?
The skill is published under the MIT licence, as listed on this page. Check the licence file in the source repository for the full terms.
What do I need to run this skill?
The skill itself runs no scripts and uses no network. You only need Python and FastAPI if you want to run the sample template, which also imports pydantic and email-validator.
Can this skill write production API code?
Not from the sample. The template is an in-memory teaching mock with no persistence, authentication or password storage. The skill focuses on design principles and says it does not cover framework-specific implementation.
Does this skill support GraphQL as well as REST?
Yes. It includes reference notes on GraphQL schema design covering modular structure and type patterns, alongside REST best practices and a design checklist.
When should I not use this skill?
Avoid it for framework-specific implementation questions, infrastructure-only work with no API contracts, or public interfaces you cannot change or version.
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
This skill suits developers planning a new REST or GraphQL API, teams that want shared design standards and a review checklist, and engineers refactoring an API for better usability. Pick something else if you need framework-specific implementation help, infrastructure-only work, or a ready-to-deploy backend, since the sample template is only a teaching mock.
Download the skill