Design Better APIs with the api-design Agent Skill

Where this fits

Imagine your team is adding a teams feature to a CRM API. You need clear endpoints, no ambiguous error shapes, and a versioning plan. The api-design skill gives your agent a practical playbook to design and review REST and GraphQL APIs before implementation.

Why agents benefit

• Generates resource-oriented endpoints from natural-language requirements, avoiding action-style URLs like POST /createUser.
• Applies versioning and deprecation rules to existing specs, catching breaking changes early.
• Produces consistent error-handling schemas and documentation blocks from stated conventions.
• Evaluates endpoints against an API Quality Scorecard and suggests concrete improvements.
• Answers design questions with principles such as 'consistency over cleverness' and 'backward compatibility'.

Practical scenarios

Designing a new REST resource

A developer wants to add memberships to a CRM. The agent uses the skill to define POST /teams, GET /teams/{id}/members, and appropriate status codes for validation, conflicts, and not-found cases.

Reviewing a GraphQL schema

Before shipping a GraphQL API, the agent evaluates mutation naming, input types, and error extensions, then rewrites the schema according to the skill's guidance.

Versioning a breaking change

An endpoint returns name but must split into firstName and lastName. The agent drafts a deprecation plan: add fields, keep old ones, mark deprecated, and schedule removal in a later major version.

Add it to your agent workflow

Install the skill with:

npx skills add cosmicstack-labs/mercury-agent-skills --skill api-design

Then ask your agent: 'Review these API endpoints for consistency and error handling. Use the api-design skill.' It can return a design checklist, revised routes, and a documentation template.

Compare before adopting

Before adopting, compare this skill with your team's current API guidelines. Check the GitHub repository for recent commits and issue responses to judge maintenance freshness. The 471 stars are a positive signal, but verify the patterns fit your stack: REST versioning needs differ from GraphQL federation rules. Consider whether a simple internal style guide is enough, or if your agent needs an external skill to give consistent, scorecard-based reviews.

Why it is worth tracking

This skill has tangible quality signals: a clear README, structured metadata, and a scorecard that agents can apply directly. Its author maintains the Mercury Agent Skills collection, suggesting room for related backend and design skills. Track it if you plan to automate API design reviews in CI or want agents to encode your team's principles. For more details, see the listing at https://www.openagentskill.com/skills/cosmicstack-labs-api-design and compare it with similar skills.