New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

API Design Principles

by aipoch in aipoch/medical-research-skills

Principles and checklists for designing and reviewing REST and GraphQL APIs; use when defining or evaluating API contracts (endpoints/schemas), naming, error models, pagination, versioning, and REST…

MITAuto-check passedBackend & APIs

Install API Design Principles

skills CLI
$ npx skills add aipoch/medical-research-skills --skill api-design-principles -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install aipoch/medical-research-skills api-design-principles --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/aipoch/medical-research-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/scientific-skills/Other/api-design-principles .claude/skills/api-design-principles && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
api-design-principles
GitHub stars
2k
Token cost
~1.7k tokens
SKILL.md length
558 words
Files
5 (incl. references)
Skills in repo
567
Repo updated
First seen
Licence
MIT

At a glance

Principles and checklists for designing and reviewing REST and GraphQL APIs; use when defining or evaluating API contracts (endpoints/schemas), naming, error models, pagination, versioning, and REST…

  • Works in 4 steps: Clarify requirements and constraints → Choose API style and boundaries → Produce a REST contract skeleton… → …
  • Evaluating API contracts (endpoints/schemas)
  • SKILL.md covers When to Use, Key Features, Dependencies and Example Usage, plus 1 more section
  • Calls curl

What it does

API Design Principles is an agent skill from aipoch/medical-research-skills. Principles and checklists for designing and reviewing REST and GraphQL APIs; use when defining or evaluating API contracts (endpoints/schemas), naming, error models, pagination, versioning, and REST vs. GraphQL trade-offs.

Its SKILL.md is about 1.7k tokens, which your agent loads only when the skill is triggered. The skill folder holds 5 other files, including reference files (for example `api-design-principles_audit_result_v1.json`, `references/graphql.md` and `references/rest.md`).

It sits in Backend & APIs, covering API design and GraphQL. It works with GraphQL. The repository describes itself as: Hundreds of agent skills for medical research, including protocol design, data analysis, evidence insights, and academic writing. The licence is MIT.

When your agent uses it

  • Evaluating API contracts (endpoints/schemas)
  • Tasks that involve API design
  • Tasks that involve GraphQL

Example prompts

  • “Use the api-design-principles skill to principle and checklists for designing and reviewing REST and GraphQL APIs; use when defining or evaluating…”
  • “/api-design-principles”

Workflow steps

4 steps, taken from the step headings in SKILL.md.

  1. Clarify requirements and constraints
  2. Choose API style and boundaries
  3. Produce a REST contract skeleton (runnable examples)
  4. Run the review checklist

What it can do on your machine

Read from SKILL.md and the folder at commit 686e09d. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • curl

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use curl, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

API Design Principles loads about 1.7k tokens when it runs, and up to ~3.4k if it reads all its reference files. Until then it costs about 61 tokens; SKILL.md has 558 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~61
When it runs · the whole SKILL.md, loaded when a task matches
~1.7k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~3.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from aipoch/medical-research-skills at commit 686e09d, republished under its MIT licence (© aipoch). 558 words, ~1,693 tokens.

Download SKILL.mdSave it as .claude/skills/api-design-principles/SKILL.md (or your agent's skills folder). This skill also uses 4 other files; get the full folder from GitHub.
name
api-design-principles
description
Principles and checklists for designing and reviewing REST and GraphQL APIs; use when defining or evaluating API contracts (endpoints/schemas), naming, error models, pagination, versioning, and REST vs. GraphQL trade-offs.
license
MIT
author
AIPOCH

Source: https://github.com/aipoch/medical-research-skills

API Design Principles

When to Use

  • Designing a new REST API contract for CRUD-style resources and you need consistent resource modeling, naming, and HTTP semantics.
  • Designing a new GraphQL schema for multiple clients with different data shapes and you need clear type/field ownership and safe evolution.
  • Reviewing an existing API (REST or GraphQL) to identify inconsistencies in naming, error handling, pagination/filtering, or versioning/deprecation.
  • Deciding between REST vs. GraphQL (or defining boundaries when mixing both) and documenting trade-offs and constraints.
  • Standardizing cross-cutting concerns (authn/authz, rate limiting, observability, long-running operations, idempotency) across multiple services.

Key Features

  • End-to-end workflow for API design/review: requirements → style choice → domain modeling → operations → cross-cutting concerns → deliverables.
  • REST guidance: resource-oriented modeling, stable identifiers, relationship patterns, and correct HTTP verb usage.
  • GraphQL guidance: schema/type modeling, Query vs. Mutation separation, input types for writes, and explicit side-effect handling.
  • Cross-cutting design patterns: consistent error model, pagination/filtering/sorting, versioning and deprecation strategy, and operational concerns.
  • Review checklist to validate completeness, highlight risks/gaps, and produce actionable follow-ups.

Dependencies

  • None (documentation-only skill).
  • Reference documents:
    • references/rest.md
    • references/graphql.md
    • references/review-checklist.md

Example Usage

Goal

Design (or review) an API for managing Projects and Tasks, and produce a contract with examples, error model, pagination, and a checklist summary.

Step 1: Clarify requirements and constraints
  • Consumers: Web app + mobile app + internal admin.
  • Constraints: p95 latency < 200ms for list endpoints; PII present; audit logging required.
  • Core use cases: list projects, view project, create task, update task status, search tasks by status/assignee.
Step 2: Choose API style and boundaries
  • Choose REST for resource-oriented CRUD with cacheable reads and straightforward endpoints.
  • If GraphQL is later introduced for client-specific views, define boundaries (e.g., GraphQL for read aggregation; REST remains source-of-truth for writes).
Step 3: Produce a REST contract skeleton (runnable examples)

Base URL

  • https://api.example.com/v1

Resources

  • projects
  • tasks (scoped under a project)

Endpoints

  • GET /v1/projects
  • POST /v1/projects
  • GET /v1/projects/{projectId}
  • GET /v1/projects/{projectId}/tasks
  • POST /v1/projects/{projectId}/tasks
  • PATCH /v1/projects/{projectId}/tasks/{taskId}
List projects (pagination + filtering)

Request

bash
curl -sS -X GET "https://api.example.com/v1/projects?limit=20&cursor=eyJpZCI6IjEwMCJ9&sort=createdAt:desc" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Response (200)

json
{
  "data": [
    {
      "id": "proj_123",
      "name": "Roadmap 2026",
      "createdAt": "2026-01-10T12:00:00Z"
    }
  ],
  "page": {
    "limit": 20,
    "nextCursor": "eyJpZCI6InByb2pfMTIzIn0="
  }
}
Create a task (idempotency)

Request

bash
curl -sS -X POST "https://api.example.com/v1/projects/proj_123/tasks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: 2b7b1a2e-7f2b-4c2a-9c2b-0b3b7c9d1a11" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Draft API spec",
    "assigneeId": "user_42",
    "dueAt": "2026-03-01T00:00:00Z"
  }'

Response (201)

json
{
  "data": {
    "id": "task_999",
    "projectId": "proj_123",
    "title": "Draft API spec",
    "status": "OPEN",
    "assigneeId": "user_42",
    "dueAt": "2026-03-01T00:00:00Z",
    "createdAt": "2026-02-25T09:00:00Z"
  }
}
Error model example

Response (409)

json
{
  "error": {
    "code": "CONFLICT",
    "message": "A task with the same title already exists in this project.",
    "details": {
      "field": "title",
      "reason": "DUPLICATE"
    },
    "requestId": "req_01HTZQ8K7Y9M2A3B4C5D6E7F8G"
  }
}
Show full SKILL.md (229 more words)Show less
Step 4: Run the review checklist

Use references/review-checklist.md to validate:

  • Naming consistency (resources, fields, enums)
  • HTTP semantics and status codes
  • Pagination/filtering/sorting rules
  • Error model completeness and stability
  • Versioning/deprecation plan
  • Security and observability requirements
Expected deliverable format (save to outputs/)
  • API style choice + trade-offs
  • Contract skeleton (endpoints or schema)
  • Request/response (or query/mutation) examples
  • Error model + pagination strategy
  • Checklist results + risks/gaps

Implementation Details

  1. Clarify requirements and constraints

    • Identify domain, core use cases, and consumer types (web/mobile/partners/internal).
    • Capture constraints: latency, throughput, consistency, compliance, data sensitivity.

  2. Choose API style and boundaries

    • REST: best for resource-oriented APIs, cacheable reads, and simple CRUD.
    • GraphQL: best for multiple clients with varying data shapes and frequent iteration.
    • If mixing, define boundaries to avoid overlapping responsibilities.

  3. Domain modeling

    • REST: model stable resources (nouns), stable identifiers, and relationships.
    • GraphQL: define types and field ownership; use input types for writes.

  4. Operation and behavior design

    • REST: map operations to HTTP verbs; represent actions via sub-resources or noun-based endpoints when needed.
    • GraphQL: separate Query vs. Mutation; document side effects explicitly.
    • Define idempotency (especially for creates) and patterns for long-running tasks when applicable.

  5. Cross-cutting concerns

    • Authentication/authorization
    • Error model (stable codes, actionable messages, request correlation IDs)
    • Pagination, filtering, sorting (document defaults and limits)
    • Versioning and deprecation strategy
    • Observability (logging/metrics/tracing), rate limiting
Reference guides
  • REST Principles and Patterns: references/rest.md
  • GraphQL Principles and Patterns: references/graphql.md
  • Review Checklist: references/review-checklist.md

© aipoch, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 4 other files (references) in scientific-skills/Other/api-design-principles of aipoch/medical-research-skills.

  • SKILL.md
  • api-design-principles_audit_result_v1.json
  • references/graphql.md
  • references/rest.md
  • references/review-checklist.md

Open the folder on GitHubat commit 686e09d

Compare with similar skills

API Design Principles next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

API Design Principles compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
API Design Principles this skillaipoch/medical-research-skills2k—~1.7kAutomated safety check: PassMIT
API DesignerJeffallan/claude-skills12k2 repos~2kAutomated safety check: PassMIT
Nodejs Backend Patternsever-works/ever-works15818 repos~4kAutomated safety check: PassAGPL-3.0
API Design Principlesjh941213/my-cc-harness12620 repos~3.4kAutomated safety check: PassNone
API And Interface Designdzhalaevd/Donatello1359 repos~2.6kAutomated safety check: PassApache-2.0
Designing APIsCloudAI-X/claude-workflow-v21.4k2 repos~1.2kAutomated safety check: PassMIT

Similar skills

  • API Designer

    Jeffallan/claude-skills

    Designs REST and GraphQL APIs from resource modeling to an OpenAPI 3.1 contract, with versioning, pagination and RFC 7807 error handling.

    12k GitHub starsUsed in 2 repos~2k tokens
    Backend & APIsAuto-check passed

  • Nodejs Backend Patterns

    ever-works/ever-works

    Build production-ready Node.js backend services with Express/Fastify, implementing middleware patterns, error handling, authentication, database integration, and API design best practices.

    158 GitHub starsUsed in 18 repos~4k tokens
    Backend & APIsAuto-check passed

  • API Design Principles

    jh941213/my-cc-harness

    REST 및 GraphQL API 설계 원칙 가이드. An agent skill from jh941213/my-cc-harness.

    126 GitHub starsUsed in 20 repos~3.4k tokens
    Backend & APIsAuto-check passed

  • API And Interface Design

    dzhalaevd/Donatello

    Guides stable API and interface design. An agent skill from dzhalaevd/Donatello.

    135 GitHub starsUsed in 9 repos~2.6k tokens
    Backend & APIsAuto-check passed

  • Designing APIs

    CloudAI-X/claude-workflow-v2

    Designs REST and GraphQL APIs including endpoints, error handling, versioning, and documentation.

    1.4k GitHub starsUsed in 2 repos~1.2k tokens
    Backend & APIsAuto-check passed

  • GraphQL Architect

    Jeffallan/claude-skills

    Designs GraphQL schemas and Apollo Federation graphs, with DataLoader resolvers, subscriptions, query complexity limits and caching.

    12k GitHub starsUsed in 1 repo~1.3k tokens
    Backend & APIsAuto-check passed

More from aipoch/medical-research-skills

All 567 skills in this repo

  • Academic Poster Generator

    aipoch/medical-research-skills

    Complete workflow for generating academic research posters from PDF literature; use when you need to extract paper content from PDFs and produce a LaTeX-based poster…

    2k GitHub stars~2.2k tokensUpdated 21 days ago
    Auto-check passed

  • Diagnostic Study Quality Assessment Quadas

    aipoch/medical-research-skills

    Analyzes clinical diagnostic accuracy studies for bias using the QUADAS-2 tool.

    2k GitHub stars~1.4k tokensUpdated 21 days ago
    Auto-check passed

  • Exploratory Data Analysis

    aipoch/medical-research-skills

    Perform comprehensive exploratory data analysis on scientific data files across 200+ file formats.

    2k GitHub stars~3.7k tokensUpdated 21 days ago
    Auto-check passed

  • Iso Certification

    aipoch/medical-research-skills

    A toolkit for preparing ISO 13485:2016 certification documentation for medical device QMS.

    2k GitHub stars~1.8k tokensUpdated 21 days ago
    Auto-check passed

  • Journal Skills

    aipoch/medical-research-skills

    Recommends target journals for manuscript submission by analyzing the paper topic/abstract and the journal distribution of similar PubMed literature; use when users ask for journal…

    2k GitHub stars~1.7k tokensUpdated 21 days ago
    Auto-check passed

  • Latex Posters

    aipoch/medical-research-skills

    Creates academic-poster writing packages for LaTeX using beamerposter, tikzposter, or baposter.

    2k GitHub stars~1.3k tokensUpdated 21 days ago
    Auto-check passed

Works with

Categories

Questions about API Design Principles

What does API Design Principles do?

Principles and checklists for designing and reviewing REST and GraphQL APIs; use when defining or evaluating API contracts (endpoints/schemas), naming, error models, pagination, versioning, and REST…. API Design Principles is an agent skill from aipoch/medical-research-skills. Principles and checklists for designing and reviewing REST and GraphQL APIs; use when defining or evaluating API contracts (endpoints/schemas), naming, error models, pagination, versioning, and REST vs.

When should I use API Design Principles?

API Design Principles fits situations like: evaluating API contracts (endpoints/schemas); tasks that involve API design; tasks that involve GraphQL.

How do I install API Design Principles in Claude Code?

Run `npx skills add aipoch/medical-research-skills --skill api-design-principles -a claude-code`. Or copy the skill folder (scientific-skills/Other/api-design-principles in aipoch/medical-research-skills) into .claude/skills/api-design-principles in your project. Claude Code loads it when a task matches its description.

How do I install API Design Principles in Codex?

Run `npx skills add aipoch/medical-research-skills --skill api-design-principles -a codex`. Or copy the skill folder (scientific-skills/Other/api-design-principles in aipoch/medical-research-skills) into .agents/skills/api-design-principles in your project. Codex loads it when a task matches its description.

Can I use API Design Principles in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add aipoch/medical-research-skills --skill api-design-principles -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/api-design-principles, .gemini/skills/api-design-principles, .github/skills/api-design-principles and .opencode/skills/api-design-principles in your project.

What does API Design Principles need to run?

Going by SKILL.md and its folder, API Design Principles needs the command-line tools its instructions call (curl).

Does API Design Principles access the network?

SKILL.md contains no URLs. Its commands use curl, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is API Design Principles safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does API Design Principles use?

API Design Principles is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does API Design Principles use?

About 1.7k tokens (SKILL.md is roughly 6.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 1.7k tokens, read only when the agent opens those files.

What are the alternatives to API Design Principles?

Skills that share tags, products or a category with API Design Principles: API Designer (Jeffallan/claude-skills, 12k stars), Nodejs Backend Patterns (ever-works/ever-works, 158 stars), API Design Principles (jh941213/my-cc-harness, 126 stars) and API And Interface Design (dzhalaevd/Donatello, 135 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains API Design Principles?

aipoch (a GitHub organization) maintains it in aipoch/medical-research-skills, which has 1,974 GitHub stars. The repository holds 567 skills in this directory. The repository was last updated on September 17, 2026.

Source: aipoch/medical-research-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.