Android CLI 与 Android Skills 最佳实践:把 AI Agent 接入可验证的 Android 开发流程

Android 开发接入 AI Agent 后，难点很快会从 Kotlin 代码生成转向工程执行：Agent 不知道本机 SDK 状态、拿不到设备界面、依赖了过期文档，或者修改完成后没有可靠的验收路径。

Google 推出的 Android CLI 和 Android Skills 分别补了这两块：Android CLI 给 Agent 一组可执行、可返回结构化结果的 Android 工具；Android Skills 用 SKILL.md 固化具体任务的官方工作流、约束和参考资料。二者配合后，Agent 才能从「生成一段代码」走到「读取工程、查官方文档、修改代码、部署设备、检查结果」。

本文基于 2026 年 8 月 11 日的环境核验：Android CLI 版本为 1.0.15985488，android/skills 仓库最新标签为 v1.0.7，仓库中共有 22 个 SKILL.md。这套工具仍在快速更新，文中的命令应结合本机 android help 和 android <command> --help 使用。

Key Takeaways

• Android CLI 提供环境、文档、工程、设备、界面与 Android Studio 的可执行入口；Android Skills 用 SKILL.md 固化任务级操作规程。两者解决不同问题：执行 vs 工作流。
• 把 Agent 任务拆成六阶段：建立环境基线、选择技能、查询资料、修改与静态检查、部署、UI 或性能验收。最容易省略的是第 1 步和第 6 步。
• 按任务安装少量 Skill，提示词写清范围与验收条件，高风险修改采用「分析」与「执行」两阶段，最终以编译、测试、布局、截图或 trace 结果判断完成。

Android CLI 解决的是执行问题

Android CLI 是面向 Android 开发工具和 AI Agent 的统一命令行入口。它没有替代 Gradle、ADB、SDK Manager 或 Android Studio，而是把常见操作整理成更容易发现、调用和解析的命令。

当前版本的主要能力可以分为五组：

能力	常用命令	适合解决的问题
环境与 SDK	android info、android sdk list/install/update/remove	确认 SDK 路径、补齐平台和构建工具、减少环境猜测
工程与构建产物	android create、android describe	从模板创建工程，生成模块与 APK 产物的结构化描述
设备与模拟器	android emulator、android install、android run	管理 AVD，安装 APK，启动 Activity、Service、Wear OS 组件
界面检查	android layout、android screen capture/resolve	获取布局树、截图和可点击坐标，支持 UI 调试与自动化
文档与 IDE	android docs、android studio	查询官方知识库，连接 Android Studio 做符号、检查和 Compose Preview 操作

这层能力的价值在于让 Agent 拿到证据。例如，排查「登录按钮被导航栏遮住」时，只有代码生成能力还不够。Agent 至少要知道当前设备、运行中的 APK、布局树和屏幕截图，修改后还要重新部署并检查按钮位置。

安装与初始化

官方安装页提供 macOS、Linux 和 Windows 的安装包。安装完成后，先确认版本、SDK 路径和设备状态：

android --version
android info
android help

android info 会输出 CLI 使用的 SDK 路径。机器上存在多个 Android SDK 时，可以通过全局参数临时指定：

android --sdk="$HOME/Library/Android/sdk" info

随后运行初始化命令，让 Agent 获得 Android CLI 的使用说明：

android init

初始化不是项目构建步骤，它负责准备 CLI 配置和默认技能。团队脚本仍应显式检查 Java、Gradle、SDK package 和设备状态，不能把环境前提全部交给初始化命令。

公司内部开发环境还是要注意下数据收集说明。Android CLI 官方文档的「Data collected」章节有声明，Android CLI 会记录命令与子命令的调用、非位置参数名称、部分预定义选项值，以及匿名化后的异常堆栈；不会收集 CLI 返回内容、用户自定义输入、Maven 坐标、本地文件路径或项目名称。涉及内部项目时，需要按公司的开发工具与网络策略综合评估。

用 docs 查询官方资料

Agent 写 Android 代码时，版本知识过期比语法错误更难发现。android docs 使用两步式查询：先搜索知识库，再根据返回的 kb:// 地址获取正文。

下面的命令用于查找 edge-to-edge 的官方说明：

android docs search "edge-to-edge Compose system bars"
android docs fetch kb://android/develop/ui/compose/system/setup-e2e

第二条命令中的 kb:// 地址要使用搜索结果返回的真实值，不能预先拼接。把「先搜索、再读取来源」写进任务要求，可以减少 Agent 依赖记忆回答 API 版本、迁移步骤和兼容性问题。

用 describe 消除工程结构猜测

多模块项目里（参见 {% post_link '2016-04-20-Android Gradle最佳实践系列5' 'Gradle 多模块构建' %}），Agent 经常会猜错应用模块、构建变体或 APK 路径。describe 会分析项目并输出描述构建目标和产物位置的 JSON 文件路径：

android describe --project_dir=.

这条命令适合放在部署动作之前。Agent 应先读取结果，再决定使用哪个 APK，而不是默认产物总在 app/build/outputs/apk/debug/app-debug.apk。

现有工程的编译仍应调用仓库自己的 Gradle Wrapper。一个稳定的顺序如下：

./gradlew :app:assembleDebug
android describe --project_dir=.
android run --apks=app/build/outputs/apk/debug/app-debug.apk \
  --device=emulator-5554

android run 负责部署并启动组件。只安装、不启动时使用 android install。新版本还提供 --use-delta-install，它会在增量迭代中减少传输量；首次安装、安装异常或需要排除增量状态影响时，可以关闭这项优化并重新安装。

布局树与截图要配合使用

android layout 返回当前应用的布局树 JSON。排查文本、可访问性属性、节点边界和层级变化时，它通常比只看截图更直接：

android layout --pretty --output=artifacts/layout.json
android layout --diff

--diff 返回相对上一次布局快照发生变化的元素，适合检查点击、展开、键盘弹出后的 UI 状态。

截图处理的是布局树表达不了的问题，例如颜色对比度、图像裁切、系统栏图标是否清楚、元素是否发生视觉遮挡：

android screen capture --output=artifacts/home.png
android screen capture --annotate --output=artifacts/home-annotated.png

验收 UI 时不要在两者之间二选一。布局树负责回答「节点在哪里、属性是什么」，截图负责回答「最终画面是什么样」。涉及点击自动化时，还可以用 screen resolve 把带编号标注的截图目标转换为坐标：

android screen resolve \
  --screenshot=artifacts/home-annotated.png \
  --string="input tap #5"

screen resolve 只识别 screen capture --annotate 生成的编号，普通截图不能直接用于坐标替换。

studio 命令把 IDE 能力开放给 Agent

Android CLI 新增了 studio 命令，可连接正在运行的 Android Studio（从早期的 {% post_link '2015-10-04-AndroidStudio-Develop-Guide' 'AndroidStudio 插件效率工具' %} 到如今 CLI 化的 Agent 工具，IDE 能力正在向可被 Agent 调用的方向演进），执行以下操作：

• find-declaration 和 find-usages：使用 IDE 索引查定义与引用，适合 Kotlin、Java 和资源符号定位。
• analyze-file：返回指定文件中的错误、警告和 Lint 问题。
• render-compose-preview：渲染 Compose Preview，并可输出图片和语义树。
• version-lookup：查询 Maven 依赖、Android 版本等当前可用版本。

这部分目前有明确前提：项目需要在 Android Studio Quail 2 Canary 1 或更高版本中打开，同时启用并登录 Gemini in Android Studio（见 Android CLI 文档的 studio 命令说明）。使用前先检查连接状态：

android studio check

IDE 没有连接时，应回到 Gradle、源码检索和设备验证，不要让整个任务卡在 studio 子命令上。

Android Skills 解决的是工作流问题

Android Skills 是遵循 Agent Skills 开放规范 的模块化说明。每个技能以 SKILL.md 为入口，可以附带 references/、scripts/ 和其他资源。Agent 根据技能的 name 与 description 判断当前任务是否需要加载它，再按正文中的步骤和约束执行。

一个 Skill 通常包含四类信息：

• 触发条件：说明什么任务应该使用该技能，避免只凭技能名称匹配。
• 执行顺序：规定先检查什么、运行什么命令、在哪些条件下切换分支。
• 领域约束：记录版本门槛、禁止项、验证方式和输出格式。
• 配套资源：提供官方文档副本、脚本、查询模板或报告模板，减少临时搜索和现场编造。

官方仓库没有追求覆盖所有 Android 基础知识。README 明确说明，技能建设优先选择评测中 LLM 表现较弱的任务，基本 Compose 最佳实践这类模型已经较熟悉的内容并非当前重点。

这个取向决定了 Skills 的正确用法：把它当作任务级操作规程，不把它当作 Android 百科全书。

当前技能覆盖了哪些任务

截至本文核验时，官方仓库有 22 个技能。下面按工作类型归类，具体列表以 android skills list --long 为准：

类型	代表技能	它补充的能力
构建与体积	agp-9-upgrade、r8-analyzer	版本迁移、R8 配置检查、量化或启发式规则分析
性能分析	perfetto-sql、perfetto-trace-analysis	生成有效的 Perfetto SQL，沿线程状态和依赖关系定位瓶颈
UI 与迁移	edge-to-edge、adaptive、navigation-3、migrate-xml-views-to-jetpack-compose	系统栏适配、自适应布局、导航和 View 到 Compose 迁移
测试	testing-setup	识别现有测试栈，配置单元、UI、截图和端到端测试
安全与合规	android-intent-security、play-policy-insights	Intent 安全审计、权限和 Play 政策检查
设备形态与媒体	wear-compose-m3、leanback-to-compose-tv-migration、camerax、media3-cast-integration	Wear OS、TV、CameraX 和 Cast 的专项实现约束

同一个技能也可能包含严格边界。r8-analyzer 默认只分析并输出报告，不允许直接修改文件（SKILL.md 明确写明「No code changes: Research and suggest only; Do not modify files」）；perfetto-trace-analysis 要求先在证据链（Chain of Evidence）中记录已验证证据，再沿线程阻塞关系追到依赖方，不能在等待中的线程上结束分析；edge-to-edge 要求检查 targetSdk、Activity、列表、FAB 和 IME，避免只加一行 enableEdgeToEdge() 就结束任务。

这些限制比一段「请按最佳实践修改」的提示词更可靠，因为 Agent 能看到明确的步骤、分支和完成条件。

安装 Skills：先按项目，再按任务

查看可用技能和详细说明：

android skills list --long
android skills find performance

给当前项目安装一个技能：

android skills add r8-analyzer --project=.

安装全部技能：

android skills add --all --project=.

官方 README 和本机 CLI 在预览期可能出现参数形式差异。本文实测版本使用位置参数 r8-analyzer，官方 README 和 CLI 文档 展示的都是 --skill=r8-analyzer。遇到这种情况，先运行：

android skills add --help

项目级安装适合团队共享。Skill 跟随仓库后，每位开发者和 CI Agent 可以使用同一版操作规程（CI 集成可参考 {% post_link '2016-05-02-Android Gradle最佳实践系列8' 'Gradle 与 CI 集成实践' %}），也方便在代码评审里查看技能更新。全局安装更适合 android-cli、perfetto-sql 这类跨项目通用技能。

不建议默认执行 --all。技能越多，Agent 的可选路径越多，触发冲突和读取无关材料的概率也越高。更稳妥的配置是：

1. 全局保留 android-cli，让 Agent 知道如何查询环境、文档、设备和技能。
2. 项目内只安装当前技术栈需要的技能，例如 Compose 项目安装 edge-to-edge 和 testing-setup（测试基础设施可参考 {% post_link '2023-02-20-Android单元测试实践' 'Android 单元测试实践' %}）。
3. 碰到专项任务再安装 r8-analyzer、perfetto-trace-analysis 或迁移类技能。
4. 使用 android skills list --long --project=. 定期检查安装位置和状态。

android skills add 也承担更新功能。官方文档提醒，自定义官方技能时要先改名，否则下次更新会覆盖修改。团队自己的规则应放在独立技能中，不要直接改官方目录。

一条可复用的 Agent 工作流

Android CLI 与 Android Skills 配合时，可以把任务分成六个阶段：

阶段	Agent 应做的事	证据
1. 建立环境基线	读取项目规则，运行 android info，确认 Gradle 与设备	CLI 版本、SDK 路径、设备序列号、Git 状态
2. 选择技能	根据任务查找并加载一个主技能，必要时增加一个辅助技能	技能名称、适用条件、版本前提
3. 查询最新资料	使用 android docs search/fetch 或技能附带参考资料	官方文档地址、适用 API 或库版本
4. 修改与静态检查	按技能步骤改代码，运行目标模块测试、Lint 或 studio analyze-file	diff、编译结果、测试结果、Lint 输出
5. 部署与交互	用 describe 确认 APK，再使用 install/run 部署	APK 路径、设备、启动组件、命令退出状态
6. UI 或性能验收	使用布局树、截图、Compose Preview 或 Perfetto 数据检查	JSON、PNG、trace 查询结果、失败分支

这里最容易省略的是第 1 步和第 6 步。没有环境基线，Agent 会在错误的 SDK、模块或设备上工作；没有最终证据，「代码已经修改」只能证明文件发生了变化，不能证明问题已经解决。

示例：修复 Compose 页面 edge-to-edge 问题

一个可执行的任务描述应包含目标、范围、约束和验收方式：

修复登录页在 Android 15 上被状态栏、导航栏和 IME 遮挡的问题。

要求：
- 使用项目中的 edge-to-edge Skill，并先检查它的前置条件。
- 只修改登录流程相关 Activity、Composable、Manifest 和测试。
- 保留当前 Material 3 主题，不引入新的 UI 框架。
- 先用 android docs 查询当前 edge-to-edge 与 IME 官方说明。
- 修改后运行相关编译和测试，部署到 emulator-5554。
- 分别记录键盘关闭、键盘打开时的 android layout 输出和截图。
- 报告改动文件、验证命令、结果和仍未覆盖的设备形态。

这段任务会引导 Agent 读取 edge-to-edge Skill 中的完整检查项：targetSdk 35+、enableEdgeToEdge() 的位置、Scaffold 的 PaddingValues、insets 是否重复消费、adjustResize 和 IME 处理。验收又会迫使它检查运行结果，避免只完成源码层修改。

示例：分析 R8 规则时不要授权自动删除

R8 keep rule 涉及反射、序列化、JNI 和三方库 consumer rules。删除一条看似宽泛的规则，可能只在 Release 包的某条低频路径上崩溃。

适合给 Agent 的任务是：

使用 r8-analyzer 分析 app 模块的 Release R8 配置。
只生成报告，不修改 proguard-rules.pro 或 Gradle 文件。
报告中区分可量化结果与启发式判断，并列出每条建议需要覆盖的回归场景。

官方 Skill 会根据 AGP 与 R8 版本选择独立 Gradle task、量化分析或启发式检查。它还明确限制「只分析，不改文件」。先保留这条边界，人工确认反射入口和回归测试（用 Gradle 编排测试任务可参考 {% post_link '2016-04-25-Android Gradle最佳实践系列6' 'Gradle 运行测试任务' %}）后，再创建单独的修改任务。

示例：Perfetto 分析必须沿等待关系继续查

性能任务最怕把「长 slice」直接当成「CPU 执行很久」。线程可能处于 Runnable、Sleeping 或 Uninterruptible Sleep（相关虚拟机与内存背景可参考 {% post_link '2021-07-15-深入理解Java和Android中的内存管理（一）：虚拟机' 'Android 内存与虚拟机基础' %}），处理方式完全不同。

perfetto-trace-analysis Skill 要求查询可疑时间窗内的 thread_state。如果线程在等待，还要继续检查 Binder、锁或 I/O 依赖，不能停在调用方。一个合格的任务描述应提供 Perfetto trace 文件、目标包名、问题时间范围和用户可感知现象，并要求每条结论附 SQL 或指标结果。

Agent 最终应该交付一条证据路径，例如：

掉帧区间 -> 主线程 slice -> thread_state=Sleeping
-> Binder transaction -> system_server 对应线程
-> 锁等待或 I/O slice -> 根因与影响范围

如果只得到「主线程某函数耗时 45 ms」，分析还没有完成。

提示词要写验收条件，不要复述技能正文

安装 Skill 之后，无需把 SKILL.md 全文粘进提示词。提示词应该补充技能无法预先知道的项目上下文：

• 目标：要修复哪个用户问题，或者要回答哪个技术问题。
• 范围：允许修改哪些模块、文件和构建配置，哪些内容禁止改动。
• 环境：目标 API、设备序列号、构建变体、入口 Activity、trace 路径。
• 证据：必须运行哪些测试、输出哪些报告、保存哪些截图或布局树。
• 停止条件：什么情况下需要先报告风险，例如依赖升级、数据迁移、公开 API 变更。

「帮忙适配 edge-to-edge」只给了主题。「修复登录页在 Android 15 上被 IME 遮挡，限制修改登录模块，部署到指定模拟器，并提供键盘开关两种状态的布局树与截图」才给出了任务。

使用时需要守住的六条边界

1. 每次先确认 CLI 版本和 help

Android CLI 与 Skills 仍在更新。本文核验时，官方 README、开发者文档和本机 --help 已经出现过参数写法差异。脚本中可以固定已验证版本；交互式使用时先查本机 help。

2. Skill 是操作规程，不是正确性证明

Skill 可以改善 Agent 的步骤和判断依据，但不会消除模型错误。官方仓库 README 也明确要求复查结果。代码仍需经过编译、测试、Lint、设备或 trace 证据验证。

3. 一个任务只设一个主技能

主技能负责决定工作流，其他技能只补充局部能力。例如 edge-to-edge 改造以 edge-to-edge 为主，testing-setup 只在项目缺少对应测试基础设施时介入。多个技能同时给出不同的修改顺序和输出约束时，应先拆分任务。

4. 官方技能与团队技能分开维护

官方技能通过 android skills add 更新，团队技能记录内部架构、构建命令、测试设备和发布门禁。二者目录和名称分开，可以避免升级覆盖，也便于追踪规则来源。

5. 高风险修改采用「分析」和「执行」两阶段

依赖升级、R8 规则删除、数据库迁移、Manifest 导出组件修改先生成分析报告，再开独立任务执行。这样可以让代码评审聚焦于已经确认的变更范围，也能减少 Agent 一边调查一边扩大修改面的情况。

6. 把产物纳入评审

除代码 diff 外，UI 任务提交截图和布局树，性能任务提交 trace 查询与时间窗，构建任务提交 APK/Bundle 信息，迁移任务提交测试和兼容性清单。可复查的产物越具体，越容易发现 Agent 的判断偏差。

团队接入建议

小范围试用时，可以先选一个边界明确、容易验收的任务，例如 edge-to-edge、R8 规则分析或测试基础设施盘点。不要从大型架构迁移开始。

项目中建议维护以下内容：

project/
├── AGENTS.md                    # 项目构建、测试、目录和禁止项
├── skills/                      # 示例；实际目录由 CLI 与 Agent 约定决定
│   ├── edge-to-edge/
│   │   └── SKILL.md
│   └── team-release-check/
│       ├── SKILL.md
│       ├── references/
│       └── scripts/
└── artifacts/                   # 本地或 CI 生成，不一定提交仓库
    ├── layout/
    ├── screenshots/
    └── reports/

AGENTS.md 写项目级稳定规则，Skill 写某类任务的执行步骤。两者不要重复整段内容。团队自己的 Skill 还应带最小可运行脚本和输出模板，让 Agent 在不同工具中得到相近结果。

接入效果可以用四个指标观察：首次执行成功率、人工返工次数、无证据结论数量、从任务开始到得到可复查产物的时间。只统计生成了多少代码，无法判断工具是否改善了工程过程。

总结

Android CLI 提供环境、文档、工程、设备、界面和 Android Studio 的执行入口；Android Skills 提供具体 Android 任务的步骤、约束和参考资料。CLI 让 Agent 能做事，Skills 让它按经过整理的流程做事。

稳定的用法可以压缩为一句话：按任务安装少量 Skill，用 Android CLI 获取环境和运行证据，在提示词里写清范围与验收条件，最终以编译、测试、布局、截图或 trace 结果判断任务是否完成。

参考资料

• Android CLI 官方文档
• Android Skills 官方文档
• android/skills GitHub 仓库
• Agent Skills 开放规范