When should I use this skill?

Use it when designing new REST or GraphQL APIs, refactoring existing APIs, setting team standards, reviewing specifications before implementation, migrating between paradigms, writing developer documentation, or optimizing for specific use cases.

When should I not use this skill?

Do not use it when you only need implementation guidance for a specific framework, when doing infrastructure-only work without API contracts, or when you cannot change or version public interfaces.

What does the skill produce?

It walks through defining consumers and use cases, modeling resources, specifying errors, versioning, pagination, and auth, then validating with examples and checking consistency.

API Design Principles

SkillMedia

The api-design-principles skill guides an AI agent through designing or reviewing REST and GraphQL APIs. It covers defining consumers and use cases, modeling resources, and specifying errors, versioning, pagination, and auth. The skill validates designs with examples and checks consistency using a playbook of patterns, checklists, and templates.

Use API Design Principles in Claude, ChatGPT or Ahel Desktop

Free. Sign in, add API Design Principles and connect your AI. About a minute.

Claude ChatGPT Ahel Desktop

Also: Claude Code · Cursor · Codex

Then ask your AI: use the API Design Principles skill

Details

Instructions available. Your AI can read the instructions. Execution depends on the setup they require.

Account requirements not reviewed. Check the skill instructions before use; ahel provides instructions and does not run this skill.

No other account needed.

Confirm the task matches the skill scope, such as designing or reviewing a REST or GraphQL API.

API Design PrinciplesStart free

What your AI can do with it

Design new REST or GraphQL APIs from consumers and use cases
Refactor existing APIs for better usability
Establish API design standards for a team
Review API specifications before implementation
Specify errors, versioning, pagination, and auth strategy
Validate designs with examples and check consistency

Getting started

Confirm the task matches the skill scope, such as designing or reviewing a REST or GraphQL API.
Provide the consumers, use cases, and constraints for the API.
Choose the API style and model the resources or types.
Specify errors, versioning, pagination, and auth strategy.
Validate the design with examples and review it for consistency.

What this skill tells your AI

The instructions your AI receives, as published by sickn33/agentic-awesome-skills in skills/api-design-principles/SKILL.md and read by ahel’s review.

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.md for 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.

Signals

GitHub stars: 47k
Forks: 7k
Last commit: Sep 2026

Others that do the same job

api-design-principles
Skill · lingxling

Questions

When should I use this skill?: Use it when designing new REST or GraphQL APIs, refactoring existing APIs, setting team standards, reviewing specifications before implementation, migrating between paradigms, writing developer documentation, or optimizing for specific use cases.
When should I not use this skill?: Do not use it when you only need implementation guidance for a specific framework, when doing infrastructure-only work without API contracts, or when you cannot change or version public interfaces.
What does the skill produce?: It walks through defining consumers and use cases, modeling resources, specifying errors, versioning, pagination, and auth, then validating with examples and checking consistency.

Advanced

Item type: skill
Key: api-design-principles-sickn33
Source: github.com/sickn33/agentic-awesome-skills

github.com/sickn33/agentic-awesome-skills