Skip to main content
Agent skill

Kotlin Patterns

Idiomatic Kotlin patterns, best practices, and conventions for building robust, efficient, and maintainable Kotlin applications with coroutines, null safety, and DSL builders. Use when writing or reviewing Kotlin code and idiomatic structure or null safety is in question.

Get started

Get the complete skill folder, including its scripts and reference files.

·

When to use this skill

Use Kotlin Patterns when an AI agent needs a reusable SKILL.md workflow for this job: Idiomatic Kotlin patterns, best practices, and conventions for building robust, efficient, and maintainable Kotlin applications with coroutines, null safety, and DSL builders. Use when writing or reviewing Kotlin code and idiomatic structure or null safety is in question.

When not to use it

Skip Kotlin Patterns when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/kotlin-patterns
# Save SKILL.md to ~/.claude/skills/kotlin-patterns/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/kotlin-patterns/SKILL.md. For a shared project, commit the folder at .claude/skills/kotlin-patterns/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Kotlin Patterns skill for this task: Writing new Kotlin code. Confirm any required inputs or files before making changes.

What supports this recommendation?

83/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
92/100
Practical detail
92/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Kotlin Development Patterns

Idiomatic Kotlin patterns and best practices for building robust, efficient, and maintainable applications.

## When to Use

- Writing new Kotlin code - Reviewing Kotlin code - Refactoring existing Kotlin code - Designing Kotlin modules or libraries - Configuring Gradle Kotlin DSL builds

## How It Works

This skill enforces idiomatic Kotlin conventions across seven key areas: null safety using the type system and safe-call operators, immutability via `val` and `copy()` on data classes, sealed classes and interfaces for exhaustive type hierarchies, structured concurrency with coroutines and `Flow`, extension functions for adding behaviour without inheritance, type-safe DSL builders using `@DslMarker` and lambda receivers, and Gradle Kotlin DSL for build configuration.

## Examples

**Null safety with Elvis operator:** ```kotlin fun getUserEmail(userId: String): String { val user = userRepository.findById(userId) return user?.email ?: "[email protected]" } ```

**Sealed class for exhaustive results:** ```kotlin sealed class Result<out T> { data class Success<T>(val data: T) : Result<T>() data class Failure(val error: AppError) : Result<Nothing>() data object Loading : Result<Nothing>() } ```

**Structured concurrency with async/await:** ```kotlin suspend fun fetchUserWithPosts(userId: String): UserProfile = coroutineScope { val user = async { userService.getUser(userId) } val posts = async { postService.getUserPosts(userId) } UserProfile(user = user.await(), posts = posts.await()) } ```

## Core Principles

### 1. Null Safety

Kotlin's type system distinguishes nullable and non-nullable types. Leverage it fully.

```kotlin // Good: Use non-nullable types by default fun getUser(id: String): User { return userRepository.findById(id) ?: throw UserNotFoundException("User $id not found") }

// Good: Safe calls and Elvis operator fun getUserEmail(userId: String): String { val user = userRepository.findById(userId) return user?.email ?: "[email protected]" }

// Bad: Force-unwrapping nullable types fun getUserEmail(userId: String): String { val user = userRepository.findById(userId) return user!!.email // Throws NPE if null } ```

### 2. Immutability by Default

Prefer `val` over `var`, immutable collections over mutable ones.

```kotlin // Good: Immutable data data class User( val id: String, val name: String, val email: String, )

// Good: Transform with copy() fun updateEmail(user: User, newEmail: String): User = user.copy(email = newEmail)

// Good: Immutable collections val users: List<User> = listOf(user1, user2) val filtered = users.filter { it.email.isNotBlank() }

// Bad: Mutable state var currentUser: User? = null // Avoid mutable global state val mutableUsers = mutableListOf<User>() // Avoid unless truly needed ```

### 3. Expression Bodies and Single-Expression Functions

Use expression bodies for concise, readable functions.

```kotlin // Good: Expression body fun isAdult(age: Int): Boolean = age >= 18

fun formatFullName(first: String, last: String): String = "$first $last".trim()

fun User.displayName(): String = name.ifBlank { email.substringBefore('@') }

// Good: When as expression fun statusMessage(code: Int): String = when (code) { 200 -> "OK" 404 -> "Not Found" 500 -> "Internal Server Error" else -> "Unknown status: $code" }

// Bad: Unnecessary block body fun isAdult(age: Int): Boolean { return age >= 18 } ```

### 4. Data Classes for Value Objects

Use data classes for types that primarily hold data.

```kotlin // Good: Data class with copy, equals, hashCode, toString data class CreateUserRequest( val name: String, val email: String, val role: Role = Role.USER, )

// Good: Value class for type safety (zero overhead at runtime) @JvmInline value class UserId(val value: String) { init { require(value.isNotBlank()) { "UserId cannot be blank" } } }

@JvmInline value class Email(val value: String) { init { require('@' in value) { "Invalid email: $value" } } }

fun getUser(id: UserId): User = userRepository.findById(id) ```

## Sealed Classes and Interfaces

### Modeling Restricted Hierarchies

```kotlin // Good: Sealed class for exhaustive when sealed class Result<out T> { data class Success<T>(val data: T) : Result<T>() data class Failure(val error: AppError) : Result<Nothing>() data object Loading : Result<Nothing>() }

fun <T> Result<T>.getOrNull(): T? = when (this) { is Result.Success -> data is Result.Failure -> null is Result.Loading -> null }

fun <T> Result<T>.getOrThrow(): T = when (this) { is Result.Success -> data is Result.Failure -> throw error.toException() is Result.Loading -> throw IllegalStateException("Still loading") } ```

### Sealed Interfaces for API Responses

```kotlin sealed interface ApiError { val message: String

data class NotFound(override val message: String) : ApiError data class Unauthorized(override val message: String) : ApiError data class Validation( override val message: String, val field: String, ) : ApiError data class Internal( override val message: String, val cause: Throwable? = null, ) : ApiError }

fun ApiError.toStatusCode(): Int = when (this) { is ApiError.NotFound -> 404 is ApiError.Unauthorized -> 401 is ApiError.Validation -> 422 is ApiError.Internal -> 500 } ```

## Scope Functions

### When to Use Each

```kotlin // let: Transform nullable or scoped result val length: Int? = name?.let { it.trim().length }

// apply: Configure an object (returns the object) val user = User().apply { name = "Alice" email = "[email protected]" }

// also: Side effects (returns the object) val user = createUser(request).also { logger.info("Created user: ${it.id}") }

// run: Execute a block with receiver (returns result) val result = connection.run { prepareStatement(sql) executeQuery() }

// with: Non-extension form of run val csv = with(StringBuilder()) { appendLine("name,email") users.forEach { appendLine("${it.name},${it.email}") } toString() } ```

### Anti-Patterns

```kotlin // Bad: Nesting scope functions user?.let { u -> u.address?.let { addr -> addr.city?.let { city -> println(city) // Hard to read } } }

// Good: Chain safe calls instead val city = user?.address?.city city?.let { println(it) } ```

## Extension Functions

### Adding Functionality Without Inheritance

```kotlin // Good: Domain-specific extensions fun String.toSlug(): String = lowercase() .replace(Regex("[^a-z0-9\\s-]"), "") .replace(Regex("\\s+"), "-") .trim('-')

fun Instant.toLocalDate(zone: ZoneId = ZoneId.systemDefault()): LocalDate = atZone(zone).toLocalDate()

// Good: Collection extensions fun <T> List<T>.second(): T = this[1]

fun <T> List<T>.secondOrNull(): T? = getOrNull(1)

// Good: Scoped extensions (not polluting global namespace) class UserService { private fun User.isActive(): Boolean = status == Status.ACTIVE && lastLogin.isAfter(Instant.now().minus(30, ChronoUnit.DAYS))

fun getActiveUsers(): List<User> = userRepository.findAll().filter { it.isActive() } } ```

## Coroutines

### Structured Concurrency

```kotlin // Good: Structured concurrency with coroutineScope suspend fun fetchUserWithPosts(userId: String): UserProfile = coroutineScope { val userDeferred = async { userService.getUser(userId) } val postsDeferred = async { postService.getUserPosts(userId) }

UserProfile( user = userDeferred.await(), posts = postsDeferred.await(), ) }

// Good: supervisorScope when children can fail independently suspend fun fetchDashboard(userId: String): Dashboard = supervisorScope { val user = async { userService.getUser(userId) } val notifications = async { notificationService.getRecent(userId) } val recommendations = async { recommendationService.getFor(userId) }

Dashboard( user = user.await(), notifications = try { notifications.await() } catch (e: CancellationException) { throw e } catch (e: Exception) { emptyList() }, recommendations = try { recommendations.await() } catch (e: CancellationException) { throw e } catch (e: Exception) { emptyList() }, ) } ```

### Flow for Reactive Streams

```kotlin // Good: Cold flow with proper error handling fun observeUsers(): Flow<List<User>> = flow { while (currentCoroutineContext().isActive) { val users = userRepository.findAll() emit(users) delay(5.seconds) } }.catch { e -> logger.error("Error observing users", e) emit(emptyList()) }

// Good: Flow operators fun searchUsers(query: Flow<String>): Flow<List<User>> = query .debounce(300.milliseconds) .distinctUntilChanged() .filter { it.length >= 2 } .mapLatest { q -> userRepository.search(q) } .catch { emit(emptyList()) } ```

### Cancellation and Cleanup

```kotlin // Good: Respect cancellation suspend fun processItems(items: List<Item>) { items.forEach { item -> ensureActive() // Check cancellation before expensive work processItem(item) } }

// Good: Cleanup with try/finally suspend fun acquireAndProcess() { val resource = acquireResource() try { resource.process() } finally { withContext(NonCancellable) { resource.release() // Always release, even on cancellation } } } ```

## Delegation

### Property Delegation

```kotlin // Lazy initialization val expensiveData: List<User> by lazy { userRepository.findAll() }

// Observable property var name: String by Delegates.observable("initial") { _, old, new -> logger.info("Name changed from '$old' to '$new'") }

// Map-backed properties class Config(private val map: Map<String, Any?>) { val host: String by map val port: Int by map val debug: Boolean by map }

val config = Config(mapOf("host" to "localhost", "port" to 8080, "debug" to true)) ```

### Interface Delegation

```kotlin // Good: Delegate interface implementation class LoggingUserRepository( private val delegate: UserRepository, private val logger: Logger, ) : UserRepository by delegate { // Only override what you need to add logging to override suspend fun findById(id: String): User? { logger.info("Finding user by id: $id") return delegate.findById(id).also { logger.info("Found user: ${it?.name ?: "null"}") } } } ```

## DSL Builders

### Type-Safe Builders

```kotlin // Good: DSL with @DslMarker @DslMarker annotation class HtmlDsl

@HtmlDsl class HTML { private val children = mutableListOf<Element>()

fun head(init: Head.() -> Unit) { children += Head().apply(init) }

fun body(init: Body.() -> Unit) { children += Body().apply(init) }

override fun toString(): String = children.joinToString("\n") }

fun html(init: HTML.() -> Unit): HTML = HTML().apply(init)

// Usage val page = html { head { title("My Page") } body { h1("Welcome") p("Hello, World!") } } ```

### Configuration DSL

```kotlin data class ServerConfig( val host: String = "0.0.0.0", val port: Int = 8080, val ssl: SslConfig? = null, val database: DatabaseConfig? = null, )

data class SslConfig(val certPath: String, val keyPath: String) data class DatabaseConfig(val url: String, val maxPoolSize: Int = 10)

class ServerConfigBuilder { var host: String = "0.0.0.0" var port: Int = 8080 private var ssl: SslConfig? = null private var database: DatabaseConfig? = null

fun ssl(certPath: String, keyPath: String) { ssl = SslConfig(certPath, keyPath) }

fun database(url: String, maxPoolSize: Int = 10) { database = DatabaseConfig(url, maxPoolSize) }

fun build(): ServerConfig = ServerConfig(host, port, ssl, database) }

fun serverConfig(init: ServerConfigBuilder.() -> Unit): ServerConfig = ServerConfigBuilder().apply(init).build()

// Usage val config = serverConfig { host = "0.0.0.0" port = 443 ssl("/certs/cert.pem", "/certs/key.pem") database("jdbc:postgresql://localhost:5432/mydb", maxPoolSize = 20) } ```

## Sequences for Lazy Evaluation

```kotlin // Good: Use sequences for large collections with multiple operations val result = users.asSequence() .filter { it.isActive } .map { it.email } .filter { it.endsWith("@company.com") } .take(10) .toList()

// Good: Generate infinite sequences val fibonacci: Sequence<Long> = sequence { var a = 0L var b = 1L while (true) { yield(a) val next = a + b a = b b = next } }

val first20 = fibonacci.take(20).toList() ```

## Gradle Kotlin DSL

### build.gradle.kts Configuration

```kotlin // Check for latest versions: https://kotlinlang.org/docs/releases.html plugins { kotlin("jvm") version "2.3.10" kotlin("plugin.serialization") version "2.3.10" id("io.ktor.plugin") version "3.4.0" id("org.jetbrains.kotlinx.kover") version "0.9.7" id("io.gitlab.arturbosch.detekt") version "1.23.8" }

group = "com.example" version = "1.0.0"

kotlin { jvmToolchain(21) }

dependencies { // Ktor implementation("io.ktor:ktor-server-core:3.4.0") implementation("io.ktor:ktor-server-netty:3.4.0") implementation("io.ktor:ktor-server-content-negotiation:3.4.0") implementation("io.ktor:ktor-serialization-kotlinx-json:3.4.0")

// Exposed implementation("org.jetbrains.exposed:exposed-core:1.0.0") implementation("org.jetbrains.exposed:exposed-dao:1.0.0") implementation("org.jetbrains.exposed:exposed-jdbc:1.0.0") implementation("org.jetbrains.exposed:exposed-kotlin-datetime:1.0.0")

// Koin implementation("io.insert-koin:koin-ktor:4.2.0")

// Coroutines implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2")

// Testing testImplementation("io.kotest:kotest-runner-junit5:6.1.4") testImplementation("io.kotest:kotest-assertions-core:6.1.4") testImplementation("io.kotest:kotest-property:6.1.4") testImplementation("io.mockk:mockk:1.14.9") testImplementation("io.ktor:ktor-server-test-host:3.4.0") testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.10.2") }

tasks.withType<Test> { useJUnitPlatform() }

detekt { config.setFrom(files("config/detekt/detekt.yml")) buildUponDefaultConfig = true } ```

## Error Handling Patterns

### Result Type for Domain Operations

```kotlin // Good: Use Kotlin's Result or a custom sealed class suspend fun createUser(request: CreateUserRequest): Result<User> = runCatching { require(request.name.isNotBlank()) { "Name cannot be blank" } require('@' in request.email) { "Invalid email format" }

val user = User( id = UserId(UUID.randomUUID().toString()), name = request.name, email = Email(request.email), ) userRepository.save(user) user }

// Good: Chain results val displayName = createUser(request) .map { it.name } .getOrElse { "Unknown" } ```

### require, check, error

```kotlin // Good: Preconditions with clear messages fun withdraw(account: Account, amount: Money): Account { require(amount.value > 0) { "Amount must be positive: $amount" } check(account.balance >= amount) { "Insufficient balance: ${account.balance} < $amount" }

return account.copy(balance = account.balance - amount) } ```

## Collection Operations

### Idiomatic Collection Processing

```kotlin // Good: Chained operations val activeAdminEmails: List<String> = users .filter { it.role == Role.ADMIN && it.isActive } .sortedBy { it.name } .map { it.email }

// Good: Grouping and aggregation val usersByRole: Map<Role, List<User>> = users.groupBy { it.role }

val oldestByRole: Map<Role, User?> = users.groupBy { it.role } .mapValues { (_, users) -> users.minByOrNull { it.createdAt } }

// Good: Associate for map creation val usersById: Map<UserId, User> = users.associateBy { it.id }

// Good: Partition for splitting val (active, inactive) = users.partition { it.isActive } ```

## Quick Reference: Kotlin Idioms

| Idiom | Description | |-------|-------------| | `val` over `var` | Prefer immutable variables | | `data class` | For value objects with equals/hashCode/copy | | `sealed class/interface` | For restricted type hierarchies | | `value class` | For type-safe wrappers with zero overhead | | Expression `when` | Exhaustive pattern matching | | Safe call `?.` | Null-safe member access | | Elvis `?:` | Default value for nullables | | `let`/`apply`/`also`/`run`/`with` | Scope functions for clean code | | Extension functions | Add behavior without inheritance | | `copy()` | Immutable updates on data classes | | `require`/`check` | Precondition assertions | | Coroutine `async`/`await` | Structured concurrent execution | | `Flow` | Cold reactive streams | | `sequence` | Lazy evaluation | | Delegation `by` | Reuse implementation without inheritance |

## Anti-Patterns to Avoid

```kotlin // Bad: Force-unwrapping nullable types val name = user!!.name

// Bad: Platform type leakage from Java fun getLength(s: String) = s.length // Safe fun getLength(s: String?) = s?.length ?: 0 // Handle nulls from Java

// Bad: Mutable data classes data class MutableUser(var name: String, var email: String)

// Bad: Using exceptions for control flow try { val user = findUser(id) } catch (e: NotFoundException) { // Don't use exceptions for expected cases }

// Good: Use nullable return or Result val user: User? = findUserOrNull(id)

// Bad: Ignoring coroutine scope GlobalScope.launch { /* Avoid GlobalScope */ }

// Good: Use structured concurrency coroutineScope { launch { /* Properly scoped */ } }

// Bad: Deeply nested scope functions user?.let { u -> u.address?.let { a -> a.city?.let { c -> process(c) } } }

// Good: Direct null-safe chain user?.address?.city?.let { process(it) } ```

**Remember**: Kotlin code should be concise but readable. Leverage the type system for safety, prefer immutability, and use coroutines for concurrency. When in doubt, let the compiler help you.

Intended uses

  • Writing new Kotlin code
  • Reviewing Kotlin code
  • Refactoring existing Kotlin code
  • Designing Kotlin modules or libraries
  • Configuring Gradle Kotlin DSL builds

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.