kotlin-tooling-kotlin-toolchain-plugin-authoring
Load when authoring, writing, or designing a Kotlin Toolchain local plugin to extend the declarative build with code generation, build-time processing, custom verification, or packaging that module.yaml cannot express, or when referencing @TaskAction, @Configurable, plugin.yaml, or jvm/amper-plugin. Skip for porting an existing Gradle plugin.
github:@singleton11 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Kotlin/kotlin-agent-skills --skill kotlin-tooling-kotlin-toolchain-plugin-authoring技能说明
name: kotlin-tooling-kotlin-toolchain-plugin-authoring description: > Load when authoring, writing, or designing a Kotlin Toolchain local plugin to extend the declarative build with code generation, build-time processing, custom verification, or packaging that module.yaml cannot express, or when referencing @TaskAction, @Configurable, plugin.yaml, or jvm/amper-plugin. Skip for porting an existing Gradle plugin. license: Apache-2.0 metadata: author: github:@singleton11 version: "0.1.0"
Kotlin Toolchain Plugin Authoring
Local plugins are the official escape hatch from declarative YAML: a jvm/amper-plugin module shipping
task actions, settings, and generated sources/resources alongside your project. Code patterns to adapt are
in references/examples.md.
When to write a plugin
Write one when you need:
- A build-time step a library's workflow expects (code generation, schema compilation, resource transformation, version stamping).
- Custom verification wired into the build (pre-release checks, schema validation, contract tests).
- A build-time value published into the JAR classpath or downstream tasks — the closest analog to Gradle's
project.version. - A named CLI command for a repeated workflow (
./kotlin do release).
Don't write one when module.yaml already covers it (dependencies, JDK provisioning, source layouts,
basic packaging), and never to reuse a Gradle plugin — the Kotlin Toolchain cannot consume them.
Layout
repo-root/
├── kotlin, kotlin.bat # wrappers (from `kotlin init`)
├── project.yaml # registers the plugin
├── plugins/<name>/
│ ├── module.yaml # product: jvm/amper-plugin
│ ├── plugin.yaml # tasks: + commands: + generated:
│ └── src/
│ ├── Settings.kt # @Configurable interface
│ ├── tasks/ # one @TaskAction per file
│ │ ├── Foo.kt
│ │ └── FooSteps.kt # internal shared helpers (not @TaskAction)
│ └── <domain logic>/
└── <consumer-module>/
└── module.yaml # plugins: { <name>: enabled: true, ... }
Keep at least one consumer module in the repo — it is the only way to exercise the plugin end-to-end, and plugins cannot be published to any public registry yet.
project.yaml
modules:
- consumer-app
- plugins/<name>
plugins:
- ./plugins/<name>
Without the top-level plugins: block the plugin id is unresolvable from any consumer.
module.yaml — the plugin module
product: jvm/amper-plugin # marks the module as a plugin
dependencies:
- <coordinate>:<version>
- <coordinate>:<version>: runtime-only # required only at runtime
- <coordinate>:<version>: compile-only
pluginInfo:
id: <plugin-id> # what consumers write under `plugins:`
settingsClass: <fully.qualified.Settings> # the @Configurable interface
settings:
jvm:
jdk:
version: 21
kotlin:
languageVersion: 2.1
@Configurable interface Settings
Defaults go in interface property getters; nested blocks become nested @Configurable interfaces.
@Configurable
interface Settings {
val someValue: String get() = "default"
val checks: ChecksSettings
}
@Configurable
interface ChecksSettings {
val strict: Boolean get() = true
}
Consumers override what they need in module.yaml; omitted values fall back to the getter default:
plugins:
<plugin-id>:
enabled: true
someValue: "override"
checks:
strict: false
@TaskAction
Task actions are top-level funs, called when the matching plugin.yaml entry executes.
@TaskAction
fun foo(
@Input moduleRootDir: Path,
@Output outputDir: Path,
settings: Settings,
) {
// body
}
@Input path: Path— declared input; Kotlin Toolchain snapshots its contents for execution avoidance.@Output path: Path— declared output directory; Kotlin Toolchain creates it and passes the path in. Write to the exactPathyou received, or downstream references won't find the result.settings: Settings(or any@Configurable) — typed configuration, wired inplugin.yaml.- Plain
Path/ primitives — passed literally fromplugin.yaml. println(...)is the output channel; Kotlin Toolchain captures stdout.
Execution avoidance
A @TaskAction is skipped when its declared inputs are unchanged. Tasks whose real inputs are Git history,
the network, or environment variables cannot be fingerprinted, so opt out:
@TaskAction(executionAvoidance = ExecutionAvoidance.Disabled)
fun foo(@Output outputDir: Path, settings: Settings) { /* ... */ }
Tasks with no @Output are never cached and always re-run — correct for purely side-effecting tasks
(releases, deployments, pushes).
plugin.yaml
tasks:
foo:
action: !<fully.qualified.foo>
moduleRootDir: ${module.rootDir}
outputDir: ${taskOutputDir}
settings: ${pluginSettings}
bar:
action: !<fully.qualified.bar>
input: ${tasks.foo.action.outputDir}/result.txt
settings: ${pluginSettings}
generated:
resources:
- directory: ${tasks.foo.action.outputDir}
commands:
- foo
| Reference | Resolves to |
|---|---|
${module.rootDir} | Directory containing the consumer's module.yaml. Pass as @Input to inspect the consumer's tree. |
${taskOutputDir} | Toolchain-managed per-task output directory. Pass as @Output. |
${pluginSettings} | The @Configurable object built from the consumer's module.yaml. |
${tasks.<task>.action.<param>} | Another task's parameter — used in generated.* and to wire one task's @Input to another's @Output. |
generated.resources / generated.sources
Both register a directory (usually a task's @Output) as a contribution to the consumer's build, and both
auto-wire the producing task to run first:
- `