企业官网建设流程全解析

kotlin-agent-skills 是 JetBrains 开源的一套Kotlin AI Agent 技能包，它为 AI 编程助手（如 Claude Code、Codex）提供可插拔的"专业技能"。每个技能都是一个自包含的文件夹，内含SKILL.md指令文件、参考文档和脚本，让 AI 在处理 Kotlin 项目时"像专家一样干活"。本文帮你快速搞懂：5 大官方技能分别解决什么问题、什么时候该用哪个，附选型速查表与安装指南。

一、kotlin-agent-skills 是什么？先搞懂技能机制

理解选型之前，先花 30 秒了解它的运行原理：

• 技能 = 一个文件夹：打包了指令（SKILL.md）、参考资料（references/）、脚本（scripts/）和检查清单（assets/）
• 按需激活：AI Agent 根据任务场景自动加载对应技能，加载后就会按照技能内的规范执行
• 两大分类：backend（后端开发）与tooling（工具链/构建），分类定义见 CATEGORIES

一句话总结：它不写业务代码，而是教会 AI 如何正确地做 Kotlin 领域的专业任务。

二、5 大技能总览：一张表看清全家福

💡 规律很清晰：4 个 tooling 技能聚焦"迁移"这一痛点，1 个 backend 技能聚焦"实体建模"这一高频坑点，全部来自 JetBrains 官方经验沉淀。

三、逐个解析：每个技能适合什么场景？

3.1 Java 转 Kotlin：kotlin-tooling-java-to-kotlin

这是最通用的技能，适合存量 Java 代码逐步 Kotlin 化的团队。

它的核心能力是"框架感知"——转换前先扫描 import，自动加载对应的框架参考指南，覆盖 Spring、Lombok、Hibernate、Jackson、Quarkus、Dagger/Hilt、RxJava、JUnit、Guice、Retrofit、Mockito 等 12 种框架，参考文档位于 skills/kotlin-tooling-java-to-kotlin/references/frameworks/。

采用 4 步工作流（扫描检测 → 转换 → 写 .kt → Git 重命名 → 验证），每步有 5 项不变量检查，方法论详见 CONVERSION-METHODOLOGY.md。

✅选它，如果：你要把.java文件批量改成.kt，且项目里用到了上述任一框架。

3.2 AGP 9.0 迁移：kotlin-tooling-agp9-migration

AGP 9.0 之后，Android 应用/库插件与 Kotlin Multiplatform 插件不能再同模块共存，大量 KMP 项目升级时会直接构建失败。这个技能是专门的"解药"：

• 自动分析项目：内置 analyze-project.sh 脚本，一次性扫描模块、插件、版本目录
• 三条迁移路径：Path A（库插件替换）、Path B（强制 Android 拆分）、Path C（全量重组，推荐用于单模块承载多平台入口的巨石composeApp），各路径完整指南见 MIGRATION-APP-SPLIT.md、MIGRATION-LIBRARY.md、MIGRATION-FULL-RESTRUCTURE.md
• 兼容性兜底：附带第三方插件兼容矩阵 PLUGIN-COMPATIBILITY.md 与版本对照 VERSION-MATRIX.md

✅选它，如果：你的 KMP 项目升级 AGP 后构建报错，或明确要升级到 AGP 9.0+。

3.3 CocoaPods 迁移 SwiftPM：kotlin-tooling-cocoapods-spm-migration

KMP 的 iOS 侧正在从 CocoaPods 转向 Swift Package Manager。该技能把迁移拆成8 个阶段：从分析现有cocoapods配置，到并行引入swiftPMDependencies {}DSL，再到最后安全移除 CocoaPods 插件并输出MIGRATION_REPORT.md报告。

关键细节：它会提醒你在第 6 阶段之前保持 CocoaPods 处于激活状态，避免迁移中途项目不可用；常见 Pod 的对应关系可查 common-pods-mapping.md，报错排查见 troubleshooting.md。

⚠️ 有版本门槛：Kotlin 2.4.0-Beta2+、Xcode 16.4 或 26.0+。

✅选它，如果：KMP + iOS 项目想从kotlin("native.cocoapods")平滑切换到 SwiftPM。

3.4 不可变集合升级：kotlinz… 0.5.x Migration

kotlinx.collections.immutable0.5.x 按 KEEP-0459 提案把持久化集合的复制方法全部重命名（add→adding、put→putting、set→replacingAt等），旧 API 被标记为WARNING级弃用警告。

这个技能的思路非常"工程师"：以编译器为驱动——升级版本号 → 重新编译 → 按弃用警告逐个重命名。它是纯机械式、二进制兼容、语义不变的重命名迁移，几乎零风险。

✅选它，如果：升级依赖后满屏出现 "Use adding() instead of add()" 之类的警告。

3.5 JPA 实体映射：kotlin-backend-jpa-entity-mapping

唯一的 backend 技能，专治 Kotlin + Spring Data JPA / Hibernate 的经典坑：

• data class做实体是高危操作：全字段的equals/hashCode会破坏Set/Map成员关系，copy()会制造游离的实体副本
• 覆盖实体设计规则、基于 ID 的相等性策略、唯一约束、关系与抓取计划（fetch plan）
• 能帮你诊断N+1 查询和LazyInitializationException等性能顽疾

✅选它，如果：你在 Kotlin 后端项目里新建/评审 JPA 实体，或 ORM 行为"看起来不对"。

四、选型速查：按你的场景直接对号入座

🎯一句话选型法则：看任务属于"迁移升级"还是"日常开发"——前四类是迁移工具，最后一个是日常后端规范。

五、安装方式：三种常用姿势

方式 1：skills CLI（最省事）

npx skills add Kotlin/kotlin-agent-skills

方式 2：Claude Code / Codex 插件市场

claude plugin marketplace add Kotlin/kotlin-agent-skills claude plugin install kotlin-agent-skills@Kotlin

Codex 用户在 shell 执行codex plugin marketplace add Kotlin/kotlin-agent-skills后，在交互界面执行/plugins搜索安装即可。

方式 3：手动复制（只装某一个技能）

先把仓库克隆到本地：

git clone https://gitcode.com/gh_mirrors/ko/kotlin-agent-skills

然后只拷贝需要的技能文件夹，例如：

cp -r skills/kotlin-tooling-agp9-migration .claude/skills/

💡新手建议：不确定要不要全装时，先用方式 3 手动装一个最匹配你场景的技能试试水，确认 AI 行为符合预期再考虑全量安装。

六、小结

kotlin-agent-skills 的价值在于把 JetBrains 团队在 Kotlin 工具链上的"踩坑经验"标准化成了 AI 可执行的技能：

1. 按需挑选：5 个技能互不依赖，哪个场景用到装哪个
2. 迁移类技能（AGP 9、SwiftPM、不可变集合）适合依赖升级期集中使用
3. JPA 实体技能适合长期留在 Agent 里，约束日常后端代码质量
4. 所有技能源码均遵循kotlin-<category>-<name>命名规范，存放在 skills/ 目录，想深入了解可阅读 CONTRIBUTING.md 了解贡献流程

希望这份选型指南能帮你少走弯路，让 AI Agent 真正成为 Kotlin 项目的得力助手 🚀