API Design Skill for Agents That Build Better REST APIs

Where this fits

You're sketching a new endpoint for a partner-facing API. You know the resources, but should it be /order-cancel or POST /orders/:id/cancel? How should errors look? What about pagination? Instead of stopping to scan docs, an agent with this skill can apply a consistent REST API contract before code is written.

Why agents benefit

• Agents can generate resource routes that follow plural, kebab-case noun conventions, reducing naming debates in review.
• They can choose status codes and error response envelopes that match expected client handling—not just 200/500.
• They can add pagination, filtering, and versioning strategy early, avoiding breaking changes later.
• They can audit an existing OpenAPI file or route handler against these patterns and suggest concrete improvements.
• The skill gives coding agents a shared vocabulary for API reviews, so suggestions are actionable rather than stylistic.

Practical scenarios

Designing a new public API from a product spec

When an agent turns a feature brief into routes, this skill guides it from /users/get-orders to GET /api/v1/users/:id/orders. It also selects default pagination limits and a consistent error envelope before the first endpoint is implemented.

Reviewing an existing API contract before launch

An agent can inspect route handlers and flag inconsistencies: non-standard status codes, missing version prefixes, or actions modeled as verbs in URLs. The output is a checklist of concrete changes, not vague feedback.

Adding pagination and filtering to a legacy endpoint

With the skill active, an agent modernizes a list endpoint to support limit, offset, sort, and filter params while preserving backward compatibility. It also updates response metadata and documentation.

Add it to your agent workflow

Install the skill from the repo:

npx skills add loulanyue/awesome-claude-notes --skill api-design

Then use it in agent instructions: "Use the api-design skill to critique this endpoint contract. Return the correct routes, status codes, error response format, and pagination parameters." For a broader review, ask: "Does this route need filtering or versioning? If so, propose the exact additions."

Compare before adopting

Before adding it to your stack, compare the skill with alternatives like Zalando's REST API Guidelines or Microsoft's API guidelines. Check whether the examples match your language and framework. Look at commit history: is the skill maintained? Does it cover the areas your team struggles with, like rate-limit headers or versioning? Since it's packaged as an agent skill, also confirm it fits your agent runner. For more details and quality signals, see https://www.openagentskill.com/skills/loulanyue-api-design before making it a default.

Why it is worth tracking

At 270 stars, this skill has enough community traction to be credible, and it covers production concerns—rate limiting, versioning, and error responses—that many API docs skip. It is worth tracking when you want agents to encode REST conventions instead of improvising. If maintainers keep it current with new patterns for filtering and versioning, it becomes a stronger default in agent workflows.