api-designer
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.
Best use case
api-designer is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
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.
Teams using api-designer should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/api-designer/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How api-designer Compares
| Feature / Agent | api-designer | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
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.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# 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:
| Topic | Reference | Load When |
|-------|-----------|-----------|
| REST Patterns | `references/rest-patterns.md` | Resource design, HTTP methods, HATEOAS |
| Versioning | `references/versioning.md` | API versions, deprecation, breaking changes |
| Pagination | `references/pagination.md` | Cursor, offset, keyset pagination |
| Error Handling | `references/error-handling.md` | Error responses, RFC 7807, status codes |
| OpenAPI | `references/openapi.md` | OpenAPI 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 generationRelated Skills
regex-vs-llm-structured-text
Decision framework for choosing between regex and LLM when parsing structured text — start with regex, add LLM only for low-confidence edge cases.
python-testing
Python testing strategies using pytest, TDD methodology, fixtures, mocking, parametrization, and coverage requirements.
python-patterns
Pythonic idioms, PEP 8 standards, type hints, and best practices for building robust, efficient, and maintainable Python applications.
prompt-engineer
Use when designing prompts for LLMs, optimizing model performance, building evaluation frameworks, or implementing advanced prompting techniques like chain-of-thought, few-shot learning, or structured outputs.
golang-testing
Go testing patterns including table-driven tests, subtests, benchmarks, fuzzing, and test coverage. Follows TDD methodology with idiomatic Go practices.
golang-pro
Master Go 1.21+ with modern patterns, advanced concurrency, performance optimization, and production-ready microservices. Expert in the latest Go ecosystem including generics, workspaces, and cutting-edge frameworks. Use PROACTIVELY for Go development, architecture design, or performance optimization.
golang-patterns
Idiomatic Go patterns, best practices, and conventions for building robust, efficient, and maintainable Go applications.
go-concurrency-patterns
Master Go concurrency with goroutines, channels, sync primitives, and context. Use when building concurrent Go applications, implementing worker pools, or debugging race conditions.
frontend-patterns
Frontend development patterns for React, Next.js, state management, performance optimization, and UI best practices.
bash-pro
Master of defensive Bash scripting for production automation, CI/CD, pipelines, and system utilities. Expert in safe, portable, and testable shell scripts.
ai-product
Every product will be AI-powered. The question is whether you'll build it right or ship a demo that falls apart in production. This skill covers LLM integration patterns, RAG architecture, prompt ...
You are a professional Landing page designer who is very friendly and supportive.
Your task is to guide a beginner through planning and designing a landing page or personal portfolio.