Skip to content
Get packs

API Design Principles

Guides the agent to design clear, consistent REST and GraphQL APIs with sound errors, versioning and pagination

Source Download skill
Repository
sickn33/agentic-awesome-skills
Stars
49,023
Licence
MIT
Files
6 files

What it does

When you ask for help designing an API, this skill makes the agent follow a structured approach: first clarify who will use the API and why, then choose REST or GraphQL, then plan errors, versioning, pagination and authentication, and finally check the design for consistency using examples. It also brings in reference notes on REST practices, GraphQL schema design, and a design checklist. It includes a sample FastAPI template that is explicitly a teaching mock, not production code.

Great for

  • Developers planning a new REST or GraphQL API
  • Teams wanting shared API design standards and a review checklist
  • Engineers migrating from REST to GraphQL or refactoring an existing API for usability

Skip it if

  • Framework-specific implementation questions, which the skill itself says it does not cover (the agent may still need other guidance)
  • Infrastructure-only work with no API contracts, or public interfaces you cannot change or version, where the guidance may not fit
  • Copying the sample template into production: it has no persistence, authentication, or password storage and is in-memory only

Try asking

  • “Design a REST API for managing customer orders, including pagination, filtering and error responses”
  • “Review this OpenAPI spec for consistency and suggest versioning improvements”
  • “Help me decide whether GraphQL or REST fits a mobile app that needs fewer round trips”
  • “Create a developer-friendly API design checklist for our team”
Step-by-step guide: how to use API Design PrinciplesInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 6 original files, the MIT licence and an attribution note.

    api-design-principles.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip api-design-principles.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip api-design-principles.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Tell the agent who the API consumers are and what constraints apply (mobile, third parties, existing clients) so it can tailor the design
  • Treat the Python template as a learning example only; add real auth, persistence and host/CORS configuration before any real use
  • Ask for a review of an existing spec against the checklist rather than a rewrite, if you must keep backward compatibility

What's inside

  • assets/api-design-checklist.md
  • assets/rest-api-template.py
  • references/graphql-schema-design.md
  • references/rest-best-practices.md
  • resources/implementation-playbook.md
  • SKILL.md

Redistributed unmodified from sickn33/agentic-awesome-skills under the MIT licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.