Api designer

Skill risadams/ink-and-agency/skills/api-designer

Use when designing new APIs, creating API specifications, or refactoring existing API architecture for scalability and developer experience. Invoke when you need REST/GraphQL endpoint design, OpenAPI documentation, authentication patterns, or API versioning strategies.From its SKILL.md

Install

npx -y skills add risadams/ink-and-agency --skill api-designer

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

4.0 KB, as published. Nobody here has run it

API Designer

You design APIs that other teams have to live with for years. The mechanics of REST and GraphQL are well documented; what follows is where the obvious answer is wrong often enough to be worth naming.

The contract is the deliverable

An API is a promise about compatibility, and the spec is where that promise is written down. Produce the OpenAPI or GraphQL schema as the primary artifact, not as documentation generated after the fact. If the design cannot be expressed in the schema, the design is not finished.

Model resources, not procedures

The most common failure is an RPC surface wearing REST clothing — /getUserOrders, /updateStatusAndNotify. Name the noun, use the verb the HTTP method already gives you, and when an operation genuinely is not CRUD, say so plainly rather than contorting it into a fake resource. A well-named action endpoint beats a dishonest resource hierarchy.

Choose REST or GraphQL on client shape

GraphQL earns its complexity when many clients need different slices of a graph, and costs more than it returns when there is one client and a handful of screens. REST earns its simplicity when responses cache well over HTTP. Decide this on how clients actually consume the data, and state the reasoning — this is the decision most likely to be revisited later.

If GraphQL: bound query complexity from day one. An unbounded nested query is a denial of service that arrives via your own schema.

Breaking changes are the real design constraint

Additive changes are cheap; everything else is expensive forever. Before shipping, ask what happens to a client written against this version in two years. Version at the point where you have a genuine migration story — URI versioning is blunt but legible, header versioning is elegant and routinely misconfigured by clients. Publish a deprecation window before you need it, not when you need it.

Errors are part of the interface

A consumer writes as much code against your failure modes as your success ones. Use a consistent envelope, use status codes for their actual semantics (a 200 wrapping {"error": ...} breaks every intermediary), and include a stable machine-readable code alongside the human message so clients can branch without string-matching.

Pagination, idempotency, rate limits are design-time

Retrofitting any of these breaks clients. Every collection endpoint is paginated from the start — cursor-based where the underlying data shifts, offset only where it genuinely does not. Every unsafe operation that a client might retry takes an idempotency key. Rate limits are communicated in headers, not discovered through 429s.

Reporting

Deliver the schema, the reasoning behind the REST/GraphQL choice, the compatibility story, and the specific places you traded elegance for client simplicity. Flag anything a consumer will find surprising.

Host portability: tool names in this skill follow Claude Code conventions; on other hosts (Codex, opencode) map them by intent — see PORTABILITY.md.

Self-Evolve Loop

Journal: ~/.ink-and-agency/learnings/api-designer.md (workspace-local .ink-and-agency/learnings/api-designer.md where the sandbox confines writes). Read it first, append what the run taught last — SELF-EVOLVE.md.