Skip to content
cccskills
FreePublished on GitHub

kotlin-api-consultant

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.

The English summary is being prepared. Showing the original description.

rsicarelli/fakt67 stars(GitHub 67 + cccskills 0)

Run score Not tested

See how to install

Files included (1)

  • SKILL.md3.6 KB

SKILL.md (original)

Review the instructions the agent will receive before you install.

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.md is the source of truth (minimum and latest tested).
  • Build: compiler/ compiles compileOnly against kotlin-compiler-embeddable at the kotlin version in gradle/libs.versions.toml.
  • Default FIR path (FaktGenerateTask worker): runs on the compiler Fakt pins — FAKT_KOTLIN_VERSION in gradle-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 — calls registerExtension reflectively; Kotlin 2.4.0 widened its receiver type, and a direct call compiled against 2.4 fails with NoClassDefFoundError on 2.2–2.3
  • FirToIrTransformer.extensionReceiverParameterCompat — reads the extension receiver from the unified parameters list instead of the deprecated extensionReceiverParameter

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 version

CI 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 problem
  • codegen — Code generation, which doesn't touch compiler APIs

Reviews

No reviews yet. Tell others what you thought.

Comments

No login needed. Share how it worked for you, ask a question, or note where it did not run.

No comments yet. Be the first to write one.

Comments are published right away. Do not include personal information such as email addresses or phone numbers. Up to 2 URLs.

0 / 1,000 characters

This form is protected by reCAPTCHA, and the Google Privacy Policy and Terms of Service apply.

More skills from this repository

Runs BDD-compliant GIVEN-WHEN-THEN tests, validates naming compliance, and analyzes coverage. Use when running tests, checking BDD compliance, validating test patterns, or verifying that test names follow GIVEN-WHEN-THEN conventions. Make sure to use this skill whenever tests need to be executed — it validates naming compliance and catches convention violations that plain test runners miss.

The English summary is being prepared. Showing the original description.

rsicarelli/fakt67Updated Oct 23, 2026

Documents the Fakt code generation pipeline — immutable AST model, builder DSL, renderer, default value strategies, and extension functions. Use when modifying code generation, changing generated output, adding new generated patterns, understanding builders or renderers, adding a new default value strategy, or debugging generated output. Make sure to use this skill whenever generated Kotlin code needs to change — the pipeline has strict conventions (immutable AST, builder DSL, renderer separation) that must be followed even for small changes.

The English summary is being prepared. Showing the original description.

rsicarelli/fakt67Updated Oct 23, 2026

commit

Free

Creates project commits — Conventional Commits format, message quality (72 char subject, 80 char body), staged-change checks, and the AI co-author trailer. Use when committing changes, running /commit, creating commit messages, or reviewing commit message quality. Make sure to use this skill whenever a git commit is being created — it is the project's commit workflow and replaces the default one.

The English summary is being prepared. Showing the original description.

rsicarelli/fakt67Updated Oct 23, 2026

Validates compilation of generated Fakt fakes and diagnoses build failures — where fakes are generated, which path produced them, error classification, and root cause analysis. Use when compilation fails, generated code has errors, no fakes were generated, validating changes compile before committing, or checking if generated code is valid. Make sure to use this skill whenever a build error mentions generated fakes or the Fakt plugin — even if the root cause might be elsewhere, this skill's error classification pinpoints the actual source.

The English summary is being prepared. Showing the original description.

rsicarelli/fakt67Updated Oct 23, 2026

Guides step-by-step through all 11 touchpoints for adding a new @Fake annotation option (like mutability or callHistory). Covers annotation enum, CLI processor, Gradle plugin, FIR metadata, FIR translator, the shared FakeDeclaration model, and code generators. Use when adding a new option to @Fake, adding a new enum to the annotation, making something configurable per-interface, implementing a new compiler plugin feature flag, adding a new Gradle extension property, or extending the three-tier resolution (annotation → plugin → default). Make sure to use this skill whenever a change touches more than one layer of the option pipeline, even for small additions like a new enum value.

The English summary is being prepared. Showing the original description.

rsicarelli/fakt67Updated Oct 23, 2026

Creates well-structured GitHub issues using gh CLI with auto-detected project context (version, platform, module). Supports bug reports, feature requests, and internal tasks following repo templates. Use when creating a GitHub issue, reporting a bug, requesting a feature, logging a task, documenting a TODO as an issue, or recording a bug found during development. Make sure to use this skill whenever an issue needs to be created — it auto-detects project context and applies the correct template.

The English summary is being prepared. Showing the original description.

rsicarelli/fakt67Updated Oct 23, 2026

See all skills by rsicarelli

Report a problem with this skill