main-kts

Kotlin Scripts (.main.kts)

Use this skill to generate and run executable Kotlin .main.kts scripts: single-file programs that declare their own dependencies, run directly from the shell, and need no build file.

This is the kotlin script runner, not Kotlin Toolchain, Gradle, or Maven. Do not add module.yaml, build.gradle, or pom.xml. If the task needs a real multi-file project or published artifact, it is not a .main.kts task.

When To Use

• A one-off automation, glue, or CLI utility that should run with ./script.main.kts or kotlin script.main.kts.
• The user wants Kotlin without project scaffolding or a build system.
• Quick API calls, file munging, JSON processing, HTML generation, or shell orchestration.

Prefer a real Kotlin Toolchain or Gradle module when the code grows multiple source files, needs incremental builds, or ships as a library or application artifact.

Gather Requirements

Before writing, confirm:

1. What the script should do (purpose and behavior).
2. A name (suggest one from the behavior; the file must end in .main.kts).
3. Where to save it (default: current directory).
4. Any inputs it takes (command-line args, env vars, stdin).

Script Structure

@file: annotations must come first, before any import or code. Order them: Repository, DependsOn, Import, CompilerOptions, OptIn.

#!/usr/bin/env kotlin

/**
 * [What the script does.]
 *
 * Usage:
 *   ./script.main.kts <args>
 */

// Custom repositories. If any @file:Repository is present, list every repository needed.
// Maven Central is not kept implicitly once custom repositories are declared.
@file:Repository("https://repo.maven.apache.org/maven2/")
@file:Repository("https://jitpack.io")

// Maven dependencies
@file:DependsOn("group:artifact:version")

// Compose other scripts (optional)
@file:Import("other.main.kts")

// Compiler flags (optional)
@file:CompilerOptions("-jvm-target", "21")

// Opt-ins (optional)
@file:OptIn(ExperimentalStdlibApi::class)

import ...

// Top-level script code runs directly; `args` is available.