AgentSkillsCN

ktlint

使用 ktlint 格式化并检查 Kotlin 代码；在 Gradle/CLI/CI 中设置或更新 ktlint，配置 .editorconfig 文件，并针对 Kotlin 项目中的 ktlint 失败问题或格式变更进行故障排查。

SKILL.md
--- frontmatter
name: ktlint
description: Format and lint Kotlin using ktlint; set up or update ktlint in Gradle/CLI/CI, configure .editorconfig, and troubleshoot ktlint failures or formatting changes in Kotlin projects.

Ktlint

Use this skill to format and lint Kotlin code with ktlint, and to set up or maintain ktlint tooling in a project.

Quick start

  1. •Detect how the project runs ktlint (Gradle tasks vs CLI).
  2. •Run ktlint check or format on the target paths.
  3. •Fix or configure rules via existing project config (usually .editorconfig).

Determine the integration

  • •Prefer existing build tasks: look for ktlintCheck / ktlintFormat (or custom ktlint tasks) in Gradle.
  • •If there are no build tasks, fall back to the ktlint CLI if it is installed.
  • •Before changing setup, search for existing config and automation:
    • •.editorconfig and any ktlint sections
    • •build.gradle / build.gradle.kts
    • •CI files (GitHub Actions, GitLab CI, etc.)
    • •pre-commit hooks

Common tasks

Run ktlint check (no changes)

  • •Prefer Gradle: run the project’s ktlint check task.
  • •Otherwise use the CLI to lint specific files or directories.

Run ktlint format (apply fixes)

  • •Prefer Gradle: run the project’s ktlint format task.
  • •Otherwise use the CLI formatter.

Format only specific files

  • •Pass explicit paths to the task or CLI.
  • •If using Gradle, check whether the plugin supports path filters or separate source sets.

Configure rules

  • •Modify the project’s existing .editorconfig rather than inventing a new location.
  • •Keep changes minimal and explain why a rule is enabled/disabled.
  • •If the project pins a ktlint version, follow its supported rule IDs and config keys.

Add ktlint to a Gradle project

  • •Prefer the project’s existing Kotlin/Gradle conventions (versions catalog, buildSrc, convention plugins).
  • •Add the plugin and tasks in the standard place for that repository.
  • •Wire ktlint into CI the same way other quality checks are run.

Troubleshoot failures

  • •Identify the ktlint version and whether it is coming from Gradle or CLI.
  • •Reproduce locally with the same task or command used in CI.
  • •If a rule suddenly fails, check recent ktlint or rule-set updates in the project.

Scripts

  • •scripts/ktlint.sh provides a lightweight wrapper to run check/format using Gradle tasks if present, or fall back to the ktlint CLI.

Notes

  • •Avoid changing rule configuration unless the user asks; prefer formatting fixes.
  • •When updating setup, keep changes minimal and aligned with existing project conventions.