kotlin-api-consultant
Skill67 starsChanged 47 days agoApache-2.0View on GitHub
Checks Kotlin compiler API usage against the Kotlin versions Fakt supports — which path runs on which compiler, how compat shims are written, how to verify across versions, and how to bump Kotlin. Use when calling a new FIR/IR/compiler-plugin API, seeing NoSuchMethodError, NoSuchFieldError or NoClassDefFoundError from compiler classes, bumping the Kotlin version, or checking whether an API exists in the minimum supported Kotlin. Make sure to use this skill whenever compiler plugin code starts using a Kotlin compiler API it didn't use before — these APIs change between Kotlin releases and a break only shows up on an older supported version.
In this repository10 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- bdd-test-runnerSkill
- codegenSkill
- commitSkill
- compilationSkill
- feature-optionSkill
- issue-creatorSkill
- prSkill
- sample-scaffolderSkill
- skill-creatorSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 24
Look the API up at the minimum and latest supported versions in the Kotlin repository (tags like v2.2.0), not just the version on the build …
- Very specific: line 32
When the API differs across the range, isolate it in a small private helper suffixed Compat, next to its call site.
- Distinctive: line 37
Keep the shim's KDoc explaining which versions differ, so it can be deleted when the minimum moves past them.
- Very specific: line 50
Update kotlin in gradle/libs.versions.toml and FAKT_KOTLIN_VERSION (nothing checks that they match), add a samples/compat/kotlin-<version>/ …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Kotlin API Consultant
Keeps Fakt's compiler plugin working across every Kotlin version in the support matrix.
Instructions
1. Know Which Compiler Runs the Code
- Supported range: the matrix in
docs/compatibility.mdis the source of truth (minimum and latest tested). - Build:
compiler/compilescompileOnlyagainstkotlin-compiler-embeddableat thekotlinversion ingradle/libs.versions.toml. - Default FIR path (
FaktGenerateTaskworker): runs on the compiler Fakt pins —FAKT_KOTLIN_VERSIONingradle-plugin/.../FaktGradleSubplugin.kt. The user's Kotlin version doesn't matter here. - Legacy in-process path (Native mains,
LEGACY, or-Pfakt.useExperimentalGenerateTask=false): runs inside the user's own compiler, which can be as old as the minimum supported version.
So code reachable from the in-process path (the ir/ package, FaktCompilerPluginRegistrar, and the FIR checkers it registers) must only use APIs present in every supported version.
2. Check the API Across the Range
Look the API up at the minimum and latest supported versions in the Kotlin repository (tags like v2.2.0), not just the version on the build classpath. Signs of trouble:
- The symbol doesn't exist at the minimum version, or its signature differs
@Deprecated(level = ERROR), or a replacement API introduced after the minimum- An opt-in annotation (
@ExperimentalCompilerApi,@UnsafeApi) the module doesn't already opt into
3. Bridge Differences with a Compat Shim
When the API differs across the range, isolate it in a small private helper suffixed Compat, next to its call site. Existing patterns:
FaktCompilerPluginRegistrar.registerExtensionCompat— callsregisterExtensionreflectively; Kotlin 2.4.0 widened its receiver type, and a direct call compiled against 2.4 fails withNoClassDefFoundErroron 2.2–2.3FirToIrTransformer.extensionReceiverParameterCompat— reads the extension receiver from the unifiedparameterslist instead of the deprecatedextensionReceiverParameter
Keep the shim's KDoc explaining which versions differ, so it can be deleted when the minimum moves past them.
4. Verify on Every Supported Version
make test-compat-all # publish-local + jvmTest on every samples/compat/kotlin-*/
make test-compat-2.2.0 # one versionCI runs the same matrix (version list in .github/workflows/development.yml) through .github/actions/test-compat-samples.
5. Bumping Kotlin
Update kotlin in gradle/libs.versions.toml and FAKT_KOTLIN_VERSION (nothing checks that they match), add a samples/compat/kotlin-<version>/ sample and its entry in development.yml, and update docs/compatibility.md.
Related Skills
compilation— Diagnose the build failure that surfaced the API problemcodegen— Code generation, which doesn't touch compiler APIs
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

