kotlin-gradle-build-engineering

name	kotlin-gradle-build-engineering
description	Use this skill to statically review Gradle build-graph quality and CI throughput for Kotlin/KMP projects: configuration-cache compatibility (no execution-time Project access), build-cache correctness (@CacheableTask annotation completeness and relocatable/reproducible output), kapt vs KSP annotation-processing configuration and incremental opt-in, configuration-avoidance API usage, and convention-plugin (build-logic included build) centralization. Reads Gradle build files and build-scan evidence only; it never invokes Gradle or measures a live build.
allowed-tools	Read Grep Glob
metadata	{"author":"github: Raishin","version":"0.1.0","updated":"2026-07-21","category":"delivery","lifecycle":"experimental"}

kotlin-gradle-build-engineering

Purpose

This skill decides whether a Kotlin/KMP Gradle build is correctly engineered for cache reuse and CI throughput. A build is safe only when no task reads live project state at execution time, every cacheable task is fully and correctly annotated with relocatable/reproducible output, annotation processing is incremental and prefers KSP over kapt where possible, the configuration-avoidance API is used by default, and shared build configuration lives in a centralized build-logic convention plugin rather than being duplicated.

Trigger conditions

• A user provides Gradle build files (root, subproject, or build-logic convention plugins) and asks whether the configuration cache or build cache will work correctly.
• A user is diagnosing a cache miss, cache-poisoning, or slow-CI symptom in a Kotlin/KMP Gradle build.
• A user asks whether kapt should be migrated to KSP, or whether an annotation processor is configured for incremental compilation.

When not to use

• The concern is dependency trust, verification metadata, plugin trust, or publication provenance — route to kotlin-supply-chain-release-integrity-agent.
• The concern is cryptographic signing or SLSA provenance attestation — route to the sigstore board.
• The concern is CI-runner or cluster infrastructure rather than the build graph — route to the kubernetes/cloud boards.
• The task requires actually invoking Gradle, measuring a live build, or reading a live build-cache node — this skill is static-review only.

Lean operating rules

• CRITICAL — a task that reads Project, Task.project, or other live project/build-model state at execution time (inside doLast/doFirst or a task-action method) breaks configuration-cache serialization; require inputs be captured at configuration time via Provider/Property lazy APIs and passed into the task, never resolved from project at execution time.
• CRITICAL — a custom task declared @CacheableTask without complete and correct @Input/@InputFiles/@OutputDirectory/@OutputFile annotations on every property affecting output produces cache poisoning (a false cache hit serving stale output) or a permanent cache miss; treat missing/incomplete annotations on a cacheable task as a defect.
• CRITICAL — a cacheable task whose output embeds an absolute path, timestamp, or machine-specific value is not relocatable/reproducible and will misbehave under a shared or remote build cache across machines/CI runners; require output be path- and machine-independent.
• HIGH — kapt used for a purely Kotlin-targeted annotation processor where a KSP-based version of the same processor exists is an avoidable performance cost (kapt generates Java stub sources); require justification (no KSP equivalent) or migration to KSP.
• HIGH — an annotation processor enabled without an explicit incremental-processing declaration (isolating or aggregating) forces a full, non-incremental recompilation on every change; require the processor be verified incremental-capable and configured accordingly.
• HIGH — duplicated build configuration (repeated repository/plugin/dependency blocks) copy-pasted across subproject build scripts instead of centralized in a build-logic included-build convention plugin is a maintainability and version-skew defect; require shared configuration be extracted.
• MEDIUM — eager task creation (tasks.create) or eager project.subprojects/allprojects configuration where the configuration-avoidance API (tasks.register, a lazy Provider) would suffice inflates configuration-phase cost on every build invocation, including cache-hit builds; require lazy APIs be used by default.
• MEDIUM — a task or plugin that forces configuration of unrelated subprojects (e.g. iterating rootProject.allprojects inside a single module's build script) defeats partial/selective configuration and slows CI; require cross-project access go through explicit, documented dependency declarations.

References

Load these only when needed:

• Configuration Cache And Build Cache
• Annotation Processing: Kapt Vs KSP
• Convention Plugins And The Build-Logic Included Build
• Official Sources
• Safety Checklist

Response minimum

• A verdict (pass / pass-with-conditions / block) and the Gradle/Kotlin version(s) assumed.
• Configuration-cache, build-cache, task-graph/configuration-avoidance, annotation-processing, and convention-plugin findings, each with an evidence-basis label.
• A severity-labelled finding list plus safe next actions and open questions, including any throughput claim needing build-scan measurement.