- name
- android-adb
- description
- Execute Android ADB (Android Debug Bridge) commands for device management, app management, debugging, and automation. Use when the user requests any ADB-related operation such as: (1) Device management — list/connect/disconnect devices, query device info, WiFi debugging; (2) App management — install/uninstall APKs, start/stop apps, clear data, manage permissions; (3) Debugging — logcat capture and filtering, crash log extraction, process inspection; (4) Screen capture — screenshots, screen recording; (5) Performance profiling — memory/CPU/battery/GPU stats; (6) File transfer — push/pull files between host and device; (7) Input simulation — tap, swipe, key events, text input; (8) Network control — WiFi/data toggle, proxy settings; (9) System info — device properties, display info, settings. Also triggers when the user says 'adb', mentions Android device operations, or asks to debug an Android app via command line.
Android ADB
Execute ADB commands via natural language or direct command input, with multi-device support, safety guardrails, and sandboxed ADB installation.
Workflow
- List devices: Directly run
adb devices -l. If the command fails (command not found), go to ADB Resolution to find or install adb, then retry. - Select device: If multiple devices connected, list them and ask user to choose. Prepend
-s <serial>to all subsequent commands. - Translate request to ADB command(s): Map the user's intent to appropriate ADB commands. See references/adb-commands.md for the full command reference.
- Safety check: If the command is destructive (see Dangerous Operations), show the command and ask for confirmation before executing.
- Execute and report: Run the command, parse output, and present results clearly.
ADB Resolution
When adb is not found, resolve using scripts/adb_env.sh which checks in order: system PATH → common SDK paths (~/Library/Android/sdk/, ~/Android/Sdk/) → sandbox local (<skill_dir>/tools/platform-tools/adb).
If none found, ask the user: "ADB 未安装，是否需要我帮你安装到 skill 本地目录？（不影响系统配置）"
If agreed, run bash <skill_dir>/scripts/install_adb.sh (no sudo, no PATH modification, uninstall via rm -rf <skill_dir>/tools/).
Multi-Device Handling
When adb devices -l returns multiple devices:
- Display a numbered list with serial, model, and Android version
- Ask the user to pick one (or "all" for broadcast)
- Store the chosen serial and use
-s <serial>for all commands in the session - Run
bash scripts/device_check.shin the skill directory for a quick overview
Safety Levels
| Level | Behavior | Examples |
|---|---|---|
| Safe | Execute directly | adb devices, logcat, screencap, getprop, pull, file listing |
| Moderate | Show command, then execute | install, push, am start, input tap, pm grant |
| Dangerous | Show command, explain risk, require explicit "yes" | pm clear, uninstall, factory reset, flash, wipe, reboot |
Quick Tasks
Device Info
bash <skill_dir>/scripts/device_check.shScreenshot
bash <skill_dir>/scripts/screenshot.sh [output_dir] [serial]Logcat Capture
bash <skill_dir>/scripts/logcat_capture.sh all [output_file] [serial]
bash <skill_dir>/scripts/logcat_capture.sh crash [output_file] [serial]
bash <skill_dir>/scripts/logcat_capture.sh app <package> [output_file] [serial]
bash <skill_dir>/scripts/logcat_capture.sh tag <TAG> [output_file] [serial]Long Output Rule
When the user requests any long-running or verbose log output (logcat streaming, dropbox dump, dumpsys, large trace output, etc.), unless the user explicitly specifies an output file, always open a new system terminal window to display the output. This gives the user a scrollable, stoppable, dedicated view without blocking the conversation.
Only write to file when the user explicitly says "保存到文件" / "输出到 xxx.txt" / provides a file path.
macOS
osascript -e 'tell app "Terminal" to do script "<adb_logcat_command>"'Linux (common DEs)
# GNOME
gnome-terminal -- bash -c '<adb_logcat_command>; exec bash'
# KDE
konsole -e bash -c '<adb_logcat_command>; exec bash'
# Fallback
x-terminal-emulator -e bash -c '<adb_logcat_command>; exec bash'Replace <adb_logcat_command> with the actual command, e.g.:
adb logcat— all logsadb logcat | grep -i "redirect" --line-buffered— filter by keywordadb logcat -s MyTag:D— filter by tagadb logcat --pid=$(adb shell pidof com.example.app)— filter by app
zsh compatibility
zsh treats * as a glob wildcard. When the command contains * (e.g. Tag:*), escape it in the osascript string:
# Wrong — zsh expands *
osascript -e 'tell app "Terminal" to do script "adb logcat -s MyTag:*"'
# Correct — escape the *
osascript -e 'tell app "Terminal" to do script "adb logcat -s MyTag:\\*"'After launching, report to the user that the terminal window has been opened and what command is running.
Common Scenarios
"Install this APK"
adb install -r <path.apk>If install fails, check: device storage (adb shell df -h), existing app version, test package flag (-t).
"Show me crash logs"
Two-level fallback:
- logcat crash buffer (first try):
adb logcat -b crash -d | grep <package>- dropbox (fallback if crash buffer is empty):
⚠️ 强制规则：严禁主动挑选 dropbox 条目。必须先列出所有条目，等用户选择后再输出内容。绝不允许跳过用户选择步骤。
Step 1 — 列出 dropbox 中所有 crash/anr 条目及其时间戳，供用户选择：
adb shell dumpsys dropbox | grep -E "^[0-9].*(_crash|_anr)" 输出示例：
2026-04-09 11:04:34 data_app_anr (compressed text, 23807 bytes)
Process: com.netease.cloudmusic:play/PID: 2553 ...
2026-04-09 10:23:45 data_app_crash (text, 1234 bytes)
Process: com.example.app/PID: 1234 ...Step 2 — 将列表完整呈现给用户（包含完整日期时间、类型、进程信息），然后必须等待用户明确选择要查看哪一条。严禁自行判断、自动选择最近一条或任何一条。
Step 3 — 用户选择后，打开新终端窗口展示对应条目：
# 使用用户选择的条目的时间戳
adb shell dumpsys dropbox --print '<tag>' --since <timestamp_ms>"Dump UI hierarchy"
Two-level fallback:
- uiautomator dump (first try):
adb shell uiautomator dump /sdcard/ui_dump.xml
adb pull /sdcard/ui_dump.xml <local_path>
adb shell rm /sdcard/ui_dump.xml- dumpsys activity top (fallback — some devices like Huawei may report
could not get idle state):
adb shell dumpsys activity top -a > <local_path>This outputs a text-based View Hierarchy instead of XML, but contains equivalent structural info.
"Screen recording"
adb shell screenrecord /sdcard/recording.mp4 # default max 180s
adb shell screenrecord --time-limit 30 /sdcard/recording.mp4 # limit to 30s
# Ctrl+C to stop, then pull:
adb pull /sdcard/recording.mp4 <local_path>
adb shell rm /sdcard/recording.mp4"Which app is in the foreground?"
adb shell dumpsys activity activities | grep mResumedActivity"App performance check"
adb shell dumpsys meminfo <package>
adb shell dumpsys gfxinfo <package>
adb shell dumpsys cpuinfo | grep <package>"Connect via WiFi"
adb tcpip 5555
# Note the device IP from:
adb shell ip route | grep wlan
adb connect <ip>:5555Dangerous Operations
Always confirm before executing any of:
pm clear— wipes app data permanentlyuninstall— removes apprm -rf— deletes files/directoriesreboot/reboot recovery/reboot bootloaderfactory reset/wipe_datafastboot flash— overwrites partitionspm disable-user— disables system appssettings put— modifies system/secure/global settingssetprop— changes system propertiessu/adb root— elevates to root privilegessideload— flashes OTA packages- Any command with
--user 0on system packages
Present the exact command and a one-line risk description, then wait for explicit confirmation.
Troubleshooting
| Issue | Fix |
|---|---|
device not found | Check USB cable, enable USB debugging in Developer Options |
device unauthorized | Accept RSA key prompt on device, or adb kill-server && adb start-server |
multiple devices | Use -s <serial> |
INSTALL_FAILED_* | Check error suffix — common: ALREADY_EXISTS (use -r), INSUFFICIENT_STORAGE, OLDER_SDK |
Permission denied | Try adb root or run-as <package> |
| Command hangs | Ctrl+C, then adb kill-server && adb start-server |
Reference
For the full ADB command cheat sheet organized by category, see references/adb-commands.md.