AutoGineer
Generated banner for Kotlin Tooling Java To Kotlin
Generated logo for Kotlin Tooling Java To Kotlin

Kotlin Tooling Java To Kotlin

JetBrainsOfficialCreated by JetBrainsDistributed by JetBrains

  • Skill
  • Workflow
  • Software development
  • Apache-2.0
  • No issues found
Download ZIP

From the author

Use when converting Java source files to idiomatic Kotlin, when user mentions "java to kotlin", "j2k", "convert java", "migrate java to kotlin", or when working with .java files that need to become .kt files. Handles framework-aware conversion for Spring, Lombok, Hibernate, Jackson, Micronaut, Quarkus, Dagger/Hilt, RxJava, JUnit, Guice, Retrofit, and Mockito.
— the description by JetBrains

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

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/jetbrains/kotlin-tooling-java-to-kotlin/download

  2. Unzip 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 prefixFramework 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:

  1. Faithful 1:1 translation — exact semantics preserved

  2. Nullability & mutability audit — val/var, nullable types

  3. Collection type conversion — Java mutable → Kotlin types

  4. 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.kt

If 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):

  1. List all .java files in the target scope

  2. Sort 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

  3. Convert one file at a time — apply the full workflow (steps 0-4) for each

  4. Track progress — report which files are done, which remain

  5. 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 / @JvmOverloads usage

  • Checked exceptions and @Throws

  • Wildcard generics → Kotlin variance

Files

references/frameworks/HIBERNATE.md

Hibernate / JPA Conversion Guide

When This Applies

Detected when imports match any of:

  • javax.persistence.*

  • jakarta.persistence.*

  • org.hibernate.*

Critical Rules

  1. Do NOT use data classes for JPA entities. Data classes generate equals/hashCode based on all properties, which breaks Hibernate's identity semantics and proxy creation.

  2. Keep entity classes open. Hibernate creates proxies via subclassing. Kotlin classes are final by default, so you must use open explicitly (or use the allopen compiler plugin with JPA annotation support).

  3. Provide a no-argument constructor if Hibernate requires one for proxy creation. Use a secondary constructor or default values for all primary constructor parameters.

  4. Annotation site targets matter:

    • @Id, @Column, @GeneratedValue on fields → use @field:Id, @field:Column, etc. in Kotlin, OR place annotations on constructor parameters with @field: site target.

    • @ManyToOne, @OneToMany, @JoinColumn → same @field: targeting.

  5. Lazy loading considerations: @ManyToOne(fetch = FetchType.LAZY) requires the entity class to be open for proxy creation. @OneToMany with lazy collections work with Kotlin's MutableList.

  6. @Embeddable classes: Can be data classes (they don't need proxies).

  7. @MappedSuperclass: Must be open abstract class in Kotlin.

Examples

Example 1: JPA Entity with @Id, @Column, and Relationships

Java:

@Entity
@Table(name = "users")
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(name = "username", nullable = false, unique = true)
    private String username;

    @Column(name = "email")
    private String email;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "department_id")
    private Department department;

    protected User() {}

    public User(String username, String email, Department department) {
        this.username = username;
        this.email = email;
        this.department = department;
    }

    public Long getId() { return id; }
    public String getUsername() { return username; }
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
    public Department getDepartment() { return department; }
    public void setDepartment(Department department) { this.department = department; }
}

Kotlin:

@Entity
@Table(name = "users")
open class User(

    @field:Column(name = "username", nullable = false, unique = true)
    open val username: String,

    @field:Column(name = "email")
    open var email: String? = null,

    @field:ManyToOne(fetch = FetchType.LAZY)
    @field:JoinColumn(name = "department_id")
    open var department: Department? = null

) {
    @field:Id
    @field:GeneratedValue(strategy = GenerationType.IDENTITY)
    open var id: Long? = null
        protected set

    protected constructor() : this(username = "")
}
Example 2: @Embeddable Value Object

Java:

@Embeddable
public class Address {

    @Column(name = "street")
    private String street;

    @Column(name = "city")
    private String city;

    @Column(name = "zip_code")
    private String zipCode;

    protected Address() {}

    public Address(String street, String city, String zipCode) {
        this.street = street;
        this.city = city;
        this.zipCode = zipCode;
    }

    public String getStreet() { return street; }
    public String getCity() { return city; }
    public String getZipCode() { return zipCode; }
}

Kotlin:

@Embeddable
data class Address(

    @field:Column(name = "street")
    val street: String = "",

    @field:Column(name = "city")
    val city: String = "",

    @field:Column(name = "zip_code")
    val zipCode: String = ""
)

@Embeddable classes can safely be data classes because Hibernate does not proxy them. Default values satisfy the no-arg constructor requirement.

Example 3: Entity with @ManyToOne and @OneToMany

Java:

@Entity
@Table(name = "departments")
public class Department {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(name = "name", nullable = false)
    private String name;

    @OneToMany(mappedBy = "department", cascade = CascadeType.ALL, orphanRemoval = true)
    private List<User> users = new ArrayList<>();

    protected Department() {}

    public Department(String name) {
        this.name = name;
    }

    public Long getId() { return id; }
    public String getName() { return name; }
    public List<User> getUsers() { return users; }

    public void addUser(User user) {
        users.add(user);
        user.setDepartment(this);
    }

    public void removeUser(User user) {
        users.remove(user);
        user.setDepartment(null);
    }
}

Kotlin:

@Entity
@Table(name = "departments")
open class Department(

    @field:Column(name = "name", nullable = false)
    open val name: String = ""

) {
    @field:Id
    @field:GeneratedValue(strategy = GenerationType.IDENTITY)
    open var id: Long? = null
        protected set

    @field:OneToMany(mappedBy = "department", cascade = [CascadeType.ALL], orphanRemoval = true)
    open val users: MutableList<User> = mutableListOf()

    protected constructor() : this(name = "")

    fun addUser(user: User) {
        users.add(user)
        user.department = this
    }

    fun removeUser(user: User) {
        users.remove(user)
        user.department = null
    }
}

Key points in this example:

  • cascade array syntax uses Kotlin's [CascadeType.ALL] instead of Java's {CascadeType.ALL}.

  • The collection is typed as MutableList to allow Hibernate to manage the relationship.

  • The class and its properties are open so Hibernate can create proxies.

  • The no-arg constructor delegates to the primary constructor with default values.

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 or JetBrains.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download kotlin-tooling-java-to-kotlin.zip