kotlin-tooling-java-to-kotlin
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.
- Installs
- 2K
- Last 24h
- +15
- Trending rank
- #7078
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/kotlin/kotlin-agent-skills --skill kotlin-tooling-java-to-kotlin- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads kotlin-tooling-java-to-kotlin automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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.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):
- List all
.javafiles in the target scope - 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
- 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/@JvmOverloadsusage- Checked exceptions and
@Throws - Wildcard generics → Kotlin variance
FAQ
What does the kotlin-tooling-java-to-kotlin skill do?
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.
How do I install kotlin-tooling-java-to-kotlin?
Run npx skills add https://github.com/kotlin/kotlin-agent-skills --skill kotlin-tooling-java-to-kotlin in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/kotlin-tooling-java-to-kotlin/ (personal) or .claude/skills/kotlin-tooling-java-to-kotlin/ (project).
Which AI agents can use kotlin-tooling-java-to-kotlin?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is kotlin-tooling-java-to-kotlin safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains kotlin-tooling-java-to-kotlin?
It is published by kotlin in kotlin/kotlin-agent-skills, and it is an official skill from the maker of the technology it covers. It has 1,994 recorded installs.
More from kotlin/kotlin-agent-skills
kotlin-tooling-agp9-migration
kotlin/kotlin-agent-skills
Migrates Kotlin Multiplatform (KMP) projects to Android Gradle Plugin 9.0+. Handles plugin replacement (com.android.kotlin.multiplatform.library), module splitting, DSL migration, and the new default project structure. Use when upgrading AGP, when build fails due to KMP+AGP incompatibility, or when the user mentions AGP 9.0, android multiplatform plugin, KMP migration, or com.android.kotlin.multiplatform.library.
kotlin-tooling-cocoapods-spm-migration
kotlin/kotlin-agent-skills
Migrate KMP projects from CocoaPods (kotlin("native.cocoapods")) to Swift Package Manager (swiftPMDependencies DSL) — replaces pod() with swiftPackage(), transforms cocoapods. imports to swiftPMImport., and reconfigures the Xcode project.
kotlin-backend-jpa-entity-mapping
kotlin/kotlin-agent-skills
Model Kotlin persistence code correctly for Spring Data JPA and Hibernate. Covers entity design, identity and equality, uniqueness constraints, relationships, fetch plans, and common ORM (Object-Relational Mapping) traps specific to Kotlin. Use when creating or reviewing JPA (Java Persistence API) entities, diagnosing N+1 or LazyInitializationException, placing indexes and uniqueness rules, or preventing Kotlin-specific bugs such as data class entities and broken equals/hashCode.
kotlin-tooling-immutable-collections-0-5-x-migration
kotlin/kotlin-agent-skills
Migrate Kotlin (and Java) code from kotlinx.collections.immutable 0.3.x / 0.4.x to the latest 0.5.x. The 0.5.x line renames every copy-returning method on PersistentList / PersistentMap / PersistentSet / PersistentCollection to a participial form per KEEP-0459 (add→adding, removeAt→removingAt, set→replacingAt, put→putting, clear→cleared, …) and deprecates the old names (WARNING, with ReplaceWith). Driven by the compiler: bump the version, recompile, and apply the rename each deprecation warning names. Use when the user mentions kotlinx.collections.immutable 0.5.x, PersistentList migration, "Use adding() instead", KEEP-0459, or sees deprecation warnings from kotlinx.collections.immutable.
kotlin-tooling-native-build-performance
kotlin/kotlin-agent-skills
Diagnoses and fixes slow Kotlin/Native compilation and linking in Kotlin Multiplatform projects that target iOS. Use when the user reports slow iOS or shared-framework builds, long linkDebug/linkRelease or XCFramework tasks, cold CI builds that re-download the Kotlin/Native toolchain, KSP or other generated code on the native path, transitiveExport usage, or asks for a local-development versus CI build performance plan.
kotlin-tooling-kotlin-toolchain
kotlin/kotlin-agent-skills
Open the skill to read its SKILL.md instructions.
Popular mobile skills
design-mobile-apps
designed-by-ai/skills
Design mobile app screens with Sleek, edit Sleek projects, and implement their designs in React Native or HTML.
ios-design
uizze.sh
Design and review iOS UI/UX for iPhone apps in SwiftUI, UIKit, or React Native. Use for mobile app design, screen redesigns, navigation flows, typography, forms, keyboard and safe-area layout, and accessibility checks. Apply Apple Human Interface Guidelines and consult real product references through the optional Uizze connection.
vercel-react-native-skills
vercel-labs/agent-skills
React Native and Expo best practices for building performant mobile apps. Use when building React Native components, optimizing list performance, implementing animations, or working with native modules. Triggers on tasks involving React Native, Expo, mobile performance, or native platform APIs.
animate-expo
emilkowalski/skills
Build animations in React Native and Expo, making the decisions in the order that determines whether they feel right — should it animate, which thread it runs on, which properties, spring or timing, how the gesture hands off, how it degrades. Writes the implementation with Reanimated, Gesture Handler, Expo Router and expo-haptics. Use when animating anything in an Expo app, adding gestures, sheets, screen transitions, press feedback or haptics, or fixing motion that stutters on device. For web animation use animate.
xcode-project-setup
firebase/agent-skills
Safely modifies Xcode projects (.pbxproj) to add Swift Packages and link files. Use this skill whenever an iOS project needs dependencies installed (e.g. Firebase, Alamofire).
firebase-remote-config-basics
firebase/agent-skills
Manages Firebase Remote Config templates, feature flags, loading strategies, and SDKs (Android, iOS). Use when downloading/deploying remoteconfig JSON templates, managing version history/feature flags, setting in-app defaults, fetchAndActivate(), real-time listeners, or SDK setup. Don't use for Firebase Hosting, Auth, Firestore, Data Connect, Crashlytics, or App Hosting.