1. 为什么要在本地跑通 Android 官方 Skills
Android 官方在 2026 年推出了一套面向 Agent 的开发工具链，核心是两样东西：Android CLI 和 Android Skills。前者是一个android.exe可执行文件，把gradlew、adb、emulator、sdkmanager这些零散命令收拢成android <module> <action>的统一入口；后者是一批以SKILL.md为入口的能力模块，告诉 Agent「Android 项目该怎么建、怎么构建、怎么部署、怎么查文档」。
这套东西解决的真实痛点是：你让 Claude Code、Codex、Gemini CLI 这类 Agent 去改一个 Android 工程，它经常不知道gradlew在哪、不知道当前连了哪台设备、不知道 CameraX 的正确用法，于是开始瞎猜。装上 Skills 之后，Agent 手里就有了一份结构化的 Android 知识库和一套可调用的 CLI，调用链路才真正闭环。
适合谁：本地已经装了至少一个 Agent（Claude Code / CodeBuddy / Qoder / OpenClaw 等）、想用 Agent 写 Android 代码但被环境问题卡住的开发者。这篇会从SKILL.md结构讲到 Android CLI 初始化，再给一次完整的 Skills 加载与调用验证，命令都能直接复制。
2. 前置准备：Android CLI 安装与 SKILL.md 目录结构
2.1 安装 Android CLI
Windows 下注意一点：安装命令要在 CMD 里执行，PowerShell 跑不通。命令如下：
curl.exe -fsSL https://dl.google.com/android/cli/latest/windows_x86_64/install.cmd -o "%TEMP%\i.cmd" && "%TEMP%\i.cmd"执行过程大致是这样：
Installing android.exe... Downloading... Installing to C:\Users\daizh\AppData\AndroidCLI... Adding C:\Users\daizh\AppData\AndroidCLI to user PATH... Initializing CLI... Success! android is ready to use.装完之后去C:\Users\daizh\AppData\AndroidCLI看一眼，里面就一个android.exe。这一点很关键：如果安装脚本失败，你完全可以手动拿到这个android.exe，把它所在目录加进系统 PATH 就行，不需要重装。
验证安装：
android --version输出最后一行类似1.0.15498356，这就是当前版本号。顺手检查更新：
android update看到Already up-to-date with version 1.0.15498356.说明没问题。
2.2 SKILL.md 的结构长什么样
每个 Skill 就是一个目录，目录名即 Skill 名，里面至少有一个SKILL.md，还可以带几个可选子目录。官方对这几个目录的定位说得很清楚：
scripts/：Agent 可以运行的可执行代码，比如 Python 或 Bash。references/：详细技术文档、API 参考或领域指南。assets/：静态资源，比如文档模板、界面图或 JSON 架构。
在SKILL.md里引用这些文件时，用相对于技能根目录的路径，例如Run the script at scripts/cleanup.py。一个典型的 Skill 目录骨架：
android-cli/ ├── SKILL.md └── references/ ├── build.md ├── device.md └── skills.mdSKILL.md本身是给 Agent 读的说明书，负责回答两个问题：这个技能能干什么、具体怎么干。references/里放的是执行时按需加载的细节，这样SKILL.md可以保持简洁，不会一上来就把上下文塞满。
2.3 初始化 Android CLI 技能
先让 Agent 知道「有个 android.exe 存在，而且它能干活」：
android init执行结果：
Initializing android-cli skill... Skill 'android-cli' installed to C:\Users\daizh\.claude\skills\android-cli Skill 'android-cli' installed to C:\Users\daizh\.codebuddy\skills\android-cli Skill 'android-cli' installed to C:\Users\daizh\.openclaw\skills\android-cli Skill 'android-cli' installed to C:\Users\daizh\.qoder\skills\android-cliAndroid CLI 会自动探测本机装了哪些 Agent，然后把android-cli这个 Skill 分别写进各自的skills目录。从输出能看出一个通用规律：各家 Agent 的 Skill 都放在~/.<agent>/skills/下，SKILL.md是通用格式。这意味着你在 GitHub 上按 star 排序找一些高排名的 Skill，复制进对应目录就能直接用。
3. 可复制配置：批量安装 Android Skills
3.1 一次性装齐官方 Skills
android skills add --all这一步会从远端拉取官方 Skill 包。如果网络环境正常，你会看到进度条和一连串安装日志：
[========================================] 100% (679076/679076 bytes) Skill 'camera1-to-camerax' installed to C:\Users\daizh\.claude\skills\camera1-to-camerax Skill 'appfunctions' installed to C:\Users\daizh\.claude\skills\appfunctions Skill 'android-cli' installed to C:\Users\daizh\.claude\skills\android-cli ...装完之后~/.claude/skills目录大致是这样：
adaptive agp-9-upgrade android-cli appfunctions camera1-to-camerax display-glasses-with-jetpack-compose-glimmer edge-to-edge engage-sdk-integration jetpack-compose-m3 migrate-xml-views-to-jetpack-compose navigation-3 perfetto-sql perfetto-trace-analysis play-billing-library-version-upgrade r8-analyzer styles testing-setup verified-email一共 18 个官方 Skill，加上最开始android init装的android-cli，合计 19 个。每个目录里都是一个SKILL.md加一个references/。
3.2 查看和检索 Skills
列出当前可用的 Skill 列表：
android skills list输出是一串 Skill 名，比如camera1-to-camerax、appfunctions、perfetto-sql、jetpack-compose-m3等。这个命令会联网拉取列表，所以网络不通时可能返回空。
想装单个 Skill 而不是全量：
android skills install camerax搜索：
android skills search compose看某个 Skill 的详情：
android skills info camerax3.3 在 CLAUDE.md 里写清调用约定
Skill 装好了，还得让 Agent 知道什么时候该调。在项目的CLAUDE.md里加一段：
## Android CLI - 构建: android build - 部署: android device install - 日志: android device logs - 文档: android docs - 技能列表: android skills list注意别写成android deploy这种老式写法，现在官方已经规范到android <module> <action>结构了，写错 Agent 会调不到。
4. 验证请求：跑通一次完整的 Skills 加载与调用
4.1 确认命令树
先看整体帮助：
android --help输出里能看到完整的命令模块：
Commands: create Create a new Android project describe Analyzes an Android project to generate descriptive metadata. docs Android documentation commands emulator Emulator commands info Print environment information (SDK Location, etc.) init Initializes the environment (eg. skills) for Android CLI. layout Returns the layout tree of an application run Deploy an Android Application screen Commands to view the device sdk Download and list SDK packages skills Manage skills studio Android Studio commands update Update the Android CLI想看某个模块的细节，用子命令帮助：
android skills --help android device --help android docs --help4.2 让 Agent 真正调用一次
打开 Claude Code，在 Android 工程目录下提一个需要查文档的问题，比如：
帮我看下 CameraX 的 PreviewView 怎么和 ImageAnalysis 一起用，用 android docs 查一下官方文档再回答。Agent 会去读~/.claude/skills/android-cli/SKILL.md，发现里面写了android docs这个能力，于是执行：
android docs camerax这个命令会返回结构化的官方文档片段，比让 Agent 直接爬网页省 token，也更准。你可以在 Claude Code 的终端输出里看到它确实调用了android.exe，这就是调用链路跑通的标志。
再验证一个设备相关的：
android device list输出当前连接的设备列表，等价于adb devices但格式更规整。接着：
android device logs能实时看到日志流。Agent 在排查崩溃时就会用这条命令。
4.3 构建与部署验证
android build构建 debug APK。要 release 或 AAB：
android build release android build bundle部署到设备：
android device install app.apk android device launch截图和录屏：
android device screenshot android device record模拟器管理：
android emulator list android emulator start Pixel_9 android emulator stop测试：
android test android test connected android test compose这一整套跑下来，Agent 手里就有了从构建、部署、日志到测试的完整工具链，不再需要你手动敲gradlew和adb。
5. 本篇常见错排查
5.1android skills add --all下载失败
典型报错：
Error downloading skills: release-assets.githubusercontent.com这是拉取 Skill 包时网络不通。先确认基础网络，再检查是否需要给 JDK 配代理。注意 Android CLI 是 Java 程序，它不一定读 CMD 里set HTTPS_PROXY设的环境变量，得走 JVM 参数：
set JAVA_TOOL_OPTIONS=-Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=8082 -Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=8082设完之后再跑android skills add --all，你会看到输出里多了一行：
Picked up JAVA_TOOL_OPTIONS: -Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=8082 ...这说明 JVM 确实吃到了代理配置，下载就能走通。android skills list同理，它也要联网，没配代理会返回空列表。
5.2 PowerShell 里装不上
安装脚本在 PowerShell 下会失败，必须在 CMD 里跑。如果你习惯用 PowerShell，先cmd切过去再执行那条curl.exe命令。
5.3 Skill 装了但 Agent 不调用
先确认 Skill 目录真的存在：
dir C:\Users\daizh\.claude\skills\android-cli里面应该有SKILL.md和references/。如果目录在但 Agent 不调，检查CLAUDE.md里的命令写法是不是老式的android deploy，改成android device install这种规范写法。
5.4 Qoder 系列目录混乱
本机可能同时存在.qoder、.qoder-cli、.qoder-cn三个目录。android init只会写进.qoder，如果你用的是 Qoder 的 CLI 版本，可能读的是.qoder-cli。解决办法很简单：把.qoder/skills/android-cli整个目录复制到.qoder-cli/skills/和.qoder-cn/skills/下即可。
5.5 没有网络环境时的离线方案
官方 Skill 仓库在 GitHub 上，如果拉不下来，可以手动下载后复制到对应 Agent 的skills目录。每个 Skill 就是一个目录，复制过去就能用，不需要额外注册。Gitee 上也有镜像仓库可以备用。
6. 让 Agent 稳定调用 Android CLI 的下一步
Skill 装好只是第一步，真正影响体验的是 Agent 的模型能力和上下文管理。Android 工程动辄几十个模块，Agent 在长会话里很容易丢上下文，导致它忘了android docs这个能力存在。这时候可以考虑用 TaoToken 的 Coding Plan 来跑长期编码任务，它的上下文策略对 Agent 工作流更友好，配合 Android Skills 用下来，Agent 调用android.exe的稳定性会明显好一些。
如果你只是想先验证模型对 Android CLI 命令的理解，可以直接在模型对话里贴一段android --help的输出，让它解释每个模块的用途，快速判断模型是否吃透了这套工具链。接入相关的 Key 和文档在 API Keys 和接入文档里，按需取用即可。
最后给一个实用建议：把android skills list的输出存成一个skills-inventory.md放在项目根目录，每次 Agent 会话开始时让它先读这个文件，它就知道当前有哪些 Skill 可用，不用每次重新探测。这个习惯能省掉不少「Agent 不知道有某个 Skill」的来回。
