JPeetz/agent-skills / skills/api-backend/api-design-first
api-design-first
VerifiedUse this skill when designing an API or defining an API contract before writing code. Generates OpenAPI 3.1 specifications, enforces REST design best practices, validates endpoints, and handles versioning, pagination, error formatting, authentication patterns, rate limiting, and idempotency. Activates when users say "design an API", "create OpenAPI spec", "REST API design", "API contract", "Swagger/OpenAPI doc", "API versioning", "rate limiting", or "API security". Covers REST, GraphQL schema design, and gRPC proto generation with cross-protocol consistency.
| File | Kind | Size |
|---|---|---|
| CHANGELOG.md | markdown | 2.0 KB |
| LICENSE | other | 12 B |
| SKILL.md | skill md | 11.9 KB |
| evals/evals.json | config | 2.3 KB |
| scripts/generate-mock.shexecutable | script | 622 B |
| scripts/validate-spec.shexecutable | script | 816 B |
evals/evals.json
View on GitHub{
"skill": "api-design-first",
"version": "1.0.0",
"cases": [
{
"id": "e1",
"description": "Should trigger: design REST API",
"input": "Design a REST API for a blog platform with users, posts, and comments",
"shouldTrigger": true,
"expect": "Complete OpenAPI 3.1 spec with resources, pagination, errors, auth"
},
{
"id": "e2",
"description": "Should trigger: create OpenAPI specification",
"input": "Create an OpenAPI spec for our e-commerce checkout API",
"shouldTrigger": true,
"expect": "OpenAPI 3.1 YAML with paths, schemas, security, mock instructions"
},
{
"id": "e3",
"description": "Should trigger: API versioning strategy",
"input": "We need to make breaking changes to our API. How should we handle versioning?",
"shouldTrigger": true,
"expect": "URL path versioning, deprecation headers, Sunset, grace period"
},
{
"id": "e4",
"description": "Should trigger: rate limiting design",
"input": "How should I implement rate limiting for my public API?",
"shouldTrigger": true,
"expect": "Tiered limits, 429 response with Retry-After, RFC 7807 error format"
},
{
"id": "e5",
"description": "Should trigger: GraphQL schema alongside REST",
"input": "I want to offer both REST and GraphQL for my product catalog API",
"shouldTrigger": true,
"expect": "Cross-protocol consistency, Relay cursor connections, same naming"
},
{
"id": "e6",
"description": "Should trigger: API pagination strategy",
"input": "What's the best way to paginate my /users endpoint that has millions of records?",
"shouldTrigger": true,
"expect": "Cursor-based pagination, encoded cursors, hasMore, max limit"
},
{
"id": "n1",
"description": "Should NOT trigger: frontend UI question",
"input": "How do I style a dropdown menu in Tailwind CSS?",
"shouldTrigger": false,
"expect": "CSS question, not API design"
},
{
"id": "n2",
"description": "Should NOT trigger: database query optimization",
"input": "My PostgreSQL query is slow. How do I add an index?",
"shouldTrigger": false,
"expect": "Database question, not API design"
}
]
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |