Gradle Best Practices

Audit a project against the official Gradle best practices, produce a structured findings report, and propose concrete code changes to fix the issues. Checks and fixes cover build scripts (*.gradle.kts, *.gradle), settings files, gradle.properties, the wrapper config, the version catalog, and Java/Kotlin/Groovy source under buildSrc/ and build-logic/.

The best-practices catalog ships with this skill, pre-digested, under references/. Read it from disk. Do not fetch anything from the network at run time.

Sources of truth

The catalog is layered so that each run reads only the layer it needs. Read no more of it than the steps below tell you to — every Read result stays in context and is re-sent on every later turn, so a file read once costs tokens on every turn after it.

• references/detection.md — how to read an entry, plus the symptom index. Read once, in Step 3.
• references/<category>.md — one file per category, holding each entry's title, anchor, severity band, precondition, detection recipe, and a one-line fix summary. Terse by design: this is the layer you read to decide, and it carries everything needed to write a finding — including its Fix: line. Read only the ones Step 2 selects. Seven files: general.md, structuring-builds.md, dependencies.md, tasks.md, performance.md, security.md, testing.md.
• references/fixes/<anchor>.md — one file per practice: the rule, the fix in full, and for most entries the documentation's own Don't/Do pair in Kotlin DSL. Optional depth, never a required layer. Read one only when the category entry's Fix: line is not enough to make the change, and then one at a time as you reach each fix — never up front. There are 48; loading them speculatively wastes context for no gain.
• references/index.md — provenance only: the capture date, the source URLs, and the full 48-entry listing used to regenerate the catalog. Never read it at run time. Everything a run needs from it is already here; it costs ~7,400 characters and a turn for nothing.

The direct link for any best practice is https://docs.gradle.org/current/userguide/best_practices_<category>.html#<anchor>. The URL segment is the category file's name with dashes as underscores, so structuring-builds.md → best_practices_structuring_builds.html. Cite those URLs so the reader can follow up — but read the bundled file, never fetch it. A handful of the newest anchors do not resolve on current yet; for those, cite https://docs.gradle.org/nightly/userguide/… instead.

Modes