1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | agp-9-upgrade-android-skills |
| 项目自述名称 | agp-9-upgrade（SKILL.md frontmatter name 字段） |
| 作者/维护者 | Google LLC（Android 官方团队） |
| 来源链接 | https://github.com/android/skills/tree/main/build-system/agp/agp-9-upgrade |
| 许可证 | Apache License 2.0（GitHub API 确认，仓库级） |
| GitHub Stars / Forks | 6,773 / 408（GitHub API；为 android/skills 整个合集仓库的数据，不代表本条子技能单独热度） |
| 最新版本 | 仓库标签 v1.0.7（2026-08-07 发布）；本技能 SKILL.md 同日（2026-08-07）有更新（frontmatter last-updated 字段：2026-08-06） |
| 安装方式 | Android CLI 一条命令，或手动复制到对应 Agent 的 skills 目录（详见第 10 章） |
2. 功能介绍与亮点
这是 Google Android 官方团队发布的结构化技能，指导 Agent 把 Android 项目从旧版本升级到 Android Gradle Plugin（AGP）9，覆盖依赖版本核对（KSP、Hilt）、迁移到内置 Kotlin 支持、切换到新版 AGP DSL、kapt 到 KSP 的迁移、BuildConfig 自定义字段处理、清理过渡期 gradle.properties 标志位等完整流程，并附带编译验证步骤与已知第三方工具（Paparazzi）兼容性问题的排障说明。
亮点：
- 官方出品且是首批发布技能之一：作者为 Google LLC，AGP 9 迁移与 R8 配置分析是 2026 年 4 月 Android Developers Blog 公开发布
android/skills系列时点名的首批旗舰技能之一。 - 流程完整且带防护栏：明确列出“何时该先让用户在 Android Studio 里跑 AGP Upgrade Assistant”“不要写或运行 Python 脚本”“不要跑 clean 任务浪费时间”等具体操作边界，而非泛泛的迁移建议。
- 验证与排障闭环：给出 Gradle IDE sync、
./gradlew help、./gradlew build --dry-run三项验证步骤，并单列已知第三方库（Paparazzi 低版本）在 AGP 9 下的兼容性问题及应对。 - 持续高频维护：SKILL.md 于 2026-08-06 更新，配套版本标签 v1.0.7 于 2026-08-07 发布，为近期活跃维护的项目。
- 被独立第三方开发者博客正面引用：Android 开发者博客 Blundell（blog.blundellapps.co.uk）在介绍 Android Skills 生态时专门点名本技能，称其能“自动化项目升级到 AGP 9 的过程”。
3. 适用场景
固定分类：工程效率与代码质量。
适用于计划把 Android 项目升级到 Android Gradle Plugin 9 的工程师、需要处理 AGP 9 众多破坏性变更（新 DSL、内置 Kotlin、kapt 迁移等）而不想逐条翻release notes的团队，也适合刚接触 AGP 9 升级、希望有可靠自动化流程而非手工摸索的初中级 Android 开发者。不适用于 Kotlin Multiplatform（KMP）项目——技能本身明确声明不支持该场景。
4. 跨 Agent 兼容性
- Claude Code：✅ 原生支持（格式兼容）。
android/skills遵循开放的 Agent Skills 标准，技能目录就是标准 SKILL.md + YAML frontmatter + references 结构，可直接复制到.claude/skills/使用；技能内的验证步骤（./gradlew命令）依赖 Bash 工具权限，Claude Code 原生具备。 - Codex：✅ 官方确认支持。Android Developers Blog 与多篇第三方综述明确将 OpenAI Codex 列入该开放标准兼容的 Agent 名单。
- OpenClaw：⚠️ 未经本技能专门验证。第三方资料称 OpenClaw 的技能目录结构与 Agent Skills 开放标准兼容，但未见 android/skills 官方或针对本技能的专门确认。
- Hermes Agent：⚠️ 未经本技能专门验证。第三方资料称 Hermes Agent 遵循同一开放格式规范，但同样缺少官方或本技能专属的验证材料。
需注意：官方 Android CLI 默认仅为 Gemini 与 Antigravity 自动安装技能（未显式指定 Agent 时），面向 Claude Code / Codex 需手动指定或手动复制，详见第 10 章。
5. 推荐理由
AGP 9 带来大量破坏性变更（新 DSL、内置 Kotlin、kapt 迁移路径调整等），手工对照 release notes 逐项排查既耗时又容易漏项。这份官方技能把升级流程拆解成有明确验证节点的步骤清单，并预置了已知第三方库兼容性坑位的排障说明，能显著降低 Android 团队升级到 AGP 9 时的试错成本，对经验尚浅、还没踩过这些坑的开发者尤其有价值。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | Google Android 官方团队出品；仓库 6,773 stars 属整个合集非本技能专属（已在第 1 章注明），本技能自身除 Blundell 博客点名外暂无更充分的独立第三方证据 |
| 可用性 | 9 | 一条 CLI 命令或手动复制即用；文档完整（步骤化流程+多份 references+排障说明）；SKILL.md 2026-08-06 更新、配套版本 2026-08-07 发布；无付费依赖 |
| 安全性 | 9 | 详见下方安全检查清单 |
| 综合 | 8.33 | 三项均值 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令及权限范围 | 仅要求执行本项目已有的 Gradle 命令（./gradlew help、./gradlew build --dry-run）用于验证，且明确写明“不要运行 clean 任务”“不要写或运行 Python 脚本”，权限范围收敛、有明确用途说明 |
| ② 运行时联网外发 | 无，全程为本地文件（build.gradle、gradle.properties 等）编辑与本地构建校验，不涉及任何数据外发 |
| ③ API Key / 凭据 | 不需要 |
| ④ SKILL.md 与脚本可疑指令 | 已通读 SKILL.md 全文及其引用的迁移指南、release notes、排障文档，内容均为 AGP 官方迁移技术说明，未发现要求执行越权操作、外发数据或夹带无关推广内容的可疑指令 |
| ⑤ 作者/组织信誉 | Google LLC，Android 官方团队，AGP 本身即由该团队维护，信誉良好 |
| ⑥ License | Apache License 2.0，明确（仓库级） |
| ⑦ 最近维护时间 | SKILL.md 2026-08-06 更新，配套版本标签 2026-08-07 发布，非弃置项目 |
7. 跟同类 Skills 相比的优势
android/skills 合集仓库中其他官方子技能与本技能的定位差异：
| 名称 | 来源 | 定位 | 与本技能的差异 |
|---|---|---|---|
| agp-9-upgrade（本推荐） | android/skills | Android Gradle Plugin 9 构建系统升级全流程 | — |
| r8-analyzer | android/skills | 分析 R8/Proguard keep 规则，识别冗余与过宽规则以优化包体积 | 面向发布期包体积优化，不涉及构建工具链版本升级 |
| perfetto-trace-analysis | android/skills | 分析 Perfetto trace 定位延迟/内存/卡顿的根因 | 面向运行时性能问题排查，与构建期升级无交集 |
| perfetto-sql | android/skills | 把自然语言意图翻译为 Perfetto SQL 查询提取 trace 数据 | 是 perfetto-trace-analysis 的底层查询能力，同样与构建升级无关 |
| testing-setup | android/skills | 配置 Android 项目的测试框架与环境 | 面向测试基础设施搭建，不处理构建插件版本迁移 |
差异化总结：同属 android/skills 的其他子技能各自聚焦包体积优化、运行时性能排障、测试环境搭建等单点问题；agp-9-upgrade 是仓库内唯一处理“构建工具链主版本升级”这一高风险、高频破坏性变更场景的技能，且是官方 2026 年 4 月首批发布即点名的旗舰技能之一，成熟度与官方投入程度均高于后续陆续补充的子技能。
8. 用户评价
Android 开发者博客 Blundell（blog.blundellapps.co.uk）在介绍 Android Skills 生态的文章中专门点名本技能，将其列为该开放标准的“实践示例”之一，正面评价该格式“一个文件夹、一份 Markdown 文件、一份好的 description 就够了”的低门槛特性，并鼓励开发者参考本技能自建团队专属技能。除此之外，该技能目前在第三方平台尚无更多具名用户评价。
9. 其他补充
无。
10. 安装使用方式
方式一：Android CLI（官方推荐，一条命令）
android skills add --skill=agp-9-upgrade --project=.需先安装 Android CLI；未指定 --agent 时默认为 Gemini 与 Antigravity 自动安装，面向 Claude Code / Codex 需显式使用 --agent 参数指定，具体取值以官方文档为准。
方式二：手动安装（适用于 Claude Code / Codex）
git clone https://github.com/android/skills.git
cp -r skills/build-system/agp/agp-9-upgrade <你的项目>/.claude/skills/agp-9-upgrade复制时需保留 SKILL.md 与 references/ 目录的相对结构。安装后无需重启，Agent 会在识别到“升级到 AGP 9”“迁移 Android Gradle Plugin”类任务时自动触发，也可按各 Agent 自身语法手动调用。
11. 注意事项
- 明确不支持 Kotlin Multiplatform（KMP）项目的迁移，KMP 项目使用本技能前需先确认该限制。
- 技能要求项目当前 AGP 版本已经或即将达到 9；若低于 9，技能会提示先在 Android Studio 中运行 AGP Upgrade Assistant 更新到最新稳定版（用户也可要求跳过该前置步骤）。
- 部分依赖组件（如 Paparazzi 2.0.0-alpha04 及更低版本）与 AGP 9 存在已知兼容性问题，技能内已附排障说明但仍需人工确认版本适配。
- 建议在版本控制下操作并人工复核 diff，迁移正确性最终依赖 Gradle IDE sync 与
./gradlew build --dry-run的验证结果。 - OpenClaw、Hermes Agent 的兼容性未经本技能专门验证，使用前建议先在小范围试点。
- 官方 Android CLI 默认只为 Gemini / Antigravity 自动安装，Claude Code / Codex 用户需手动复制或显式指定
--agent参数。