agentsclimarketplace

Api and interface design

Skill charlieviettq/awesome-agent-skill/.cursor/skills/core-workflow/api-and-interface-design

Curated skill pack for LLM agents in engineer and science workflow (Cursor & Claude ready).

Install
npx -y skills add charlieviettq/awesome-agent-skill --skill api-and-interface-design

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

One thing to look at

  • 22 stars22 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.

What its author says it does

Copied from the file, not written here

Design API and module boundaries with clear contracts, error semantics, pagination, and additive compatibility. Use before implementing REST/GraphQL endpoints, SDKs, or public module APIs. Triggers: "API design", "interface contract", "endpoint design", "pagination", "error codes", "backward compatible".

SKILL.md

2.5 KB, as published. Nobody here has run it

API and Interface Design

Contract-first design for HTTP APIs, GraphQL, CLI surfaces, and library module boundaries. Complements secure-api-design (security) and agent-tool-contracts (LLM tools) with general interface ergonomics and evolution rules.

When to use

  • New public or cross-team API
  • Breaking-change review
  • Designing pagination, filtering, idempotency, or error shapes

When not to use

  • Internal refactor with no boundary change
  • Security-only audit (use secure-api-design)
  • Agent tool schema only (use agent-tool-contracts)

Design checklist

Contract

  • Resource naming consistent (nouns, plural collections)
  • Versioning strategy documented (URL prefix, header, or additive-only)
  • Request/response schemas with examples for happy path + common errors
  • Idempotency keys for mutating operations where retries matter

Errors

  • Stable machine-readable codes separate from human messages
  • HTTP/status mapping documented; no stack traces in client responses
  • Validation errors: field-level detail when safe (no PII leakage)

Pagination and lists

  • Cursor-based preferred for large/live datasets; offset only when bounded
  • Default and max page size documented
  • Sort/filter params explicit; reject unknown params predictably

Compatibility

  • Additive changes only in minor versions
  • Deprecation headers or sunset dates for removals
  • Consumer migration notes in changelog

Observability

  • Correlation/request IDs in responses or logs
  • Rate-limit headers where applicable

Workflow

  1. Draft resource model and primary use cases
  2. Write example requests/responses (including errors)
  3. Run doubt-driven-review or secure-api-design for high-risk surfaces
  4. Implement with tests locked to contract examples

Output

  • Short design note or OpenAPI/GraphQL schema sketch
  • Compatibility and deprecation table if evolving an existing API

Related skills

  • secure-api-design — authn/z, input validation, secrets
  • agent-tool-contracts — LLM-facing tool schemas
  • deprecation-and-migration — sunsetting old interfaces

Adapted from addyosmani/agent-skills (MIT).

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.