AGENT SKILL

sdk-dx

Design SDKs that developers love to use—APIs that feel native, error messages that guide, and experiences that reduce friction. This skill covers creating SDKs that drive adoption through exceptional developer experience rather than aggressive marketing. Trigger phrases: "SDK design",...

License 许可
MIT
最近更新
2026-10-22
Stars
★ 1
Forks
0

01 前言 Front Matter

name
sdk-dx
risk
unknown
source
https://github.com/jonathimer/devmarketing-skills/tree/main/skills/sdk-dx
license
MIT
date_added
1782864000000
description
Design SDKs that developers love to use—APIs that feel native, error messages that guide, and experiences that reduce friction. This skill covers creating SDKs that drive adoption through exceptional developer experience rather than aggressive marketing. Trigger phrases: "SDK design",...
source_repo
jonathimer/devmarketing-skills
source_type
community
license_source
https://github.com/jonathimer/devmarketing-skills/blob/main/LICENSE

02 资源文件 1

03 SKILL.md 正文

SDK Design and Developer Experience

When to Use

Use this skill when you need design SDKs that developers love to use—APIs that feel native, error messages that guide, and experiences that reduce friction. This skill covers creating SDKs that drive adoption through exceptional developer experience rather than aggressive marketing. Trigger phrases: "SDK design",...

The best SDK marketing is an SDK that developers can't stop talking about. When your SDK makes developers feel productive and competent, they become your advocates. When it frustrates them, no amount of marketing will save you.

Overview

SDK developer experience (DX) encompasses everything a developer feels when using your library:

  • Discovery: How easily can they find and install it?
  • Learning: How quickly can they understand how to use it?
  • Using: How productive are they day-to-day?
  • Debugging: How easily can they fix problems?
  • Upgrading: How painlessly can they adopt new versions?

Great SDK DX is a competitive advantage. Developers choose tools that make them feel smart.

Before You Start

Review the developer-audience-context skill to understand:

  • What languages and frameworks do your target developers use?
  • What IDE/editor setups are most common?
  • What's their experience level with your problem domain?
  • What competing SDKs have they used? What do they like/dislike?

SDK design decisions should flow from deep understanding of your users.

API Design Principles

Principle 1: Optimize for the Common Case

The most frequent use case should require the least code.

Good Design:

# Common case: send a simple message
client.messages.send("Hello world", to="+1234567890")

# Full control when needed
client.messages.send(
    body="Hello world",
    to="+1234567890",
    from_="+0987654321",
    status_callback="https://...",
    media_urls=["https://..."]
)

Bad Design:

# Every call requires full configuration
message = Message(
    body="Hello world",
    to=PhoneNumber("+1234567890"),
    from_=PhoneNumber(config.get_default_from()),
    options=MessageOptions(
        status_callback=None,
        media_urls=[]
    )
)
client.messages.send(message)

Principle 2: Progressive Disclosure

Start simple, reveal complexity as needed.

// Level 1: Simplest possible usage
const result = await client.analyze("Hello world");

// Level 2: Common options
const result = await client.analyze("Hello world", {
  language: "en",
  features: ["sentiment", "entities"]
});

// Level 3: Full control
const result = await client.analyze("Hello world", {
  language: "en",
  features: ["sentiment", "entities"],
  model: "v2-large",
  timeout: 30000,
  retries: { max: 3, backoff: "exponential" }
});

Principle 3: Fail Fast and Clearly

Catch errors as early as possible, with actionable messages.

Good:

# Validation at construction time
client = MyClient(api_key="")
# Raises immediately: ValueError: API key cannot be empty.
# Get your API key at https://dashboard.example.com/keys

# Clear error at runtime
client.users.get("invalid-id")
# Raises: NotFoundError: User 'invalid-id' not found.
# Use client.users.list() to see available users.

Bad:

client = MyClient(api_key="")  # No validation
result = client.users.get("invalid-id")
# Returns: None (is this an error? empty result? who knows?)
# Or worse: raises generic Exception with stack trace

Principle 4: Sensible Defaults

Default values should work for most cases without configuration.

// This should just work without configuration
const client = new MyClient({ apiKey: process.env.MY_API_KEY });

// Sensible defaults:
// - Automatic retries with exponential backoff
// - Reasonable timeouts
// - JSON content type
// - Standard auth headers
// - Connection pooling

Error Messages That Guide

Error messages are documentation. Make them helpful.

The Error Message Framework

Every error message should answer:

  1. What happened?
  2. Why did it happen?
  3. How do I fix it?

Good vs. Bad Error Messages

Good:

AuthenticationError: Invalid API key provided.

The API key 'sk_test_abc...' (test key) cannot be used for
production requests.

To fix this:
1. Go to https://dashboard.example.com/keys
2. Copy your production API key (starts with 'sk_live_')
3. Update your environment variable: MY_API_KEY=sk_live_...

Docs: https://docs.example.com/authentication

Bad:

Error: 401 Unauthorized

Error Types to Distinguish

Create specific error types that developers can catch:

from myapi.errors import (
    AuthenticationError,  # Invalid/missing credentials
    AuthorizationError,   # Valid creds, insufficient permissions
    ValidationError,      # Invalid input data
    NotFoundError,        # Resource doesn't exist
    RateLimitError,       # Too many requests
    ServerError,          # Our fault, retry might help
)

try:
    client.users.get(user_id)
except NotFoundError as e:
    # Handle missing user specifically
except AuthenticationError as e:
    # Handle auth issues specifically
except MyAPIError as e:
    # Catch-all for other API errors

Include Context in Errors

// Bad: generic error
throw new Error("Invalid parameter");

// Good: contextual error
throw new ValidationError({
  message: "Invalid phone number format",
  field: "to",
  value: "+1abc",
  expected: "E.164 format (e.g., +14155551234)",
  docs: "https://docs.example.com/phone-numbers"
});

Type Safety

Type safety is documentation that never goes stale.

TypeScript Best Practices

// Define explicit types for all inputs and outputs
interface User {
  id: string;
  email: string;
  name: string;
  createdAt: Date;
  metadata?: Record<string, unknown>;
}

interface CreateUserInput {
  email: string;
  name: string;
  metadata?: Record<string, unknown>;
}

// Return types are explicit
async function createUser(input: CreateUserInput): Promise<User> {
  // ...
}

// Use discriminated unions for responses
type ApiResponse<T> =
  | { success: true; data: T }
  | { success: false; error: ApiError };

Autocomplete-Driven Design

Design for IDE autocomplete:

// Good: autocomplete shows all options
client.messages.create({
  to: "+1...",     // IDE shows: (property) to: string
  body: "...",    // IDE shows: (property) body: string
  // User types 'me' and sees 'mediaUrls' autocomplete
});

// Bad: requires memorization
client.send("messages", { /* what goes here? */ });

Enum and Literal Types

// Good: constrained values with autocomplete
type MessageStatus = "queued" | "sending" | "sent" | "failed";

interface Message {
  status: MessageStatus;  // IDE shows valid values
}

// Bad: any string accepted
interface Message {
  status: string;  // No guidance, errors at runtime
}

IDE Integration

Make Discovery Easy

Structure your SDK so IDE features help developers:

// Namespace methods logically
client.users.get(id)
client.users.list()
client.users.create(data)
client.users.update(id, data)
client.users.delete(id)

// After typing 'client.users.' the IDE shows all user operations

JSDoc/Docstrings Everywhere

/**
 * Creates a new user in your organization.
 *
 * @param input - The user details
 * @param input.email - Must be a valid email address
 * @param input.name - Display name (max 100 characters)
 * @returns The created user with generated ID
 * @throws {ValidationError} If email format is invalid
 * @throws {ConflictError} If email already exists
 *
 * @example
 * const user = await client.users.create({
 *   email: "jane@example.com",
 *   name: "Jane Developer"
 * });
 */
async createUser(input: CreateUserInput): Promise<User>

Inline Examples

def send_message(self, body: str, to: str, **kwargs) -> Message:
    """
    Send an SMS message.

    Args:
        body: The message content (max 1600 characters)
        to: Recipient phone number in E.164 format

    Returns:
        Message object with ID and status

    Example:
        >>> message = client.messages.send(
        ...     body="Hello from Python!",
        ...     to="+14155551234"
        ... )
        >>> print(message.status)
        'queued'
    """

Versioning Strategy

Semantic Versioning

Follow semver strictly:

  • MAJOR: Breaking changes (removal, signature changes)
  • MINOR: New features (backward compatible)
  • PATCH: Bug fixes (backward compatible)

What Constitutes a Breaking Change

Breaking changes (require major version bump):

  • Removing a public method or property
  • Changing method signatures
  • Changing return types
  • Changing default behavior
  • Removing support for a language/runtime version

Not breaking (minor or patch):

  • Adding new methods
  • Adding optional parameters
  • Deprecating (but not removing) features
  • Bug fixes that change incorrect behavior

Deprecation Process

import warnings

def old_method(self):
    """
    .. deprecated:: 2.3.0
       Use :meth:`new_method` instead. Will be removed in 3.0.0.
    """
    warnings.warn(
        "old_method() is deprecated, use new_method() instead. "
        "See migration guide: https://docs.example.com/migrate-v3",
        DeprecationWarning,
        stacklevel=2
    )
    return self.new_method()

Migration Guides

Migration Guide Structure

# Migrating from v2 to v3

## Overview
Version 3 introduces [major change] and removes [deprecated feature].
Migration typically takes [time estimate].

## Breaking Changes

### 1. Client Initialization
**Before (v2):**
```python
client = MyClient(key="...")

After (v3):

client = MyClient(api_key="...")

Why: Consistency with other SDK parameters.

2. [Next breaking change]

...

Deprecated Features Removed

  • client.old_method() - Use client.new_method() instead
  • LegacyClass - Use ModernClass instead

New Features

  • [Feature that makes migration worthwhile]

Need Help?

  • [Migration support channel]
  • [Office hours for migration questions]

### Codemods and Automation

When possible, provide automated migration:

```bash
# Provide migration scripts
npx @myapi/migrate-v3

# Or codemods
npx jscodeshift -t @myapi/codemods/v2-to-v3 src/

Making SDKs Feel Native

Language Idioms

Python: Use snake_case, context managers, generators

# Pythonic
with client.batch() as batch:
    for user in client.users.list():
        batch.add(user.send_notification("Hello"))

# Not Pythonic
users = client.getUsers()
batch = client.createBatch()
for i in range(len(users)):
    batch.addOperation(users[i].sendNotification("Hello"))
batch.execute()

JavaScript: Use Promises, async/await, destructuring

// Idiomatic JS
const { data, error } = await client.users.get(id);

// Not idiomatic
client.users.get(id, function(err, result) {
    if (err) { /* callback hell */ }
});

Go: Use error returns, interfaces, channels

// Idiomatic Go
user, err := client.Users.Get(ctx, userID)
if err != nil {
    return fmt.Errorf("getting user: %w", err)
}

// Not idiomatic
user := client.Users.Get(userID)  // panics on error

Match Ecosystem Conventions

  • Use the package manager developers expect (npm, pip, gem, go get)
  • Follow naming conventions of popular libraries in that language
  • Integrate with popular frameworks (Express, Django, Rails)
  • Support popular testing patterns

SDK Quality Checklist

Before Release

  • [ ] All public APIs have documentation
  • [ ] All public APIs have types (where language supports)
  • [ ] Error messages include remediation steps
  • [ ] Code examples in docs are tested automatically
  • [ ] Changelog is updated with all changes
  • [ ] Migration guide for breaking changes
  • [ ] Deprecation warnings for removed features

For Great DX

  • [ ] Quickstart achieves success in < 5 minutes
  • [ ] IDE autocomplete works for all operations
  • [ ] Errors are catchable by specific type
  • [ ] Retry logic handles transient failures
  • [ ] Logging is configurable and useful
  • [ ] Debug mode shows request/response details

Tools

SDK Generation

  • OpenAPI Generator: Generate SDKs from OpenAPI specs
  • Swagger Codegen: Alternative generator
  • Speakeasy: Modern SDK generation platform
  • Fern: Type-safe SDK generation

Testing

  • VCR/Betamax: Record and replay HTTP interactions
  • WireMock: Mock HTTP services
  • Pact: Contract testing

Documentation

  • TypeDoc: TypeScript documentation
  • Sphinx: Python documentation
  • GoDoc: Go documentation
  • YARD: Ruby documentation

Related Skills

  • docs-as-marketing: Documentation that showcases SDK capabilities
  • api-onboarding: First experience with your SDK
  • changelog-updates: Communicating SDK changes effectively
  • developer-sandbox: Try SDK without installing
  • developer-audience-context: Understanding SDK users

Limitations

  • Use this skill only when the task clearly matches its upstream source and local project context.
  • Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
  • Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

04 同仓库更多 Skills

Hazek-dc
Hazek-dc/PresensiGuru_FaceNet_EMAR

testing-best-practices

Laravel test design and review. Use when selecting coverage, naming or structuring tests, choosing assertions or test data, isolating dependencies, testing HTTP or security boundaries, improving suite performance, or reviewing test value. Use framework guidance or search-docs for Pest and PHPUnit syntax.

★ 1
Hazek-dc
Hazek-dc/PresensiGuru_FaceNet_EMAR

tailwindcss-development

Always invoke when the user's message includes 'tailwind' in any form. Also invoke for: building responsive grid layouts (multi-column card grids, product grids), flex/grid page structures (dashboards with sidebars, fixed topbars, mobile-toggle navs), styling UI components (cards, tables, navbars, pricing sections, forms, inputs, badges), adding dark mode variants, fixing spacing or typography, and Tailwind v3/v4 work. The core use case: writing or fixing Tailwind utility classes in HTML templates (Blade, JSX, Vue). Skip for backend PHP logic, database queries, API routes, JavaScript with no HTML/CSS component, CSS file audits, build tool configuration, and vanilla CSS.

★ 1
Hazek-dc
Hazek-dc/PresensiGuru_FaceNet_EMAR

laravel-best-practices

Apply this skill whenever writing, reviewing, or refactoring Laravel PHP code. This includes creating or modifying controllers, models, migrations, form requests, policies, jobs, scheduled commands, service classes, and Eloquent queries. Triggers for N+1 and query performance issues, caching strategies, authorization and security patterns, validation, error handling, queue and job configuration, route definitions, and architectural decisions. Also use for Laravel code reviews and refactoring existing Laravel code to follow best practices. Covers any task involving Laravel backend PHP code patterns.

★ 1
Hazek-dc
Hazek-dc/PresensiGuru_FaceNet_EMAR

infer-conventions

Use this skill to analyze how a Laravel application is actually written and record its conventions as shared rules. Trigger when the user wants to detect, infer, document, or standardize project conventions or coding style, set up or grow `.ai/rules`, resolve mixed or conflicting patterns (e.g. "are we using Form Requests or inline validation?"), or onboard agents and teammates to "how we do things here". Covers: a systematic sweep of ~49 Laravel convention dimensions (validation, models, architecture, testing, frontend, database, console), open-ended house-pattern discovery, conflict reporting, and recording rules scoped to the right paths via the Boost `record-rule` MCP tool. Only run this skill when the user explicitly asks for it; never start a sweep as part of another task. Do not use for one-off code review, enforcing formatting a linter already handles, or editing `.ai/rules` files by hand.

★ 1
Hazek-dc
Hazek-dc/PresensiGuru_FaceNet_EMAR

inertia-react-development

Develops Inertia.js v2 React client-side applications. Activates when creating React pages, forms, or navigation; using <Link>, <Form>, useForm, or router; working with deferred props, prefetching, or polling; or when user mentions React with Inertia, React pages, React forms, or React navigation.

★ 1
Hazek-dc
Hazek-dc/PresensiGuru_FaceNet_EMAR

deploying-to-cloud

Deploys and manages Laravel applications on Laravel Cloud using the `cloud` CLI. Use when the user wants to deploy an app, ship to Cloud, create or manage applications, environments, databases, caches, object storage, queues, domains, instances, background processes, secrets, compute, scheduled tasks, or Laravel Cloud infrastructure; or check billing, usage, or spend. Triggers on deployment, shipping, Cloud management, environment setup, database provisioning, billing or usage queries, the `cloud` CLI, and Laravel Cloud deployment troubleshooting.

★ 1