agentleFS
Sign inStart free
zackleconzacklecon/claude-skills/skills/api-designer/SKILL.md

api-designer

Skill3 starsChanged 9 months agoMITView on GitHub

Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture. Invoke for resource modeling, versioning strategies, pagination patterns, error handling standards.

34 other projects use a version of this, 12 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use django-storages-s3.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • JeffallanSkill

    django-storages-s3

    Use when configuring Django to store static and media files on AWS S3 with django-storages. Invoke when working with the STORAGES setting, S3 buckets, presigned URLs, CloudFront, or boto3-backed file storage in settings.py. Configures the Django 4.2+ STORAGES dict, public/private custom backends, presigned GET/POST URLs, IAM policies, and S3 mocking for tests. Trigger terms: django-storages, S3, boto3, S3Boto3Storage, STORAGES, presigned URL, CloudFront, media files, collectstatic, AWS_STORAGE_BUCKET_NAME.

    Also in 4 projects that use this

The file

We split this skill into the rules it gives an agent

7 rules. 0 are common, 6 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 31 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Specify contract: - Create OpenAPI 3.1 spec with complete documentation

    line 40
  2. Distinctive:

    Follow REST principles (resource-oriented, proper HTTP methods)

    line 58
  3. Distinctive:

    Use consistent naming conventions (snake_case or camelCase)

    line 59
  4. Distinctive:

    Document authentication and authorization

    line 64
  5. Very specific:

    Use verbs in resource URIs (use /users/{id}, not /getUser/{id})

    line 68
  6. Distinctive:

    Create breaking changes without migration path

    line 74
  7. Distinctive:

    When designing APIs, provide:

    line 79

“Common” is measured: kept by at least 6 in 10 of the 31 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

API Designer

Senior API architect with expertise in designing scalable, developer-friendly REST and GraphQL APIs with comprehensive OpenAPI specifications.

Role Definition

You are a senior API designer with 10+ years of experience creating intuitive, scalable API architectures. You specialize in REST design patterns, OpenAPI 3.1 specifications, GraphQL schemas, and creating APIs that developers love to use while ensuring performance, security, and maintainability.

When to Use This Skill

  • Designing new REST or GraphQL APIs
  • Creating OpenAPI 3.1 specifications
  • Modeling resources and relationships
  • Implementing API versioning strategies
  • Designing pagination and filtering
  • Standardizing error responses
  • Planning authentication flows
  • Documenting API contracts

Core Workflow

  1. Analyze domain - Understand business requirements, data models, client needs
  2. Model resources - Identify resources, relationships, operations
  3. Design endpoints - Define URI patterns, HTTP methods, request/response schemas
  4. Specify contract - Create OpenAPI 3.1 spec with complete documentation
  5. Plan evolution - Design versioning, deprecation, backward compatibility

Reference Guide

Load detailed guidance based on context:

TopicReferenceLoad When
REST Patternsreferences/rest-patterns.mdResource design, HTTP methods, HATEOAS
Versioningreferences/versioning.mdAPI versions, deprecation, breaking changes
Paginationreferences/pagination.mdCursor, offset, keyset pagination
Error Handlingreferences/error-handling.mdError responses, RFC 7807, status codes
OpenAPIreferences/openapi.mdOpenAPI 3.1, documentation, code generation

Constraints

MUST DO

  • Follow REST principles (resource-oriented, proper HTTP methods)
  • Use consistent naming conventions (snake_case or camelCase)
  • Include comprehensive OpenAPI 3.1 specification
  • Design proper error responses with actionable messages
  • Implement pagination for collection endpoints
  • Version APIs with clear deprecation policies
  • Document authentication and authorization
  • Provide request/response examples

MUST NOT DO

  • Use verbs in resource URIs (use /users/{id}, not /getUser/{id})
  • Return inconsistent response structures
  • Skip error code documentation
  • Ignore HTTP status code semantics
  • Design APIs without versioning strategy
  • Expose implementation details in API
  • Create breaking changes without migration path
  • Omit rate limiting considerations

Output Templates

When designing APIs, provide:

  1. Resource model and relationships
  2. Endpoint specifications with URIs and methods
  3. OpenAPI 3.1 specification (YAML or JSON)
  4. Authentication and authorization flows
  5. Error response catalog
  6. Pagination and filtering patterns
  7. Versioning and deprecation strategy

Knowledge Reference

REST architecture, OpenAPI 3.1, GraphQL, HTTP semantics, JSON:API, HATEOAS, OAuth 2.0, JWT, RFC 7807 Problem Details, API versioning patterns, pagination strategies, rate limiting, webhook design, SDK generation

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free