Kotlin Tooling Java To Kotlin
JetBrainsOfficialCreated by JetBrainsDistributed by JetBrains
- Skill
- Workflow
- Software development
- Apache-2.0
- No issues found
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
This skill provides a disciplined, four-step methodology for migrating Java code to Kotlin. It includes framework-aware guidance for common JVM libraries such as Spring, Hibernate, Lombok, and others. The process emphasizes maintaining behavioral parity through a chain-of-thought approach, checking five specific invariants at each stage to ensure the resulting Kotlin code is idiomatic, safe, and maintainable.
What it does
- Scans Java files to detect and load relevant framework-specific conversion guides.
- Executes a four-step conversion process: 1:1 translation, nullability audit, collection conversion, and idiomatic transformation.
- Validates code against five core invariants at every step to prevent regressions.
- Provides instructions for preserving Git history during file renaming.
- Offers a checklist for verifying compilation and behavioral consistency.
- Handles common pitfalls like keyword conflicts, SAM ambiguity, and platform types.
When to use it
- When migrating existing Java projects or individual files to Kotlin.
- When you need to ensure converted code follows idiomatic Kotlin patterns.
- When working with Java codebases that utilize frameworks like Spring, Hibernate, or Dagger.
- When you need to maintain Git blame history while refactoring Java to Kotlin.
Advantages
- Reduces manual effort by providing a systematic, repeatable conversion workflow.
- Ensures framework-specific idioms are applied correctly through targeted reference guides.
- Maintains code integrity by enforcing strict invariants throughout the transformation.
- Minimizes common interop issues by addressing platform types and JVM annotations.
Usage examples
- “Convert this Java file to idiomatic Kotlin.”
- The agent will scan the file for frameworks, perform the four-step conversion, and output the resulting .kt file.
- “Migrate my Java project to Kotlin.”
- The agent will list all .java files, sort them by dependency order, and perform a batch conversion following the defined workflow.
Install
Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/jetbrains/kotlin-tooling-java-to-kotlin/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip kotlin-tooling-java-to-kotlin.zip -d .agents/skills
Documentation by JetBrains
Java to Kotlin Conversion
Convert Java source files to idiomatic Kotlin using a disciplined 4-step conversion methodology with 5 invariants checked at each step. Supports framework-aware conversion that handles annotation site targets, library idioms, and API preservation.
Workflow
digraph j2k_workflow {
rankdir=TB;
"User specifies files" -> "Step 0: Scan & Detect";
"Step 0: Scan & Detect" -> "Load framework guides";
"Load framework guides" -> "Step 1: Convert";
"Step 1: Convert" -> "Step 2: Write .kt";
"Step 2: Write .kt" -> "Step 3: Git rename";
"Step 3: Git rename" -> "Step 4: Verify";
"Step 4: Verify" -> "Next file?" [label="pass"];
"Step 4: Verify" -> "Fix issues" [label="fail"];
"Fix issues" -> "Step 1: Convert";
"Next file?" -> "Step 0: Scan & Detect" [label="batch: yes"];
"Next file?" -> "Done" [label="no more files"];
}Step 0: Scan & Detect Frameworks
Before converting, scan the Java file's import statements to detect which frameworks are in use. Load ONLY the matching framework reference files to keep context focused.
Framework Detection Table
| Import prefix | Framework guide |
|---|---|
org.springframework.* | SPRING.md |
lombok.* | LOMBOK.md |
javax.persistence.*, jakarta.persistence.*, org.hibernate.* | HIBERNATE.md |
com.fasterxml.jackson.* | JACKSON.md |
io.micronaut.* | MICRONAUT.md |
io.quarkus.*, javax.enterprise.*, jakarta.enterprise.* | QUARKUS.md |
dagger.*, dagger.hilt.* | DAGGER-HILT.md |
io.reactivex.*, rx.* | RXJAVA.md |
org.junit.*, org.testng.* | JUNIT.md |
com.google.inject.* | GUICE.md |
retrofit2.*, okhttp3.* | RETROFIT.md |
org.mockito.* | MOCKITO.md |
If javax.inject.* is detected, check for Dagger/Hilt vs Guice by looking for other
imports from those frameworks. If ambiguous, load both guides.
Step 1: Convert
Apply the conversion methodology from CONVERSION-METHODOLOGY.md.
This is a 4-step chain-of-thought process:
Faithful 1:1 translation — exact semantics preserved
Nullability & mutability audit — val/var, nullable types
Collection type conversion — Java mutable → Kotlin types
Idiomatic transformations — properties, string templates, lambdas
Five invariants are checked after each step. If any invariant is violated, revert to the previous step and redo.
Apply any loaded framework-specific guidance during step 4 (idiomatic transformations).
Step 2: Write Output
Write the converted Kotlin code to a .kt file with the same name as the original
Java file, in the same directory.
Step 3: Preserve Git History
To preserve git blame history, use a two-phase approach:
# Phase 1: Rename (creates rename tracking)
git mv src/main/java/com/example/Foo.java src/main/kotlin/com/example/Foo.kt
git commit -m "Rename Foo.java to Foo.kt"
# Phase 2: Replace content (tracked as modification, not new file)
# Write the converted Kotlin content to Foo.kt
git commit -m "Convert Foo from Java to Kotlin"If the project keeps Java and Kotlin in the same source root (e.g., src/main/java/),
rename in place:
git mv src/main/java/com/example/Foo.java src/main/java/com/example/Foo.ktIf the project does not use Git, simply write the .kt file and delete the .java file.
Step 4: Verify
After conversion, verify using checklist.md:
Attempt to compile the converted file
Run existing tests
Check annotation site targets
Confirm no behavioral changes
Batch Conversion
When converting multiple files (a directory or package):
List all
.javafiles in the target scopeSort by dependency order — convert leaf dependencies first (files that don't import other files in the conversion set), then work up to files that depend on them
Convert one file at a time — apply the full workflow (steps 0-4) for each
Track progress — report which files are done, which remain
Handle cross-references — after converting a file, update imports in other Java files if needed (e.g., if a class moved packages)
For large batches, consider converting in packages (bottom-up from leaf packages).
Common Pitfalls
See KNOWN-ISSUES.md for:
Kotlin keyword conflicts (
when,in,is,object)SAM conversion ambiguity
Platform types from Java interop
@JvmStatic/@JvmField/@JvmOverloadsusageChecked exceptions and
@ThrowsWildcard generics → Kotlin variance
Files
- ATTRIBUTION.mdAdded by AutoGineer1023 B
- LICENSEAdded by AutoGineer10.0 KiB
- SKILL.md5.6 KiB
- assets/checklist.md2.5 KiB
- references/CONVERSION-METHODOLOGY.md9.8 KiB
- references/KNOWN-ISSUES.md9.5 KiB
- references/frameworks/DAGGER-HILT.md4.3 KiB
- references/frameworks/GUICE.md4.5 KiB
- references/frameworks/HIBERNATE.md5.9 KiB
- references/frameworks/JACKSON.md7.1 KiB
- references/frameworks/JUNIT.md5.3 KiB
- references/frameworks/LOMBOK.md6.3 KiB
- references/frameworks/MICRONAUT.md3.3 KiB
- references/frameworks/MOCKITO.md7.7 KiB
- references/frameworks/QUARKUS.md3.8 KiB
- references/frameworks/RETROFIT.md4.4 KiB
- references/frameworks/RXJAVA.md5.6 KiB
- references/frameworks/SPRING.md6.3 KiB
references/frameworks/LOMBOK.md
Lombok Conversion Guide
When This Applies
Detected when imports match lombok.*.
Core Rule
Remove ALL Lombok annotations entirely. Do not convert Lombok to Lombok — convert to idiomatic Kotlin equivalents. Lombok has no place in Kotlin code.
Annotation Conversion Table
| Lombok Annotation | Kotlin Equivalent |
|---|---|
@Getter / @Setter | Kotlin properties (val/var) — automatic |
@Data | data class with primary constructor properties |
@Value (Lombok) | data class with val properties (immutable) |
@Builder | Default parameter values, or named arguments. For complex builders, use Kotlin builder DSL |
@NoArgsConstructor | Secondary no-arg constructor, or default values for all params |
@AllArgsConstructor | Primary constructor (Kotlin default) |
@RequiredArgsConstructor | Primary constructor with only required (non-default) params |
@ToString | data class auto-generates toString, or manual override fun toString() |
@EqualsAndHashCode | data class auto-generates, or manual override fun equals/hashCode |
@Slf4j / @Log / @Log4j2 | Companion object with logger (see example below) |
@Cleanup | Kotlin's .use {} extension function |
@SneakyThrows | Kotlin has no checked exceptions — just remove it |
@Synchronized | Kotlin's @Synchronized annotation |
@With | data class .copy() method |
@Accessors(chain = true) | Kotlin's apply {} block |
Key Rules
@Slf4j — Convert to a companion object with an explicit logger:
companion object {
private val log = LoggerFactory.getLogger(MyClass::class.java)
}@Data with JPA entities — Do NOT use
data classfor JPA entities. Use regularopen classwith properties instead. Data classes break Hibernate proxies.@Builder — Prefer default parameter values. Only create an explicit builder pattern if the Java code has complex builder logic beyond simple setters.
Lombok
val— Replace with Kotlin'sval(they serve the same purpose).
Example 1: @Data Class with @Builder
Java Input
package com.acme.model;
import lombok.Builder;
import lombok.Data;
/**
* Represents a customer order with shipping details.
*/
@Data
@Builder
public class Order {
private String orderId;
private String customerName;
private int quantity;
private boolean expedited;
}Kotlin Output
package com.acme.model
/**
* Represents a customer order with shipping details.
*/
data class Order(
val orderId: String?,
val customerName: String?,
val quantity: Int = 0,
val expedited: Boolean = false
)What changed:
@Data→data classwith primary constructor properties.@Builder→ default parameter values. Callers use named arguments:Order(orderId = "123", customerName = "Alice", quantity = 2).All Lombok imports removed.
Fields become
valproperties (immutable by default; usevaronly if mutation is required by the original code).Reference types are nullable (
String?) because Java fields default tonullunless proven otherwise.
Example 2: @Slf4j Annotated Service Class
Java Input
package com.acme.service;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
/**
* Service that processes incoming payment requests.
*/
@Slf4j
@RequiredArgsConstructor
public class PaymentService {
private final PaymentGateway gateway;
private final NotificationSender notifier;
/**
* Processes a payment for the given amount.
*
* @param amount the payment amount in cents
* @return true if the payment succeeded
*/
public boolean processPayment(long amount) {
log.info("Processing payment of {} cents", amount);
try {
gateway.charge(amount);
notifier.sendConfirmation(amount);
log.info("Payment of {} cents succeeded", amount);
return true;
} catch (Exception e) {
log.error("Payment failed for amount {}", amount, e);
return false;
}
}
}Kotlin Output
package com.acme.service
import org.slf4j.LoggerFactory
/**
* Service that processes incoming payment requests.
*/
open class PaymentService(
private val gateway: PaymentGateway,
private val notifier: NotificationSender
) {
companion object {
private val log = LoggerFactory.getLogger(PaymentService::class.java)
}
/**
* Processes a payment for the given amount.
*
* @param amount the payment amount in cents
* @return true if the payment succeeded
*/
fun processPayment(amount: Long): Boolean {
log.info("Processing payment of {} cents", amount)
return try {
gateway.charge(amount)
notifier.sendConfirmation(amount)
log.info("Payment of {} cents succeeded", amount)
true
} catch (e: Exception) {
log.error("Payment failed for amount {}", amount, e)
false
}
}
}What changed:
@Slf4j→ companion object withLoggerFactory.getLogger(...).@RequiredArgsConstructor→ primary constructor withvalparameters.Lombok imports replaced with
org.slf4j.LoggerFactory.try/catchused as an expression (idiomatic Kotlin).Class is
openbecause Java classes are implicitly open.
Example 3: @Value (Lombok) Immutable Class
Java Input
package com.acme.config;
import lombok.Value;
/**
* Immutable configuration for connecting to a database.
*/
@Value
public class DatabaseConfig {
String host;
int port;
String databaseName;
boolean useSsl;
}Kotlin Output
package com.acme.config
/**
* Immutable configuration for connecting to a database.
*/
data class DatabaseConfig(
val host: String?,
val port: Int,
val databaseName: String?,
val useSsl: Boolean
)What changed:
@Value→data classwithvalproperties (all immutable).Lombok's
@Valuemakes the class final, and Kotlindata classis also final by default — so the semantics match.All Lombok imports removed.
Auto-generated
equals(),hashCode(),toString(), andcopy()come fromdata classfor free.Reference types are nullable (
String?) since the original Java fields have no nullability annotations.
Requirements and compatibility
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Needs: Needs a command-line tool
Security
No issues found by our static scan· No issues found
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Created by
- JetBrains
- Publisher
- JetBrains (Official)
- Distributed by
- JetBrains
- Source
- JetBrains/skills · kotlin-tooling-java-to-kotlin · commit 3f53782
- Licence
- Apache License 2.0 (redistribution allowed)
- LICENSE (written by AutoGineer)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
AutoGineer is not affiliated with or endorsed by JetBrains.
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download kotlin-tooling-java-to-kotlin.zip