Design REST APIs with an Agent That Thinks in Contracts

Where this fits

You're sketching out a new endpoint for your service. You have a rough idea: a POST to upload a user avatar, a GET for user preferences, and a PATCH to update them. But where should the routes live? What's the request body shape? Which status codes mean what? If you're like most developers, you make a few choices on the fly and hope they align with what's already in your codebase. That's exactly where the api-designer skill steps in—it turns vague endpoint ideas into structured REST contracts, and it can also review your existing API for consistency before more consumers depend on it.

Why agents benefit

• Institutionalizes REST conventions: The agent applies consistent pluralization, HTTP verb semantics, and status code mapping across all endpoints it designs or reviews—so you don't get /users from one endpoint and /getUserById from another.
• Models resources first: Instead of jumping to routes, it identifies the core resources and their relationships, helping you avoid RPC-style endpoints that are painful to maintain later.
• Generates explicit request/response schemas: You get concrete field types, validation rules, and error formats—not vague suggestions like "use a proper response body."
• Catches versioning and nesting traps: The agent flags over-nested routes (past two levels) and reminds you about versioning strategies before you bake in a bad URL structure.
• Reviews API design as a second pair of eyes: When you have existing endpoints, the agent can audit them against common best practices, giving you a actionable list of inconsistencies.

Practical scenarios

Designing a brand-new API from scratch

You're building a small SaaS and need a JSON API for customers, subscriptions, and invoices. Instead of staring at a blank spec, you give the agent a high-level capability list. It returns a proposed resource breakdown, route map, and sample payloads—ready for you to refine.

Reviewing a legacy API before adding new endpoints

Your team has a years-old REST API with some endpoints that follow conventions and others that don't. You're about to add a new billing resource. The agent reviews the existing patterns and tells you what to mirror—or what to deprecate—so the new endpoints fit naturally.

Shaping a rough idea into a contract

You have a clear use case: "The client should be able to update a user's email, but only if the user hasn't verified it yet." The agent translates that into a PATCH /users/{id}/email with specific request/response fields, validation rules (e.g., email format, uniqueness), and proper status codes (200 vs 202 vs 409).

Add it to your agent workflow

Install the skill with npx:

npx skills add codebygarv/Ai-skills --skill api-designer

Then, when your agent is set up, you can prompt it like: "Use the api-designer skill to review the following endpoints for consistency: [list]." The agent will load the skill’s context and produce a design review or a new endpoint proposal.

Compare before adopting

Before you commit, compare this skill to alternatives like OpenAPI Generator or hand-rolled API checklists. Look at the skill's README quality—does it clearly define input/output behavior? Does the author maintain it (last commit, issues)? Check if it covers your stack (it's language-agnostic but may not address specific framework quirks). Also, consider if you already have internal conventions—this skill might conflict or complement them.

Why it is worth tracking

With 21 stars and an active repo, api-designer shows early community interest, but it's still young. The skill's value depends on the author's willingness to update it as REST practices evolve (e.g., new status codes, pagination patterns). Track it because it addresses a common pain point—API design inconsistency—and it could become a default tool in agent workflows. Revisit when it reaches a few hundred stars or gets contributions. For more details, check its skill page. For now, it's a lightweight, useful skill to adopt if you already rely on agent-driven development and want consistent APIs.