Agent-Skills.md

Agent Skills: API Design

Design RESTful APIs with consistent patterns, clear conventions, and comprehensive documentation. Covers endpoint design, HTTP methods, status codes, request/response formats, pagination, filtering, versioning, authentication, and OpenAPI specifications. Use this skill when designing new APIs, reviewing API designs, or establishing API standards for a project or organization.

UncategorizedID: srstomp/pokayokay/api-design

Repository

srstomp/pokayokay
srstomp
2

Install this agent skill to your local

pnpm dlx add-skill https://github.com/srstomp/pokayokay/tree/HEAD/plugins/pokayokay/skills/api-design

Skill Files

Browse the full folder contents for api-design.

Download Skill

Loading file tree…

plugins/pokayokay/skills/api-design/SKILL.md

Skill Metadata

Name
api-design
Description
Use when designing new REST APIs, reviewing API designs, establishing API standards, designing request/response formats, pagination, versioning, authentication flows, or creating OpenAPI specifications.

API Design

Design clear, consistent, and developer-friendly REST APIs.

When NOT to Use

  • Consuming external APIs — Use api-integration for building clients to call third-party services (Stripe, Twilio, etc.)
  • Writing tests for APIs — Use testing-strategy for contract tests, integration tests, mocking strategies
  • Reviewing existing API security — Use security-audit for vulnerability scanning of live endpoints
  • Designing auth mechanisms that are the whole task — Use security-audit if reviewing, this skill if designing from scratch

Core Principles

  • Resource-oriented — Design around nouns (resources), not verbs (actions)
  • Predictable patterns — Consistent URL structure, response format, and behavior
  • Clear contracts — Explicit schemas, documented errors, versioned endpoints
  • Developer experience — Meaningful errors, helpful examples, logical defaults

Quick Start Checklist

  1. Identify resources and their relationships
  2. Define CRUD operations + custom actions with correct HTTP methods
  3. Design request/response schemas with consistent envelope
  4. Plan error format with status codes, error codes, and field-level details
  5. Write OpenAPI specification with examples
  6. Review for consistency, security, and usability

Design Quick Reference

| Method | Purpose | Idempotent | Body | |--------|---------|------------|------| | GET | Read | Yes | No | | POST | Create | No | Yes | | PUT | Replace | Yes | Yes | | PATCH | Partial update | Yes* | Yes | | DELETE | Remove | Yes | No |

References

| Reference | Description | |-----------|-------------| | endpoints.md | URL design, HTTP methods, resource modeling | | requests-responses.md | Request/response formats, headers, content types | | status-codes.md | HTTP status codes, error handling patterns | | pagination-filtering.md | Pagination, filtering, sorting, searching | | versioning.md | API versioning strategies | | openapi.md | OpenAPI specification, documentation | | security.md | Authentication, authorization, rate limiting | | tdd-patterns.md | Test-first patterns for REST endpoints, supertest templates | | review-checklist.md | API design review checklist (validation, auth, performance, docs) |