kotlin-tooling-kotlin-toolchain
Load when building, running, testing, packaging, linting, or configuring a Kotlin/Java project with the Kotlin Toolchain (JetBrains' unified CLI, formerly Amper), when scaffolding a new or greenfield Kotlin project, or when the repo has project.yaml, module.yaml, or a ./kotlin wrapper. Skip for existing Gradle/Maven projects.
github:@singleton11 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Kotlin/kotlin-agent-skills --skill kotlin-tooling-kotlin-toolchain技能说明
name: kotlin-tooling-kotlin-toolchain description: > Load when building, running, testing, packaging, linting, or configuring a Kotlin/Java project with the Kotlin Toolchain (JetBrains' unified CLI, formerly Amper), when scaffolding a new or greenfield Kotlin project, or when the repo has project.yaml, module.yaml, or a ./kotlin wrapper. Skip for existing Gradle/Maven projects. license: Apache-2.0 metadata: author: github:@singleton11 version: "0.1.0" provider: anthropic tested_models: "anthropic/claude-sonnet-5, anthropic/claude-opus-5" agent_version: claude-code last_eval: "2026-08-14"
Kotlin Toolchain
JetBrains' unified CLI for Kotlin (JVM, Android, iOS, multiplatform) and Java projects, in Alpha. Configuration is declarative YAML instead of Gradle build scripts.
Installation
Prefer the project's checked-in wrapper: ./kotlin build needs nothing installed — the wrapper downloads
the CLI itself. Install a global CLI only when there is no wrapper (e.g. before kotlin init):
sdk install kotlintoolchain # SDKMAN (macOS / Linux / WSL)
The kotlin command then auto-provisions its JDK on first use. Other install options (installer scripts,
IntelliJ IDEA plugin) live at https://kotlin-toolchain.org/.
If the project root ships wrapper scripts (kotlin / kotlin.bat), the global kotlin detects them and
proxies into them, pinning the project to the wrapper's version. Always invoke kotlin from the project
root so the wrapper wins; never call a globally installed binary directly when a wrapper exists.
CLI commands
For the detailed list of commands and their options, run kotlin --help or kotlin <command> --help.
Project structure
project-root/
├── kotlin, kotlin.bat # Local wrappers
├── project.yaml # Project-level config
├── libs.versions.toml # Version catalog (Gradle-compatible; root or gradle/)
├── module-name/
│ ├── module.yaml # Module configuration
│ ├── src/ # Production sources (Kotlin + Java mixed when JVM platform is available)
│ ├── resources/ # Resources (copied into JAR)
│ ├── test/ # Test sources
│ └── testResources/ # Test-only resources
└── another-module/
├── module.yaml
└── ...
project.yaml declares the project's modules and any local build plugins. See
references/examples.md for a project-level config example.
module.yaml
product: jvm/app # jvm/app, jvm/lib, android/app, lib (multiplatform), …
dependencies:
- org.example:artifact:1.0.0 # Maven coordinates
- //other-module # Module dependency (relative path from the project root)
- $libs.ktor.client # From version catalog
- bom: io.ktor:ktor-bom:2.2.0 # BOM import
- org.example:foo:1.0.0: exported # Exposed to dependents (like Gradle api())
- org.example:bar:1.0.0: compile-only
- org.example:baz:1.0.0: runtime-only
test-dependencies:
- io.mockk:mockk:1.13.0
settings:
jvm:
mainClass: org.example.MainKt # Default: main() in main.kt
jdk:
version: 21
kotlin:
languageVersion: 2.0
compose:
enabled: true
test-settings:
kotlin:
languageVersion: 2.0
Notes:
module.yamldoes not support${...}interpolation. Values are literal strings/booleans/numbers; paths are relative to the module root. Interpolation works only inplugin.yaml.- The module name is the basename of the directory holding
module.yaml. There is noname:field. - Tests use kotlin.test by default, no dependency needed.
Version catalogs use the standard Gradle libs.versions.toml format, referenced as $libs.<key>.
Built-in catalogs $kotlin.* and $compose.* derive their versions from settings.
Templates
A template extracts reusable module.yaml sections into a <name>.module-template.yaml file (same
structure as module.yaml) that modules pull in via an apply: list of relative paths. It's a general
reuse mechanism — sharing project-wide config is just one use. There is no enforced convention for where
the file lives. Modules reference it by path under apply:.
Because there is no project-wide settings: block, templates are the only way to share configuration
(Kotlin language version, common test dependencies, repositories, …) across modules. apply: one template
everywhere for project-wide defaults, or keep several templates and apply different combinations to
different subsets of modules — e.g. a common template in every module plus a service-only template in the
backend modules. A module can list multiple templates under apply:.
# common.module-template.yaml
test-dependencies:
- io.mockk:mockk:1.13.0
settings:
kotlin:
languageVersion: 2.0
# module.yaml
product: jvm/app
apply:
- //common.module-template.yaml
- //jvm-service.module-template.yaml
- Templates can't have
product:orapply:sections — a template can't apply another template (no recursion) and can't define products. - Applied one by one, with
module.yaml's own values last: scalars are overridden, lists and mappings appended, andmodule.yamlalways wins regardless ofapply:position.
Checks and linters
kotlin check runs all tests plus every registered check. Filter by name (kotlin check detekt apiCheck),
skip with --skip <name> (e.g. --skip tests), restrict to modules with -m <module> (repeatable), and
list what exists with kotlin show checks. A check fails when its underlying task throws.
The Toolchain ships no bundled linters — tests is the only built-in check. detekt, ktlint, and
API-compatibility verification must be registered as local-plugin tasks under checks: in plugin.yaml.
Multiplatform
Platform code lives in @platform-suffixed directories: src@jvm/, src@ios/, src@android/. Common
code in `src