# Kotlin API Consultant

> Queries Kotlin compiler source code for API validation, compatibility checks, and breaking change detection. Use when validating Kotlin compiler APIs, checking IrGenerationExtension compatibility, analyzing compiler plugin API usage, or verifying that an API hasn't been deprecated or removed in a newer Kotlin version. Make sure to use this skill whenever compiler plugin code references Kotlin internal APIs — these APIs change frequently between Kotlin versions and silent breakage is common. Use when this capability is needed.

- Skill: `tomevault-io/kotlin-api-consultant` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/kotlin-api-consultant`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/kotlin-api-consultant/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/kotlin-api-consultant

---


# Kotlin API Consultant

Validates Kotlin compiler API usage, detects breaking changes, and provides best practice recommendations for compiler plugin development.

## Core Mission

Provides Kotlin compiler API validation by consulting source code, detecting breaking changes, and ensuring API compatibility across Kotlin versions.

## Instructions

### 1. Identify Target API

**Extract from conversation:**
- API class/interface name from user's message
- Look for patterns: "check IrGenerationExtension", "validate IrPluginContext API"
- Common APIs: IrGenerationExtension, IrPluginContext, IrFactory, IrClass, IrTypeParameter, CompilerPluginRegistrar

**If unclear or missing:**
```
Ask: "Which Kotlin compiler API would you like me to consult?"
Suggest: IrGenerationExtension | IrPluginContext | IrFactory | CompilerPluginRegistrar | Other
```

### 2. Locate API in Kotlin Compiler Source

**Search Kotlin source on GitHub or local copy if available:**

Common package locations:
- `org.jetbrains.kotlin.backend.common.extensions` (IR extension APIs)
- `org.jetbrains.kotlin.ir.declarations` (IR tree elements)
- `org.jetbrains.kotlin.ir.expressions` (IR expressions)
- `org.jetbrains.kotlin.ir.types` (Type system)
- `org.jetbrains.kotlin.fir` (FIR APIs)
- `org.jetbrains.kotlin.compiler.plugin` (Plugin registration)

**If not found:**
```
API '${API_NAME}' not found

Suggestions:
1. Check spelling (case-sensitive)
2. Check if it's an internal/experimental API
3. Consult: https://kotlinlang.org/docs/compiler-plugins.html
```

### 3. Analyze API Definition

**Extract key information:**
- [ ] Package and imports
- [ ] Interface/class declaration
- [ ] Generic type parameters
- [ ] Method signatures
- [ ] Annotations (@UnsafeApi, @FirIncompatiblePluginAPI, @Deprecated)
- [ ] Default implementations

**Critical annotation markers:**
```kotlin
@UnsafeApi                          // May change without notice
@FirIncompatiblePluginAPI          // K1 only, not K2
@Deprecated(message = "...", level = ERROR)  // Removal planned
@ExperimentalCompilerApi           // Unstable, may change
```

### 4. Detect Breaking Changes

**Breaking change indicators:**
- Removed methods
- Changed method signatures
- Added abstract methods to interface
- Changed return types
- New required type parameters
- Deprecation with ReplaceWith (migration path)

### 5. Generate API Report

```
KOTLIN API CONSULTATION: ${API_NAME}

LOCATION:
Package: org.jetbrains.kotlin...
Module: ...

DEFINITION (Kotlin ${VERSION}):
[Interface/class definition]

STABILITY: Stable / Experimental / Deprecated
K2 COMPATIBLE: Yes / No / Partial

FAKT USAGE:
- [How Fakt uses this API]
- [Alignment status]

WARNINGS:
- [Any @UnsafeApi warnings]
- [Deprecation notices]

RECOMMENDATIONS:
1. [Recommendation]
...
```

### 6. Provide Usage Recommendations

**If API is stable:** Safe to use directly.
**If API has @UnsafeApi:** Consider abstraction layer for isolation.
**If API is deprecated:** Show migration path with replacement API.

## Supporting Files

- **`resources/api-lookup-patterns.md`** - Strategies for finding APIs
- **`resources/breaking-changes-catalog.md`** - Known breaking changes across Kotlin versions
- **`resources/api-best-practices.md`** - Best practices for compiler plugin APIs

## Related Skills

- **`compiler-architecture-validator`** - Validate architectural patterns
- **`compilation`** — Debug compilation errors
- **`docs-navigator`** — Access documentation

## API Categories

| Category | Examples | Stability |
|----------|----------|-----------|
| Core IR | IrGenerationExtension, IrPluginContext | Stable |
| FIR Phase | FirExtensionRegistrar | K2 specific |
| Plugin System | CompilerPluginRegistrar | Stable |
| Type System | IrTypeParameter, IrType | Moderate |
| Experimental | Various @ExperimentalCompilerApi | Unstable |

## Validation Checklist

Before using an API in Fakt:
- [ ] API located and analyzed
- [ ] Current definition understood
- [ ] Breaking changes checked
- [ ] Deprecation status confirmed
- [ ] K1/K2 compatibility verified

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/rsicarelli) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->