skill-developer-relations

name	skill-developer-relations
description	SDK development, external developer communication, code samples, API client libraries, community engagement, and developer experience. Use when creating SDKs, writing external guides, creating code samples, or improving developer experience.
version	1.0.0

Skill: Developer Relations

Overview

Develop SDKs, guides, and external-facing communication that makes your product accessible and enjoyable for third-party developers.

Core Principles

1. SDK Design

• Single Responsibility: One SDK = one language, one purpose
• Familiar Patterns: Match community conventions (not your internal patterns)
  • Python: classes, context managers, snake_case
  • JavaScript: async/await, CommonJS or ESM, camelCase
  • Go: interfaces, structs, package-level functions
• Minimal Dependencies: Reduce transitive dependency bloat
• Versioning: Semantic versioning, clear deprecation paths

2. Code Samples

• Real, Runnable: Not pseudocode — every sample executes
• Progressive Complexity: Start simple, build up
  • Hello World (authentication only)
  • Basic operation (read/write)
  • Advanced pattern (error handling, retries, batching)
• Error Paths: Show what failure looks like and how to handle it
• Tested: CI verifies samples remain accurate as APIs evolve

3. Documentation for Developers

• Task-First, Not API-First:
  • Instead of: "Query using GET /users/{id}"
  • Write: "To fetch a user by ID: [sample code]"
• Examples Over Explanation: Code sample > prose description
• Quick Start: First 5 minutes = working integration (not configuration)
• API Reference: Auto-generated from OpenAPI/GraphQL schema (not hand-written)

4. Developer Experience (DX)

• Obvious Error Messages: Include context (what happened, why, how to fix)
• Retry Logic: Built-in exponential backoff for transient failures
• Rate Limit Handling: Transparent queuing or clear backpressure
• Type Safety: Static typing (TypeScript, mypy stubs, Go generics)
• Zero Configuration: Sensible defaults; only require secrets

5. Community & Feedback

• Clear Contribution Guidelines: What community code is accepted
• Deprecation Policy: 2+ minor versions before removal, clear migration path
• Response Time: Triage issues within 48 hours
• Use Cases: Document common patterns from community questions

Execution Checklist

When Creating an SDK

• Decide target language(s) and justify (what developers use this API?)
• Design API surface (objects, functions, errors) from community perspective
• Write 3 samples: auth → basic operation → advanced pattern
• Add error handling: timeouts, retries, rate limits
• Generate OpenAPI/GraphQL client (or hand-craft minimal wrapper)
• Run samples in CI (every commit)
• Package: choose common distribution (npm, PyPI, Maven, Go modules)

When Writing Developer Guides

• Audience: Who is this for? (backend engineer? mobile? data engineer?)
• Goal: What will they build by end of guide?
• Sample App: Real project they can clone and run locally
• Runbook Format:
  1. Prerequisites (what you need)
  2. 1-sentence goal
  3. Step 1: [screenshot of result]
  4. Step 2: [screenshot of result]
  5. Troubleshooting (common failures)
• Code Samples: Copy-paste ready (not pseudocode)
• Testing: Walk through yourself, measure time (target: <15 min for quick start)

When Responding to Community Questions

• Extract Pattern: What is the underlying use case?
• Document: If it's the 3rd time someone asks, it's underdocumented
• Create Issue: For unclear error messages or missing samples
• Build Sample: If it's a complex pattern, add to guides

Example: Python SDK Design

# Familiar: context manager, snake_case, exceptions
from myapi import Client, AuthenticationError, RateLimitError

with Client(api_key="sk-...") as client:
    try:
        user = client.users.get(user_id="123")
        print(f"User: {user.email}")
    except AuthenticationError:
        print("Invalid API key")
    except RateLimitError as e:
        print(f"Rate limited. Retry after {e.retry_after}s")

Example: Developer Guide (Task-First)

Goal: Build a webhook receiver that listens for order events.

Step 1: Create Flask endpoint

from flask import Flask, request

app = Flask(__name__)

@app.route("/webhook", methods=["POST"])
def handle_webhook():
    event = request.json
    print(f"Received {event['type']}: {event['id']}")
    return {"ok": True}

Step 2: Verify signature

import hmac
import hashlib

secret = "webhook_secret_from_dashboard"

def verify_signature(body: bytes, signature: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

@app.route("/webhook", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-Webhook-Signature", "")
    if not verify_signature(request.data, signature):
        return {"error": "Invalid signature"}, 401
    # ... rest of handler

Common Pitfalls to Avoid

❌ SDK with opinionated architecture: Forces framework choice (use minimal wrapper)
❌ Incomplete error context: "Error 401" instead of "Invalid API key. See docs.example.com/auth"
❌ Samples that don't run: Pseudocode or manual setup required before copy-paste works
❌ API-first documentation: "GET /users/{id}" instead of "To fetch a user..."
❌ Silent failures: Missing retry logic, rate limit handling, or timeout defaults

Success Metrics

• Adoption: SDK downloads/installs trending up (PyPI, npm, Maven)
• Time-to-First-Success: Measure how long until developer's first successful API call (target: <10 min)
• Support Load: Fewer duplicated questions (indicates good docs)
• Community Contributions: Issues opened, PRs submitted, Stack Overflow answers
• Satisfaction: Developer survey NPS on ease-of-use