Design SDKs with exceptional developer experience

Helps design SDKs that developers love using, on the premise that great developer experience across five stages - discovery, learning, using, debugging, and upgrading - is a competitive advantage that drives adoption better than marketing does. It first points to the developer-audience-context skill to understand target languages, IDE setups, experience level, and competing SDKs, since design decisions should flow from that understanding. Four API design principles anchor everything: optimize for the common case (the most frequent use case needs the least code, with full configuration available but not required); progressive disclosure (simplest usage first, options revealed as needed, full control available at the deepest level); fail fast and clearly (validate at construction time with an actionable error rather than returning None or a generic exception at some later point); and sensible defaults (a client should just work from an API key alone, with automatic retries, reasonable timeouts, and standard auth headers built in). Error messages are treated as documentation: every message should answer what happened, why, and how to fix it, contrasting a bad 401 Unauthorized against a good message naming the exact key issue and giving numbered remediation steps with a docs link. Specific catchable error types (AuthenticationError, AuthorizationError, ValidationError, NotFoundError, RateLimitError, ServerError) let developers handle each failure mode distinctly instead of parsing a generic exception, and errors should carry structured context (field, value, expected format) rather than a bare string. Type safety is framed as documentation that never goes stale: explicit input/output types, discriminated union response types, autocomplete-driven design (so typing client.users. surfaces every operation via namespaced methods), and enum/literal types so the IDE shows valid values instead of accepting any string. Documentation should live in JSDoc/docstrings on every public method with runnable inline examples, since discovery happens in the IDE, not just in a docs site. Versioning follows strict semver, with an explicit breaking-vs-not distinction (removing a method, changing a signature, changing return types, or changing default behavior are breaking; adding methods, adding optional parameters, deprecating without removing, and behavior-correcting bug fixes are not), a deprecation process that warns before removal with a migration link, a structured migration guide template (overview, before/after code per breaking change with a stated reason, removed deprecated features, new features that make migrating worthwhile, and a help channel), and automated migration scripts or codemods when feasible. Making an SDK feel native to its language means following that language's idioms - Python's snake_case, context managers, and generators over camelCase and manual loops; JavaScript's Promises and async/await over callback-based APIs; Go's explicit error returns over exceptions or silent panics - and matching ecosystem conventions for package managers and popular framework integrations. A pre-release quality checklist covers documentation and type coverage on every public API, remediation steps in every error message, tested code examples, an updated changelog, and a migration guide for any breaking change; a separate DX checklist covers a sub-5-minute quickstart, full IDE autocomplete, specifically-catchable errors, transient-failure retry logic, configurable logging, and a debug mode showing request/response detail.

Use it when designing or reviewing an SDK's API surface, error handling, type definitions, versioning strategy, or migration guides - anywhere the goal is reducing developer friction and making the SDK feel native to its target language.

Input is an SDK's current or proposed API surface, error handling approach, or a planned breaking change. Output is API design following the four core principles, a structured error-message framework with distinguishable error types, type-safe interfaces with autocomplete support, and (for breaking changes) a semver-correct version bump with a full migration guide.

References the developer-audience-context skill for understanding SDK users, and recommends tooling: OpenAPI Generator/Speakeasy/Fern for SDK generation, VCR/WireMock/Pact for HTTP testing, and TypeDoc/Sphinx/GoDoc/YARD for language-specific documentation; hands off to docs-as-marketing, api-onboarding, changelog-updates, and developer-sandbox skills for adjacent work.

SDK and API teams who want their library to feel native to the target language, fail with actionable errors instead of generic exceptions, and handle breaking changes with proper semver and migration guides rather than surprising downstream developers.