When this skill is activated, always start your first response with the 🧢 emoji.

Developer Experience

Developer Experience (DX) is the practice of designing tools, SDKs, APIs, and documentation so that developers can go from zero to productive with minimal friction. Great DX reduces time-to-first-success, prevents common mistakes through ergonomic API design, and communicates changes clearly so upgrades feel safe rather than scary. This skill equips an agent to design SDKs, write onboarding flows, craft changelogs, and author migration guides that developers actually trust.

When to use this skill

Trigger this skill when the user:

• Wants to design or review an SDK's public API surface
• Needs to create a getting-started guide or quickstart tutorial
• Asks about developer onboarding flows or time-to-first-success
• Wants to write a changelog entry for a release
• Needs to author a migration guide for a breaking change
• Asks about API ergonomics, naming conventions, or method signatures
• Wants to evaluate or improve developer portal structure
• Needs to communicate deprecations or upgrade paths

Do NOT trigger this skill for:

• Internal team onboarding or HR processes (not developer tooling)
• End-user UX design for non-developer products (use UX skills instead)

Key principles

1. Time-to-first-success is the metric that matters - Every decision in DX should minimize the gap between "I found this tool" and "I got it working." If a developer cannot achieve something meaningful in under 5 minutes with your quickstart, you have a DX problem.

2. Pit of success over pit of despair - Design APIs so that the obvious, easy path is also the correct path. Defaults should be safe and sensible. Make it harder to misuse an API than to use it correctly.

3. Changelog is a contract, not a diary - Every entry should answer three questions: what changed, why it changed, and what the developer needs to do. Internal refactors that don't affect consumers do not belong in changelogs.

4. Migration guides are empathy documents - A breaking change without a clear migration path is a betrayal of trust. Every breaking change needs a before/after example, a mechanical upgrade path, and an explanation of why the break was necessary.

5. Progressive disclosure over information dump - Show developers only what they need at each stage. Quickstart shows the happy path. Guides add depth. API reference covers everything. Never front-load complexity.

Core concepts

The DX funnel mirrors a marketing funnel but for developers: Discovery (finding the tool) -> Evaluation (reading docs, trying quickstart) -> Adoption (integrating into a real project) -> Retention (staying through upgrades). Each stage has different documentation and design needs.

API surface area is the set of public methods, types, configuration options, and behaviors a developer must learn. Smaller surface area means lower cognitive load. Every public method is a commitment - it must be supported, documented, and maintained. Prefer fewer, composable primitives over many specialized methods.

The upgrade treadmill is the ongoing cost developers pay to stay current. Changelogs, deprecation notices, migration guides, and codemods are all tools to reduce this cost. High upgrade cost leads to version fragmentation and eventual abandonment.

Error messages as documentation - For many developers, the first "docs" they read are error messages. An error that says what went wrong, why, and how to fix it is worth more than a perfect API reference.

Common tasks

Design an SDK's public API

Start with use cases, not implementation. List the 5-8 most common things a developer will do, then design the minimal API that covers them.

Checklist:

1. Write the README code examples first (README-driven development)
2. Every method name should be a verb-noun pair (createUser, sendEmail)
3. Required parameters go in the function signature; optional ones go in an options object
4. Return types should be predictable - same shape for success, typed errors for failure
5. Provide sensible defaults for every configuration option
6. Use builder or fluent patterns only when construction is genuinely complex

// Good: minimal, predictable, composable
const client = new Acme({ apiKey: process.env.ACME_API_KEY });
const user = await client.users.create({ email: "dev@example.com" });
const invoice = await client.invoices.send({ userId: user.id, amount: 4999 });

Avoid: client.createUserAndSendWelcomeEmail() - compound operations hide behavior and make error handling ambiguous.

See references/sdk-design.md for the full SDK design checklist.

Write a getting-started guide

Structure every quickstart with this template:

1. One-sentence value prop - what this tool does for the developer
2. Prerequisites - language version, OS, required accounts (keep minimal)
3. Install - one command, copy-pasteable
4. Configure - environment variables or config file (show the minimum)
5. First working example - the smallest code that produces a visible result
6. Next steps - links to 2-3 natural follow-on tasks

The entire guide should be completable in under 5 minutes. If it takes longer, cut scope - move advanced setup to a separate guide.

See references/onboarding.md for the full onboarding framework.

Write a changelog entry

Follow the Keep a Changelog format. Each entry needs:

## [2.3.0] - 2026-03-14

### Added
- `client.users.archive()` method for soft-deleting users (#342)

### Changed
- `client.users.list()` now returns paginated results by default.
  Pass `{ paginate: false }` to get the previous behavior.

### Deprecated
- `client.users.delete()` is deprecated in favor of `client.users.archive()`.
  Will be removed in v3.0. See migration guide: /docs/migrate-v2.3

### Fixed
- `client.invoices.send()` no longer throws on zero-amount invoices (#401)

Rules:

• Group by Added, Changed, Deprecated, Removed, Fixed, Security
• Link to issues/PRs with parenthetical references
• For Changed/Removed: always include the migration path inline or link to one
• Never include internal refactors that don't affect the public API

See references/changelog.md for the full changelog guide.

Author a migration guide

Every migration guide follows this structure:

1. Title: "Migrating from vX to vY"
2. Who needs to migrate: which users are affected
3. Timeline: when the old version loses support
4. Breaking changes table: change, before code, after code, reason
5. Step-by-step upgrade: ordered instructions with copy-paste commands
6. Codemod (if available): automated transformation script
7. Verification: how to confirm the migration succeeded
8. Troubleshooting: 3-5 most common migration errors and fixes

### Breaking: `createPayment` renamed to `createPaymentIntent`

**Before (v1.x):**
  const payment = await client.createPayment({ amount: 1000 });

**After (v2.x):**
  const intent = await client.createPaymentIntent({ amount: 1000 });

**Why:** Aligns with industry terminology. The old name implied the charge
was immediate, but the object represents an intent that may require
additional confirmation steps.

**Codemod:** `npx @acme/migrate rename-create-payment`

See references/migration-guides.md for the full migration guide template.

Design error messages

Every error message should contain three parts:

1. What happened - factual description of the failure
2. Why it happened - the likely cause
3. How to fix it - actionable next step

AcmeAuthError: Invalid API key provided.
  The key starting with "sk_test_abc..." is not recognized.
  Get your API key at: https://dashboard.acme.com/api-keys
  Docs: https://docs.acme.com/auth#api-keys

Never expose stack traces or internal identifiers in us