api-design-principles
Teaches your agent to create APIs following best principles. This results in APIs that are easy to use, grow with the system, and please other developers.
What it does
This tool helps you create and improve the design of APIs (interfaces for software to communicate), whether they are REST or GraphQL. The goal is to make them user-friendly, efficient, and long-lasting.
When to use it
- ✓When designing a new API.
- ✓When improving an existing API.
- ✓When setting API design standards for your team.
Example of what to ask your AI
“How can I design a REST API to efficiently manage users?”
Want more? Open the sections below.
How to use
The easiest way: copy the message below and paste it into Claude, ChatGPT, Cursor or any AI. It reads the skill and follows the instructions.
Skill link
Ready-to-paste message
How it works
The tool guides you through steps like understanding who will use the API, choosing the right API type, defining how errors and versions will be handled, and validating everything with examples.
Installation
Easiest way: copy the skill link and paste it into Claude, ChatGPT or Cursor asking it to follow the instructions.
In the terminal (Claude Code, Codex, Cursor), in your project folder:
npx skills add sickn33/agentic-awesome-skills --skill api-design-principlesOr download just the file:
curl -L https://raw.githubusercontent.com/sickn33/agentic-awesome-skills/main/plugins/agentic-awesome-skills-claude/skills/api-design-principles/SKILL.md -o SKILL.mdTechnical content (original SKILL.md)
Original text by the author, straight from GitHub.
API Design Principles
Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.
Use this skill when
- Designing new REST or GraphQL APIs
- Refactoring existing APIs for better usability
- Establishing API design standards for your team
- Reviewing API specifications before implementation
- Migrating between API paradigms (REST to GraphQL, etc.)
- Creating developer-friendly API documentation
- Optimizing APIs for specific use cases (mobile, third-party integrations)
Do not use this skill when
- You only need implementation guidance for a specific framework
- You are doing infrastructure-only work without API contracts
- You cannot change or version public interfaces
Instructions
- Define consumers, use cases, and constraints.
- Choose API style and model resources or types.
- Specify errors, versioning, pagination, and auth strategy.
- Validate with examples and review for consistency.
Refer to resources/implementation-playbook.md for detailed patterns, checklists, and templates.
Resources
resources/implementation-playbook.mdfor detailed patterns, checklists, and templates.
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
FAQ
What is an API?
An API is like a menu in a restaurant. It tells software what it can order and how to order it, without needing to know how the kitchen works.
What's the difference between REST and GraphQL?
REST is like ordering specific dishes from the menu, while GraphQL allows you to request exactly the ingredients you want, all at once.
Do I need to know how to code to use this?
You don't need to be an experienced programmer. The tool is designed to help plan the API design, even if you won't be coding it directly.
Details
Original description by the author
Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.
Popularity
- GitHub stars
- 48k
- Ranking position
- #2152
- License
- MIT
- Updated
- 10/15/2026
Comments
- …
More skills from this repository
00-andruia-consultant
Helps your agent start or improve AI projects. It analyzes code, suggests tools, and creates action plans in Spanish.
sickn33/agentic-awesome-skills
007
Lets your agent perform security audits and threat modeling. It's useful for protecting projects against attacks and vulnerabilities.
sickn33/agentic-awesome-skills
10-andruia-skill-smith
Helps your agent create or improve AI tools. It defines how tools work, writes documentation, and validates the structure.
sickn33/agentic-awesome-skills
20-andruia-niche-intelligence
Lets your agent create a summary about a specific industry. It's useful for understanding the context, rules, usage patterns, and risks of a project, using reliable sources.
sickn33/agentic-awesome-skills
Similar skills
accessibility
Helps your agent create interfaces that everyone can use. Ensures websites and apps work well for people with disabilities, like those who are blind or have reduced mobility.
affaan-m/ECC
design-system
Helps your agent create a design system from existing code. It extracts visual information and checks for consistency, generating a report and an interactive preview.
affaan-m/ECC
liquid-glass-design
Helps your agent create iOS user interfaces with a 'Liquid Glass' effect. Allows adding dynamic and interactive visual effects in SwiftUI and UIKit.
affaan-m/ECC