Design Better APIs with the api-design-expert Agent Skill

Where this fits

You are adding a public invites endpoint to an existing NestJS service. You know the route list, but you need a design that keeps DTOs, errors, and versioning predictable for a mobile client. This skill plugs into that planning moment—before code is written—so the agent checks existing patterns and returns an API contract the team can review.

Why agents benefit

• Inspects .agents/memory/ and existing controllers before suggesting routes, so new endpoints match project conventions instead of generic REST patterns.
• Produces NestJS-specific code: controller decorators, DTO classes with class-validator, and exception filters for consistent error responses.
• Maps every operation to precise HTTP status codes, including 400, 404, and 409 cases, which reduces back-and-forth with frontend teams.
• Generates OpenAPI/Swagger annotations with schemas tied to DTOs, not just route names.
• Reasons about versioning strategy—URI, header, or media-type—before committing to a route design.

Practical scenarios

Versioned partner API in a growing app

You need to expose a new external API without breaking existing SDK clients. The skill reads the current versioning setup, recommends /api/v2/invites or a header-based strategy, and highlights breaking changes in response shapes.

Consistent error format across a legacy NestJS module

Existing controllers return different error shapes: some throw HttpException, others return raw objects. The skill standardizes the response envelope and provides a NestJS exception factory that all new endpoints can reuse.

OpenAPI documentation for an untouched module

The agent scans a module with controllers but no Swagger decorators. It identifies missing response schemas and DTOs, then writes OpenAPI metadata that matches actual runtime behavior.

Add it to your agent workflow

Install the skill with one command:

npx skills add shipshitdev/skills --skill api-design-expert

After installation, use a prompt like:

Use the api-design-expert skill to design POST /api/workspaces/:id/invites.
Include DTO validation, duplicate invite error handling, and Swagger metadata.

The skill first looks for .agents/memory/, then reviews existing controllers and OpenAPI setup before generating recommendations.

Compare before adopting

Before making it a permanent part of your agent stack, compare it against how your team already designs APIs. Check quality signals: does the README show concrete NestJS code for controllers, DTOs, and exception filters? Is the project maintained? With 35 stars and a single author, inspect commit dates and issues. Consider alternatives like openapi-generator for contract-first workflows or the NestJS CLI Swagger plugin if you only need documentation generation. Most importantly, verify workflow fit: this skill assumes a NestJS project and an agent that can inspect project context before writing code.

Why it is worth tracking

API design decisions are repetitive and easy to make inconsistent, especially in agent-assisted development. This skill is worth tracking because it embeds project context discovery and NestJS-specific guidance, which are stronger signals than star count alone. Its 35-star repo shows early but real community interest, so it is worth evaluating when you start a new service or refactor an existing API. If the agent produces more reviewable designs, keep it in your toolkit. For a quick reference point, see the skill listing on OpenAgentSkill: https://www.openagentskill.com/skills/shipshitdev-api-design-expert