skills.rest
chrisbanes
chrisbanesCOMMUNITY
Explore all skills by this author →
Website𝕏@chrisbanesGitHub

kotlin-api-design

Guides Kotlin API design decisions for function ownership, value classes, and multiplatform boundaries.

1.0k|46|Updated May 12, 2026
Search Tags:#Kotlin#API Design#kotlin multiplatform#expect actual#value class#Code review#extension functions
One-click install
npx skills add https://github.com/chrisbanes/skills --skill kotlin-api-design
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: kotlin-api-design
Source: https://github.com/chrisbanes/skills/tree/main/skills/kotlin-api-design
Command: npx skills add https://github.com/chrisbanes/skills --skill kotlin-api-design

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Kotlin developers often struggle with where to place behavior (member vs extension vs top-level), when to wrap primitives in domain types, and how to structure Kotlin Multiplatform expect/actual boundaries without leaking platform details into common code.

Core Features & Use Cases

  • Function Ownership Decisions: Choose between member functions, extensions, top-level functions, factories, and injected collaborators based on semantic ownership rules.
  • Value Class vs Data Class Guidance: Decide when a single-field domain concept warrants a @JvmInline value class, a typealias, or a data class, with contract checks for serialization, equality, and Java interop.
  • Multiplatform Boundary Design: Structure expect/actual declarations and common interfaces so platform SDK details stay at leaf nodes and common APIs remain semantic.
  • Use Case: When reviewing a PR that adds a String.toUserId() extension, use this Skill to relocate construction to a UserId companion factory and verify the change preserves the public contract.

Quick Start

Ask the assistant to review your Kotlin API design, for example whether a function should be a member or extension, or whether a wrapper type should be a value class or data class.

Frequently Asked Questions about kotlin-api-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
When should I use a Kotlin extension function vs a member function?▼

Use a member when the behavior is intrinsic to a project-owned type. Extensions are appropriate only for narrow private or internal scope, valid for every receiver value, with no policy, state, I/O, or dependencies, and when receiver syntax is materially clearer.

Value class vs data class in Kotlin: which should I choose?▼

Choose a @JvmInline value class for a single-field domain-meaningful type like UserId or EmailAddress. Use a data class for multiple fields, custom equality, or when callers rely on copy() and destructuring, since value classes delegate equality to the wrapped value.

How do I structure Kotlin Multiplatform expect/actual declarations?▼

Keep common APIs semantic and free of platform types like Context or UIViewController. Use expect/actual for simple compile-time specialization, and a common interface with platform bindings when you need fakes, injected dependencies, or lifecycle ownership.

Does a Kotlin value class affect JSON serialization?▼

Yes. A @Serializable data class with one field encodes as a JSON object, while a value class encodes as the wrapped value directly. Verify your API contract before converting, since this silently changes the wire format.

When should I avoid using a Kotlin value class?▼

Avoid value classes when the field has no domain meaning, when you need custom equality, or in nullable, generic, or vararg hot paths where boxing occurs. Also avoid them when constructor bodies, lateinit, or delegated properties are required.

Related Skills

Explore More Software Engineering Skills→
DesquaredDesquared
3

kotlin-api-design-reviewer

Review Kotlin public APIs for naming, visibility, and interface design issues.

Official
Advanced
pebblepawpebblepaw

coding-practices

Coordinate cross-cutting updates to prompts, schemas, configuration, and UI labels across codebases.

Community
Intermediate
Postpartum-genushyacinthus29Postpartum-genushyacinthus29
8

dotnet-managedcode-communication

Replace exception-driven control flow with explicit result objects in .NET services.

Community
Intermediate
Binh230199Binh230199
1

android-lint-fix

Fix Android lint, Kotlin compiler warnings, and Detekt violations rule by rule.

Community
Advanced