# Kotlin Tooling Kotlin Toolchain Plugin Authoring

Load when authoring, writing, or designing a Kotlin Toolchain local plugin to extend...

- Repository: https://github.com/Kotlin/kotlin-agent-skills (1104 stars)
- Category: Design
- License: Apache-2.0
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add Kotlin/kotlin-agent-skills --skill kotlin-tooling-kotlin-toolchain-plugin-authoring -g -a claude-code -y`
Codex: `npx skills add Kotlin/kotlin-agent-skills --skill kotlin-tooling-kotlin-toolchain-plugin-authoring -g -a codex -y`
Cursor: `npx skills add Kotlin/kotlin-agent-skills --skill kotlin-tooling-kotlin-toolchain-plugin-authoring -g -a cursor -y`
Gemini CLI: `npx skills add Kotlin/kotlin-agent-skills --skill kotlin-tooling-kotlin-toolchain-plugin-authoring -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add Kotlin/kotlin-agent-skills`

## 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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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](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`

```yaml
modules:
  - consumer-app
  - plugins/<name>

plugins:
  - ./plugins/<name>
```

The rest: https://github.com/Kotlin/kotlin-agent-skills/blob/HEAD/skills/kotlin-tooling-kotlin-toolchain-plugin-authoring/SKILL.md