kotlin-jvm-lsp-gradle-debug - SKILL.md Agent Skill

name: kotlin-jvm-lsp-gradle-debug description: Standardize editor-agnostic Kotlin/JVM development workflows using Language Server Protocol, Gradle wrapper commands, and JVM debugging. Use when setting up or troubleshooting Kotlin tooling in LSP-capable editors, validating Gradle build/test/run loops, or attaching debuggers to JVM app and test processes.

Kotlin JVM LSP Gradle Debug

Goal

Standardize Kotlin/JVM workflows across editors by using one repeatable loop for tooling checks, Gradle execution, and debug attach. Prefer open, editor-agnostic integrations and avoid IDE lock-in unless the user explicitly requests it.

Workflow

Detect project boundaries and toolchain.

Confirm project root and prefer ./gradlew over system Gradle.
Verify Java and Gradle: java -version and ./gradlew -v.
Confirm module layout and runnable tasks: ./gradlew tasks --all.

Stabilize the Gradle baseline before editor integration.

Run a clean verification loop: ./gradlew clean test.
If the project has an app entrypoint, run it with ./gradlew run (or project-specific task).
Fix build errors before enabling LSP/debug workflows.

Select an LSP backend explicitly.

Load tooling-matrix.md before choosing a backend.
Prefer Kotlin/kotlin-lsp for current official direction.
Use fwcd/kotlin-language-server when an open-source server is required and tradeoffs are acceptable.
Record the selected backend and any known limitations in the final output.

Run debug workflows with deterministic attach points.

Start JVM app debugging with ./gradlew run --debug-jvm.
Start JVM test debugging with ./gradlew test --debug-jvm.
Attach a DAP/JDWP client to localhost:5005 unless the build defines a different port.
For editor-agnostic debug support, use fwcd/kotlin-debug-adapter when available.

Triage failures with a fixed recovery sequence.

Stop stale daemons: ./gradlew --stop.
Retry with dependency refresh: ./gradlew clean build --refresh-dependencies.
Re-check tool versions and classpath assumptions.
If issues persist, capture exact failing command, stack trace, and minimal repro module.

Output Contract

Always provide:

Detected environment summary (JDK, Gradle wrapper, project type).
Exact commands executed in order.
LSP backend and debug adapter selection with rationale.
Current status: working, partially working, or blocked.
Next concrete command to run.

References

Use tooling-matrix.md when selecting LSP and debug tooling.
Use command-playbook.md for reusable command snippets and attach templates.

Constraints

Do not use global Gradle or global Kotlin executables when ./gradlew is present.
Do not mark setup complete unless at least one build/test command and one debug attach path have been validated.
Do not hide experimental or deprecated tooling status; state it explicitly.