api-design-assistant

Design and review APIs with suggestions for endpoints, parameters, return types, and best practices. Use when designing new APIs from requirements, reviewing existing API designs, generating API documentation, or getting implementation guidance. Supports REST APIs with focus on endpoint structure, request/response schemas, authentication, pagination, filtering, versioning, and OpenAPI specifications. Triggers when users ask to design, review, document, or improve APIs.

Install with Tessl CLI

npx tessl i github:ArabelaTso/Skills-4-SE --skill api-design-assistant

What are skills?

Review — 92%

Does it follow best practices?

Validation — 11 / 11 Passed

Validation for skill structure

SKILL.md

Review

Evals

Evaluation results

100%

API Review: Customer Support Ticketing System

RESTful API review and correction

Criteria

Without context

With context

No verbs in URLs

100%

Plural resource names

100%

Path param for resource ID

100%

Correct HTTP methods

100%

PATCH for partial update

100%

POST for actions

100%

201 for creation

100%

204 for deletion

100%

Standard error structure

100%

Correct error status codes

100%

Nested resource for comments

100%

Without context: $0.3706 · 3m 53s · 12 turns · 17 in / 8,006 out tokens

With context: $0.8002 · 5m 8s · 23 turns · 28 in / 11,216 out tokens

98%

Product Catalog API: OpenAPI Specification

OpenAPI spec generation with collections and schemas

Criteria

Without context

With context

OpenAPI 3.0 header

100%

Required top-level keys

100%

Plural lowercase resource paths

100%

Reusable $ref schemas

100%

Reusable $ref responses or parameters

100%

Collection response shape

90%

100%

Pagination fields

75%

Cursor-based pagination

100%

ISO 8601 datetime format

100%

Error response structure

100%

Nested category-products path

100%

Sort query parameter

75%

100%

Without context: $0.2774 · 3m 14s · 11 turns · 15 in / 6,643 out tokens

With context: $0.6304 · 3m 38s · 21 turns · 4,894 in / 7,761 out tokens

97%

13%

Payment Processing API: Hardening for Production

Authentication, versioning, and rate limiting design

Criteria

Without context

With context

JWT for mobile

50%

62%

API keys for server-to-server

100%

OAuth2 for third-party

100%

URL versioning

100%

Removing field requires version

100%

Type change requires version

100%

Adding optional fields no version

100%

Rate limit headers named correctly

100%

Idempotency key for order creation

100%

429 for rate limit exceeded

100%

Without context: $0.3516 · 4m 31s · 18 turns · 73 in / 6,207 out tokens

With context: $0.5477 · 5m 10s · 20 turns · 238 in / 6,831 out tokens

Evaluated: about 11 hours ago
Agent: Claude Code

Table of Contents

API Review: Customer Support Ticketing System Product Catalog API: OpenAPI Specification Payment Processing API: Hardening for Production

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.