Skip to content

About

Official Koin agent skills - set up Koin, write Koin code, migrate from Hilt/Dagger/Toothpick/Kodein/Koin KSP/Koin 3.x, diagnose Koin apps with the Kotzilla MCP.

Topics

Resources

Stars

72 stars

Watchers

0 watching

Forks

Repository files navigation

Koin Skills

Version License Koin Kotlin

Official Koin skills for AI agents, packaged as the koin Claude Code plugin. They target Koin 4.x with the Koin Compiler Plugin: Koin Annotations (JSR-330 compatible) or Koin DSL, compile safe in both, for Kotlin, Android, Compose, Kotlin Multiplatform and Ktor.

Skill What it does
koin-setup Set up Koin in a new or legacy project, or alongside an existing DI container
koin Write Koin code: definitions, modules, entry points, scopes, tests — and push back on DI mistakes
di-migration Migrate from Hilt, Dagger, Toothpick, Kodein, Metro, Koin 3.x, classic Koin DSL or Koin KSP
koin-diagnose Koin errors and app behavior (startup, ANRs, scopes): static suspects, proven with Kotzilla when you opt in

Installation

From Claude Code (recommended)

In a Claude Code session, run:

/plugin marketplace add InsertKoinIO/koin-skills
/plugin install koin@koin-skills

The first command registers this repo as a plugin marketplace; the second installs the koin plugin from it. Skills show up as koin:koin-setup, koin:koin, koin:di-migration and koin:koin-diagnose. Updates: /plugin marketplace update koin-skills.

From a clone

skills/ at the repo root holds the complete, ready-to-use skills — no build step needed.

git clone https://github.com/InsertKoinIO/koin-skills.git
claude --plugin-dir /path/to/koin-skills

Or copy one skill into your Claude Code skills directory (no plugin, skill only):

# Project-level (shared with your team via git)
mkdir -p .claude/skills/koin
cp -R koin-skills/skills/koin/. .claude/skills/koin/

# Or personal (available across all your projects)
mkdir -p ~/.claude/skills/koin
cp -R koin-skills/skills/koin/. ~/.claude/skills/koin/

Copy the whole skill folder: each skill reads its references/. Update with git pull.

Other agents

For Cursor, Codex, Copilot, Windsurf, Gemini and other agents that read agent skills, use the skills CLI (Node.js 22 or later):

npx skills add InsertKoinIO/koin-skills

Each GitHub Release attaches one <skill>-skill.skill archive per skill (a zip of the skill folder) and koin-plugin.zip.

Supported Migration Paths

Source Target
Hilt (+ Dagger) Koin 4.x Annotations + Compiler Plugin
Dagger 2 (no Hilt) Koin 4.x Annotations + Compiler Plugin
Toothpick Koin 4.x Annotations + Compiler Plugin
Kodein Koin 4.x Compiler Plugin DSL
Metro Koin 4.x Annotations + Compiler Plugin
Koin 3.x Koin 4.x + Compiler Plugin (DSL kept; Compiler Plugin DSL optional)
Koin DSL Add the Compiler Plugin (DSL kept; Compiler Plugin DSL optional)
Koin KSP Annotations Koin 4.x Annotations + Compiler Plugin

For greenfield projects or manual DI / service locator code, there's nothing to migrate from — the koin-setup skill sets Koin up directly.

Usage

The skills trigger on their own when a task touches dependency injection. Examples:

  • "Add Koin to this KMP project"

  • "Add a ViewModel for the profile screen" (in a Koin project)

  • "Why is UserRepository created twice?"

  • "Migrate this Hilt module to Koin"

  • "Convert my Dagger components to Koin"

  • "Upgrade my Koin 3.x project to Koin 4.x"

  • "Move from Koin KSP annotations to the Compiler Plugin"

  • "Convert this Toothpick scope tree to Koin"

  • "Migrate this Kodein DI container to Koin"

For migrations, di-migration follows an 8-step workflow: Inventory → Plan → Gradle Setup → Generate Module Code → Wire Up Application → Update Injection Sites → Per-module validation → Final Cleanup. Steps 4, 6 and 7 repeat module by module (Step 5 with the first module).

Progressive migration by default: the skill recommends creating a new Koin module and moving definitions into it step by step — never rewriting your existing DI modules in place. While both containers run, Koin reads from the old one through bridges: koin-dagger-bridge (dagger<T>() on a Hilt @EntryPoint) for Hilt, @Singleton fun providers for plain Dagger 2, scope helpers for Toothpick and Kodein, graph accessors for Metro.

Key Features

  • Koin Compiler Plugin (io.insert-koin.compiler.plugin) — compile-time dependency verification for Annotations and every Koin DSL form
  • Auto parameter resolution — T, T?, Lazy<T>, List<T> handled automatically by the compiler
  • Auto-bind — a class is bound to the interfaces it implements, no explicit binds needed
  • JSR-330 support — javax.inject.* and jakarta.inject.* annotations reusable as-is
  • Custom qualifiers — existing @Qualifier annotations from Dagger/Hilt work directly
  • Scope archetypes — @ActivityScope, @FragmentScope, @ViewModelScope, @ActivityRetainedScope
  • Compiler Plugin DSL — single<T>(), factory<T>(), viewModel<T>() with reified type parameters

Kotzilla MCP Server

Kotzilla is optional: the skills work fully without it. They propose it once, at a precise moment, and never force it: koin-diagnose for Koin errors, crashes and runtime behavior (startup, ANRs, memory, instances created twice), di-migration to check each migrated module at runtime, koin-setup and koin to see new definitions behave as written. The Kotzilla MCP Server alone diagnoses Koin errors; the Kotzilla SDK adds real session data for runtime behavior. Decline once and no skill asks again in that conversation.

Included with the koin plugin in Claude Code: it shows as plugin:koin:kotzilla (needs authentication) until you sign in — run /mcp, pick it, sign in with a free account from https://kotzilla.io. Nothing reaches Kotzilla before you sign in.

Without the plugin, or in another agent (Cursor, Codex, Copilot, Junie…), add the endpoint https://mcp.kotzilla.io/mcp (HTTP transport, OAuth) yourself. With Claude Code:

claude mcp add kotzilla --transport http https://mcp.kotzilla.io/mcp

The skills check whether Kotzilla tools are connected, whatever server provides them. When they aren't, the proposal says how to connect for your agent; you sign in and run any install yourself — the agent never does it for you.

Requirements

  • Kotlin ≥ 2.3.20 (K2 compiler)
  • Koin ≥ 4.2.2, Koin Compiler Plugin ≥ 1.2.3 (recommended; Koin DSL also works without it)

Contributing

Issues and pull requests are welcome.

  • Bug reports / migration path gaps → open an issue with the source framework, a minimal snippet, and the expected Koin output
  • Edit the sources under src/, never skills/ — skills/ is generated by ./build.sh and committed; run it and commit both
  • New migration paths → add a src/skills/di-migration/references/<source>-to-koin.md guide following the existing structure, register it in src/skills/di-migration/SKILL.md, then run ./build.sh
  • Release (maintainers): see RELEASING.md for the full checklist

Repository Layout

.claude-plugin/
  plugin.json                       # plugin manifest (name, version, metadata)
  marketplace.json                  # makes this repo installable via /plugin marketplace add
src/skills/<name>/                  # skill sources: SKILL.md + skill-specific references/
src/shared/*.md                     # references shared by every skill, written once
skills/<name>/                      # GENERATED by ./build.sh, committed: complete skills (the installed plugin)
build.sh                            # checks sources, generates skills/, builds build/*.skill + build/koin-plugin.zip
build/                              # git-ignored: build/plugin/, <skill>-skill.skill bundles, koin-plugin.zip
scripts/                            # build checks (duplication, generated output)

License

Apache 2.0 — see LICENSE.

About

Official Koin agent skills - set up Koin, write Koin code, migrate from Hilt/Dagger/Toothpick/Kodein/Koin KSP/Koin 3.x, diagnose Koin apps with the Kotzilla MCP.

Topics

Resources

Stars

72 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages