Skip to content

Commit 0877e7a

Browse files
denverscdenversc
committed
ai/skills: add android-cli
1 parent 438c302 commit 0877e7a

4 files changed

Lines changed: 403 additions & 0 deletions

File tree

‎ai/skills/android-cli/SKILL.md‎

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
---
2+
name: android-cli
3+
description: Orchestrates Android development tasks including project creation, deployment, SDK management, and environment diagnostics using the `android` command-line tool.
4+
---
5+
# Android CLI Specialist
6+
7+
This skill provides instructions for using the `android` CLI tool. The tool includes various commands for creating projects, running applications, interacting with devices, and managing the CLI environment.
8+
9+
## Installation
10+
11+
If the android tool is not in the path, install it. To install run the following command:
12+
Linux: curl -fsSL https://dl.google.com/android/cli/latest/linux_x86_64/install.sh | bash
13+
Mac Arm: curl -fsSL https://dl.google.com/android/cli/latest/darwin_arm64/install.sh | bash
14+
Mac Intel: curl -fsSL https://dl.google.com/android/cli/latest/darwin_x86_64/install.sh | bash
15+
Windows: curl -fsSL https://dl.google.com/android/cli/latest/windows_x86_64/install.cmd -o "%TEMP%\i.cmd" && "%TEMP%\i.cmd"
16+
17+
## SDK management
18+
To manage the installation of Android SDKs and tools, use the `sdk` command. For example:
19+
20+
- `android sdk install <package>[@<version>]...`: Install specific packages. Multiple packages can be specified, separated by spaces. `<version>` defaults to latest. For example: `android sdk install platforms/android-30@2 platforms/android-34`
21+
- `android sdk update [<pkg-name>]`: Update a specific package or all packages to the latest version.
22+
- `android sdk remove <pkg-name>`: Remove a package from the local SDK.
23+
- `android sdk list --all`: List installed and available SDK packages.
24+
25+
## Project creation
26+
Create projects from templates using the `create` command.
27+
28+
For example: `android create empty-activity --name="My App" --output=./my-app`
29+
30+
## Interacting with devices
31+
For more information on interacting with running devices, see [here](references/interact.md)
32+
33+
## Running journey tests
34+
For more information on running journeys, see [here](references/journeys.md)
35+
36+
## Doc searching
37+
The `docs` command searches authoritative, high-quality Android developer documentation in the Android Knowledge Base.
38+
By providing a few keywords, this tool will return high quality articles that contain examples or guidance on how to use Android APIs or libraries.
39+
Use this tool to obtain additional information on how to achieve Android-specific tasks or to know more about Android APIs, surfaces, libraries, or devices.
40+
41+
Always use this tool to get the most up-to-date information about Android concepts. Typical good use cases are:
42+
- Finding migration guides for APIs.
43+
- Finding examples for APIs.
44+
- Finding up-to-date information about Android APIs.
45+
- Finding best practices for Android concepts.
46+
47+
## Running APKs
48+
Use the `run` command to run Android apps.
49+
50+
## Managing emulators
51+
52+
Manage Android Virtual Devices (AVDs) using the `android emulator` command
53+
54+
## Capturing screenshots
55+
56+
Capture an image of the current screen of a connected Android device and output it to a file using the `android screenshot` command.
57+
58+
## Managing skills
59+
60+
Manage antigravity agent skills for Android using the `android skills` command.
61+
62+
## Inspecting UI Layouts
63+
64+
Use the `android layout` command to inspect the UI layout of an Android application. It returns the layout tree of an Android application in JSON format. When debugging UI errors, this is often a much faster approach than taking a screenshot.
65+
66+
## Updating the CLI
67+
68+
Update the Android CLI using the `android update` command.
69+
70+
# `android help` output
71+
72+
Usage: android [-hV] [--sdk=PARAM] [COMMAND]
73+
-h, --help Show this help message and exit.
74+
--sdk=PARAM Path to the Android SDK
75+
-V, --version Print version information and exit.
76+
Commands:
77+
create Create a new Android project
78+
describe Analyzes an Android project to generate descriptive metadata.
79+
docs Android documentation commands
80+
emulator Emulator commands
81+
help Shows the help of all commands
82+
info Print environment information (SDK Location, etc.)
83+
init Initializes the environment (eg. skills) for Android CLI.
84+
layout Returns the layout tree of an application
85+
run Deploy an Android Application
86+
screen Commands to view the device
87+
sdk Download and list SDK packages
88+
skills Manage skills
89+
studio Android Studio commands
90+
update Update the Android CLI
91+
92+
create
93+
Usage: android create [-h] [--verbose] [--list] [--minSdk=api]
94+
--name=applicationName [-o=dest-path] [template-name]
95+
Create a new Android project
96+
[template-name] The template name
97+
-h, --help Show this help message and exit.
98+
--minSdk=api The 'minSdk' supported by the application (default
99+
is defined in the template)
100+
--name=applicationName
101+
The name of the application (e.g. 'My Application')
102+
-o, --output=dest-path The destination project directory path (default is
103+
'.')
104+
--verbose Enables verbose output
105+
--list List all available templates
106+
107+
describe
108+
Usage: android describe [-hV] [--project_dir=PARAM]
109+
Analyzes an Android project to generate descriptive metadata.
110+
This command identifies and outputs the paths to JSON files that detail the
111+
project's structure, including build targets and their corresponding output
112+
artifact locations (e.g., APKs). This information enables other tools and
113+
commands to locate build artifacts efficiently.
114+
-h, --help Show this help message and exit.
115+
--project_dir=PARAM The project directory to describe
116+
-V, --version Print version information and exit.
117+
118+
docs
119+
Usage: android docs [-h] [COMMAND]
120+
Android documentation commands
121+
-h, --help Show this help message and exit.
122+
Commands:
123+
search Search Android documentation
124+
fetch Fetch Android documentation
125+
126+
emulator
127+
Usage: android emulator [-h] [COMMAND]
128+
Emulator commands
129+
-h, --help Show this help message and exit.
130+
Commands:
131+
create Creates a virtual device
132+
start Launches the specified virtual device. This command will return when
133+
the emulator is fully started and ready to use.
134+
stop Stops the specified virtual device
135+
list Lists available virtual devices
136+
remove Delete a virtual device
137+
138+
help
139+
Usage: android help [COMMAND]
140+
Shows the help of all commands
141+
[COMMAND] The command to show help for
142+
143+
info
144+
Usage: android info <field>
145+
Print environment information (SDK Location, etc.)
146+
<field> The specific field to print the value of. If omitted print all.
147+
148+
init
149+
Usage: android init
150+
Initializes the environment (eg. skills) for Android CLI.
151+
152+
layout
153+
Usage: android layout [-dhp] [--device=PARAM] [-o=PARAM]
154+
Returns the layout tree of an application
155+
-d, --diff Returns a flat list of the layout elements that have
156+
changed since the last invocation of ui-dump
157+
--device=PARAM The device serial number
158+
-h, --help Show this help message and exit.
159+
-o, --output=PARAM Writes the layout tree to the specified file or
160+
directory. If omitted, prints the tree to standard
161+
output
162+
-p, --pretty Pretty-prints the returned JSON
163+
164+
run
165+
Usage: android run [-h] [--debug] [--activity=PARAM] [--device=PARAM]
166+
[--type=PARAM] [--apks=PARAM[,PARAM...]]...
167+
Deploy an Android Application
168+
--activity=PARAM The activity name
169+
--apks=PARAM[,PARAM...]
170+
The paths to the APKs
171+
--debug Run in debug mode
172+
--device=PARAM The device serial number
173+
-h, --help Show this help message and exit.
174+
--type=PARAM The component type (ACTIVITY, SERVICE, etc.)
175+
176+
screen
177+
Usage: android screen [-h] [COMMAND]
178+
Commands to view the device
179+
-h, --help Show this help message and exit.
180+
Commands:
181+
capture Outputs the device screen to a PNG
182+
resolve Target UI elements visually
183+
184+
sdk
185+
Usage: android sdk [COMMAND]
186+
Download and list SDK packages
187+
Commands:
188+
install Install SDK packages
189+
update Update one or all packages to the latest version
190+
remove Remove a package from the SDK
191+
list List installed and available SDK packages
192+
193+
skills
194+
Usage: android skills [COMMAND]
195+
Manage skills
196+
Commands:
197+
add Install a skill
198+
remove Remove a skill
199+
list List available skills
200+
find Find skills by keyword
201+
202+
studio
203+
Usage: android studio [-h] [COMMAND]
204+
Android Studio commands
205+
-h, --help Show this help message and exit.
206+
Commands:
207+
find-declaration Find declaration of a symbol
208+
find-usages Find usages of a symbol
209+
open-file Open a file in Android Studio
210+
check Check the status of running Studio instances
211+
analyze-file Analyze a file in Android Studio
212+
render-compose-preview Render a Compose preview in Android Studio
213+
version-lookup Looks up the latest available versions on the
214+
internet of maven artifacts, Android versions, and
215+
more.
216+
217+
update
218+
Usage: android update [--url=PARAM]
219+
Update the Android CLI
220+
--url=PARAM The URL to download the update from
221+

‎ai/skills/android-cli/references/interact.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Tools
2+
Run `android layout --help` and `android screen --help`.
3+
4+
## UI Dump
5+
`android layout` returns a flat JSON list of the UI elements on screen.
6+
`android layout --diff` returns a flat JSON list of the UI elements that have changed since the last call to `layout` or `layout --diff`
7+
8+
Each JSON object represents a UI element in the Android app. The following properties may be present:
9+
- `text` - any literal text the element contains
10+
- `resourceId` - the Android resource id used to refer to the element
11+
- `contentDesc` - a description of a UI element for use by accessibility tools
12+
- `interactions` - the set of user interactions the element supports. May contain one or more of: `checkable`, `clickable`, `focusable`, `scrollable`, `long-clickable`, `password`
13+
- `state` - the set of states the element is in. May contain one or more of `checked`, `focused`, `selected`
14+
- `bounds` - the screen coordinates of the bounding rectangle of the element, in the format `[min X,min Y][max X, max Y]`
15+
- `center` - the screen coordinates of the center of the element, in the format `[x,y]`
16+
- `off-screen` - if true, the element is in the UI hierarchy but not visible; it may require scrolling to view.
17+
18+
Use `layout` as a primary means of examining an Android app. Use `layout --diff` to focus on changes and to keep your context small.
19+
Example: When entering digits into a calculator, use `layout --diff` to output only the digit readout element.
20+
21+
`layout` may fail due to the app displaying a WebView or animation; in these cases, use `android screen --annotate` to inspect the app.
22+
This failure will likely resolve after navigating away from the current screen.
23+
24+
## Screenshot
25+
`android screen capture -o <file path>` saves a PNG of the current device screen to `<file path>`
26+
27+
Use `screen capture` as a secondary means of examining an Android app
28+
Examples:
29+
- Understanding the content of an on-screen image
30+
- Looking at a `WebView` (web content does not always appear in the ui dump)
31+
- Trying to find a UI element by its visual appearance
32+
33+
**IMPORTANT**: Always *VISUALLY* examine the PNG image returned from `android screen` BEFORE doing anything else.
34+
35+
## Annotated Screenshot
36+
`android screen capture --annotate -o <file path>`
37+
`android screen resolve --screen <path> --string <string>`
38+
39+
The `--annotate` command adds numerical labels and bounding boxes around UI elements. Use this command to locate UI elements that cannot
40+
be located in the `layout` output.
41+
42+
**IMPORTANT**: When using `android screen --annotate`, always *VISUALLY* examine the resulting PNG file.
43+
44+
To refer to these labels in input commands, use `screen resolve` to convert labels into coordinates:
45+
46+
`android screen resolve --screen <file path> --string "#3"` returns `<x coord of region 3> <y coord of region 3>`
47+
48+
To save turns, you can combine shell commands:
49+
50+
`adb shell input $(android screen resolve --screen screen.png --string "tap #34")`
51+
52+
This command taps on region #34 from `screen.png`
53+
54+
## Input
55+
Use `adb shell input` for interacting with Android devices.
56+
Refer to the `"interactions"` property of an element for what interactions can be performed on a particular element.
57+
58+
Interact with UI elements with their `center` coordinate or their `bounds` coordinates:
59+
```json
60+
{
61+
"key": -248568265,
62+
"class": "android.widget.Button",
63+
"bounds": "[138,9][167,38]",
64+
"center": "[152,23]"
65+
}
66+
```
67+
To tap on this button, you would execute `adb shell input tap 152 23`. This taps the center.
68+
69+
```json
70+
{
71+
"key": 12487234,
72+
"class": "com.example.ui.ScrollableList",
73+
"bounds": "[100,200][400,600]",
74+
"center": "[250,400]"
75+
}
76+
```
77+
To scroll down on this list, you would execute `adb shell input swipe 250 400 600 500`. This swipes from the center to the bottom over 500ms.
78+
79+
# Android Interaction Rules
80+
1. Always ensure text input fields have `"focused"` in their `"state"` list before entering text
81+
2. If an element has `"scrollable"` in its `"interactions"` list, try scrolling it when looking for missing UI elements
82+
2. Always scroll slowly when executing scroll inputs. The 5th argument to `adb shell input swipe` controls scroll duration.
83+
3. Content may take time to load; if a `layout` is missing information after you take an action, wait a few seconds, then perform `layout --diff` to see if anything changes.

0 commit comments

Comments
 (0)