How do I install the API Design skill?

Run npx skillmds@latest add hi-donwi/api-design in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is API Design safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with API Design?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is API Design free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published API Design?

hi-donwi (@hi-donwi) published this skill. Their other Agent Skills are listed on their SkillMD profile.

API Design by hi-donwi — Agent Skill

Name: API Design
Rating: 4.666666666666667 (3 reviews)
Author: hi-donwi

API Design

Design clear, contract-first APIs and module interfaces with validation at the boundaries. Use when adding or changing an HTTP/RPC endpoint, a public library interface, or a service contract, or when reviewing an interface for consistency. Do not use for internal one-off helpers with no external consumers.

hi-donwi Updated Sep 22, 2026

File contents

API & Interface Design

Overview

Define the contract before the implementation. A good interface is predictable, hard to misuse, and validated at its edges.

When to use

New or changed endpoints, SDK surfaces, or cross-module interfaces.
Establishing conventions for a service or library.

Process

Model the resource/operation — nouns and verbs, not incidental implementation.
Specify the contract first (OpenAPI/types/schema): inputs, outputs, status/error codes.
Validate at the boundary — reject malformed input early; never trust callers.
Be consistent — naming, pagination, filtering, errors, and auth follow one convention.
Design errors — typed, actionable, with stable codes; don't leak internals.
Plan versioning & compatibility — additive changes; deprecate, don't break (see deprecation-and-migration if it existed, else document the migration).
Document alongside the contract; add tests for the contract.

Red flags

Leaking database shapes or internal enums through the public surface.
Inconsistent error formats across endpoints.
Booleans/flags that should be explicit states; over-broad "do everything" endpoints.
Breaking changes shipped without a version or deprecation path.

Verification

The contract is written and validated; invalid input is rejected with typed errors.
A new consumer can integrate from the contract alone, without reading the implementation.

Reference Index

references/expanded-guidance.md — deeper API/interface design principles, examples, and compatibility guidance.

Frequently asked questions