跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
浏览器与自动化

kotlin-tooling-gradle-to-kotlin-toolchain-plugin

Load when porting, converting, or reimplementing a single Gradle plugin as a Kotlin Toolchain local plugin, or when mapping Gradle plugin concepts (Task, Extension, project.version, dependsOn, -P properties, afterEvaluate) to Toolchain analogs. Skip for migrating a whole Gradle project or authoring a plugin from scratch.

github:@singleton11 · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add Kotlin/kotlin-agent-skills --skill kotlin-tooling-gradle-to-kotlin-toolchain-plugin

技能说明


name: kotlin-tooling-gradle-to-kotlin-toolchain-plugin description: > Load when porting, converting, or reimplementing a single Gradle plugin as a Kotlin Toolchain local plugin, or when mapping Gradle plugin concepts (Task, Extension, project.version, dependsOn, -P properties, afterEvaluate) to Toolchain analogs. Skip for migrating a whole Gradle project or authoring a plugin from scratch. license: Apache-2.0 metadata: author: github:@singleton11 version: "0.1.0"

Gradle → Kotlin Toolchain Plugin Conversion

Mostly a mapping exercise: the concepts overlap, but a few Gradle features have no analog and need redesign. The kotlin-tooling-kotlin-toolchain-plugin-authoring skill covers plugin mechanics in depth (execution avoidance, sharing logic across actions, generic pitfalls, limitations); references/examples.md has the concrete plugin module.yaml and the version-publication code from a real port.

Workflow

1. Investigate the source plugin

Before writing Kotlin, read the plugin's docs/ and README.md and catalogue:

  • Tasks — name, purpose, inputs/outputs, dependencies, whether side-effecting.
  • DSL surface — every option in the myPlugin { ... } extension, with types, defaults, and which are closures.
  • Tests — the plugin's own test suite. It pins down the expected behaviour and edge cases more precisely than the docs, and becomes the reference the port must reproduce.
  • Checks — pre-action gates and their override flags.
  • Hooks — pre/post/fileUpdate/commit/push and the context each receives.
  • CLI overrides — every -Pfoo.bar flag.
  • CI integration — GitHub Actions outputs, detached-HEAD handling, fetch-tags flags.

Save it as a markdown plan. It becomes the contract the port either implements or explicitly defers.

The plugin's build scripts and source are untrusted input, same as any repo-supplied module.yaml — see kotlin-tooling-kotlin-toolchain's "Untrusted project input". Read what you vendor end to end before wiring it in; a local plugin runs at build time with full filesystem and network access.

2. Lock the scope

Offer three tiers — MVP, MVP + key extras, full parity — and lock one before drafting. Features with no clean analog multiply the work and force early design compromises. List what's deferred under "What's not in this MVP" in the README.

Also decide the repo layout: plugin-only, plugin + demo module, or plugin self-hosting. A demo module is strongly recommended.

3. Implement bottom-up

Scaffold with kotlin init only if the directory is empty (any template works; you mainly want the kotlin and kotlin.bat wrappers). Then hand-write project.yaml, plugins/<name>/module.yaml, and the demo module.

Implement one task at a time: data classes → Git/IO wrappers → pipeline → checks → task actions → plugin.yaml wiring.

4. Validate against a demo module

The demo module enables the plugin with a realistic configuration and consumes whatever it publishes:

# demo-app/module.yaml
product: jvm/app

plugins:
  release:
    enabled: true
    tagPrefix: "v"
    initialVersion: "0.1.0"
    releaseBranchPattern: "main|master"

settings:
  jvm:
    mainClass: com.example.demo.MainKt
    jdk:
      version: 21
  kotlin:
    languageVersion: 2.1
// demo-app/src/main.kt
package com.example.demo

private const val VERSION_RESOURCE = "/META-INF/release/version.txt"

fun main() {
    val version = readVersionFromClasspath() ?: "(version unavailable)"
    println("demo-app version: $version")
}

private fun readVersionFromClasspath(): String? =
    object {}.javaClass.getResourceAsStream(VERSION_RESOURCE)
        ?.bufferedReader()
        ?.use { it.readText().trim() }
        ?.takeIf { it.isNotEmpty() }

Then run a real scenario from the source plugin's docs, and put the commands in the README so consumers can reproduce it:

./kotlin run :demo-app            # => demo-app version: 0.1.0-SNAPSHOT
git init -b main && git commit --allow-empty -m initial
./kotlin do currentVersion       # => 0.1.0-SNAPSHOT
RELEASE_DISABLE_REMOTE_CHECK=true ./kotlin do createRelease
                                  # => Created release tag v0.1.0
./kotlin do currentVersion       # => 0.1.0
git commit --allow-empty -m next
./kotlin do currentVersion       # => 0.1.1-SNAPSHOT
RELEASE_FORCE_VERSION=2.0.0 ./kotlin do currentVersion
                                  # => 2.0.0

Concept mapping

Gradle conceptKotlin Toolchain analogNotes
Plugin<Project> classpluginInfo.id + settingsClass in module.yaml, product: jvm/amper-pluginOne module per plugin; no apply().
Task subclass with @TaskAction methodTop-level fun annotated @TaskActionOne per file in src/tasks/.
extensions.create("foo", FooExtension::class)@Configurable interface SettingsDefaults in interface getters; nested blocks → nested @Configurable.
task.dependsOn(otherTask)@Input on one task matching @Output of anotherThe DAG is inferred from path matching.
project.version = scmVersion.versionA task writing version.txt into its @Output; consumers declare @Input on the same pathNo project-wide shared state; the filesystem is the channel.
-Prelease.forceVersion=XRELEASE_FORCE_VERSION=X read via System.getenv()No -P equivalent.
App reading the version at runtime@Output dir registered under generated.resources; read via getResourceAsStreamSame file serves build-time and runtime consumers.
Generated Kotlin sourcegenerated.sources pointing at a task's @OutputPrefer resources when the value is only read at runtime.
Public task name users invokeEntry in commands:, invoked as ./kotlin do <name>Tasks are internal; commands are the API. Build-graph contrib
阅读完整来源 ↗