skills

1---
2name: android-app-dev
3description: Use whenever the user asks to build, scaffold, edit, or debug a native Android app written in Kotlin or Java, using Jetpack Compose or the legacy View/XML system, Gradle, and Android Studio project conventions. Trigger on phrases like "make an android app", "build an app for android", "add a screen/activity/fragment", "fix my build.gradle", "add a Room database", or requests touching AndroidManifest.xml, build.gradle(.kts), libs.versions.toml, or files under app/src/main/java or app/src/main/kotlin. Always use when the user names a specific recent Android API level, Kotlin version, Compose version, or AGP version, since these change frequently and memorized defaults may be stale; verify current versions and patterns via web search before writing version-sensitive Gradle config. Requires every project to build exclusively through a GitHub Actions CI workflow rather than local Gradle, since local builds in this environment can't be reliably verified.
4---
5 
6# Android App Development
7 
8## Check for skill folder updates
9 
10Before applying this skill, check whether the skill folder has updates:
11 
121. Identify the directory where this skill is installed (such as `~/.copilot/skills/`, `~/.gemini/antigravity-cli/skills/`, `~/.claude/skills/`, or the active repository).
132. If the folder is inside a git repository, check git status:
14   ```bash
15   git -C <skill-folder> status --short --branch
16   ```
173. When network access is available, check for upstream changes:
18   ```bash
19   git -C <skill-folder> fetch --dry-run
20   ```
214. If updates are available, pull them before proceeding so you use the latest instructions. If the folder is not a git repository, proceed with the installed files.
22 
23## Scope
24 
25Native Android apps: Kotlin (default, preferred over Java for new code unless the user's
26project is already Java) with Gradle as the build system and Android Studio project
27conventions. Covers both modern Jetpack Compose UI and legacy View/XML-based UI, architecture
28(ViewModel, Room, Hilt/Koin, coroutines/Flow), and the Gradle/version-catalog layer. This is a
29different domain from the `minecraft-fabric-mod` skill (Java + Fabric/Loom for Minecraft): don't
30conflate Android's Gradle/Kotlin ecosystem with that one even though both use Gradle.
31 
32## Core principle: don't guess fast-moving version numbers or recently-changed conventions
33 
34Android tooling changes in ways that break naive pattern-matching from older training data:
35 
36- **AGP (Android Gradle Plugin), Kotlin, and Compose versions** all move independently and have
37  compatibility constraints between them.
38- **The Compose compiler setup changed**: since Kotlin 2.0, the Compose compiler ships as a
39  Kotlin-versioned Gradle plugin (`org.jetbrains.kotlin.plugin.compose`), configured via a
40  `composeCompiler { }` block: the older `composeOptions { kotlinCompilerExtensionVersion = "..." }`
41  pattern from pre-2.0 Kotlin is legacy. Don't write the old pattern for a new project without
42  checking which convention applies to the Kotlin version in use.
43- **Compose BOM version, minSdk/targetSdk/compileSdk defaults, and current Jetpack library
44  versions** (Room, Hilt, Navigation, Lifecycle, etc.) all get bumped regularly, and using a
45  memorized version can produce dependency-resolution failures or miss newer, non-deprecated APIs.
46- **Recommended architecture guidance itself has evolved** (e.g. Google's official architecture
47  guidance, recommended navigation approach, recommended DI approach): don't assume a pattern
48  learned from older tutorials is still what Google currently recommends without checking.
49 
50**Therefore: before writing or editing `build.gradle(.kts)`, `libs.versions.toml`, or
51`AndroidManifest.xml` for anything version-sensitive, search first rather than relying on
52memorized numbers.** This applies even if the agent feels confident.
53 
54## Core rule: when an error or bug appears, prefer documentation over guessing
55 
56Whenever the Gradle build fails, a compilation error appears, an API behaves unexpectedly, or a
57bug shows up in code (fresh or existing), **do not fix it from memory or by guessing** what is
58"probably" wrong. Android tooling (AGP, Kotlin, Compose, AndroidX libraries) changes APIs,
59deprecates patterns, and moves versions faster than training data can stay current: a
60confident-sounding guess is exactly what produces a second, silent failure.
61 
62When an error/bug appears:
631. **Get the exact error text**: the full compiler/AGP/stack trace message, not a paraphrase.
64   Ask the user for the precise error output if it is missing or ambiguous (e.g. from the CI log
65   or Android Studio build output).
662. **Search first**: run a web search or fetch official docs using the exact error string and
67   the library/AGP/Kotlin version involved. Prefer official sources:
68   `https://developer.android.com/develop`, AndroidX release notes at
69   `https://developer.android.com/jetpack/androidx/versions`, the AGP release notes at
70   `https://developer.android.com/build/releases/gradle-plugin`, and Kotlin docs at
71   `https://kotlinlang.org/docs/releases.html`. Also check the library's changelog/release notes
72   and any linked issue/Stack Overflow answers that quote the official docs.
733. **Apply a fix only after confirming the cause against documentation.** If you cannot find
74   authoritative docs or confirm the correct behavior, say so and mark the fix as unverified
75   rather than presenting a guess as a solution.
76 
77## Step 1: Research (do this for any new project or version-sensitive change)
78 
79Search for, in order of importance:
80 
811. **Current stable Kotlin version**: search `kotlin latest stable version`.
822. **Current stable AGP version and its Gradle compatibility**: search `android gradle plugin latest version` and check https://developer.android.com/build/releases/gradle-plugin for the AGP-to-Gradle-version compatibility table.
833. **Current Compose BOM version**: search `jetpack compose bom latest version` or check https://developer.android.com/develop/ui/compose/bom/bom-mapping: the BOM pins compatible versions of all `androidx.compose.*` artifacts together, so prefer using it over pinning individual Compose library versions by hand.
844. **Compose compiler setup for the Kotlin version in use**: check https://developer.android.com/develop/ui/compose/setup-compose-dependencies-and-compiler for the current recommended setup (Gradle plugin approach for Kotlin 2.0+, described above).
855. **Current recommended minSdk/targetSdk/compileSdk**: search `android compileSdk targetSdk latest`: Google Play has minimum targetSdk requirements that bump roughly yearly; check https://developer.android.com/google/play/requirements/target-sdk for the current requirement if the app is meant for Play Store distribution.
866. **Version of any specific Jetpack library the task touches** (Room, Hilt, Navigation Compose, Lifecycle, WorkManager, etc.): search `androidx <library> latest version` or check https://developer.android.com/jetpack/androidx/versions.
87 
88Useful authoritative sources to fetch/search directly:
89- `https://developer.android.com/develop`: main dev guide hub
90- `https://developer.android.com/jetpack/androidx/versions`: current versions of all AndroidX libraries
91- `https://developer.android.com/build/releases/gradle-plugin`: AGP release notes + Gradle compatibility
92- `https://developer.android.com/develop/ui/compose/bom/bom-mapping`: Compose BOM-to-library version mapping
93- `https://kotlinlang.org/docs/releases.html`: Kotlin release notes
94- `https://developer.android.com/topic/architecture`: Google's current official architecture guidance
95 
96If research tools are unavailable, tell the user explicitly which version numbers are unverified
97and should be double-checked in Android Studio before building.
98 
99## Step 2: Confirm findings before generating files
100 
101Briefly state the concrete versions found (Kotlin, AGP, Compose BOM, compileSdk/targetSdk/minSdk,
102and any specific library versions relevant to the task) before writing Gradle config. If numbers
103seem inconsistent (e.g. a Compose BOM newer than the Kotlin version could plausibly support),
104search again.
105 
106## Step 3: Project structure
107 
108Standard modern Android project layout (single-module, Compose-based: the common default unless
109the user's existing project says otherwise):
110 
111```
112app/
113├── build.gradle.kts
114├── src/main/
115│   ├── AndroidManifest.xml
116│   ├── kotlin/com/example/app/
117│   │   ├── MainActivity.kt
118│   │   ├── ui/
119│   │   │   ├── theme/          (Color.kt, Theme.kt, Type.kt)
120│   │   │   └── screens/        (one file/folder per screen + its ViewModel)
121│   │   ├── data/                (repositories, Room entities/DAOs, network sources)
122│   │   └── di/                  (Hilt/Koin modules, if used)
123│   └── res/
124│       ├── values/ (strings.xml, themes.xml)
125│       ├── drawable/
126│       └── mipmap-*/ (launcher icons)
127.github/
128└── workflows/
129    └── build.yml          (CI build: see Step 4, required, not optional)
130build.gradle.kts            (project-level)
131settings.gradle.kts
132gradle/libs.versions.toml   (version catalog: current standard convention)
133gradlew / gradlew.bat / gradle/wrapper/  (still committed: CI needs the wrapper even though we never run it locally)
134```
135 
136Use a Gradle **version catalog** (`gradle/libs.versions.toml`) for dependency versions rather
137than hardcoding version strings inline in each module's `build.gradle.kts`: this is the current
138standard convention and what Android Studio's own project templates generate.
139 
140Read `references/gradle-setup.md` for annotated `build.gradle.kts` / `libs.versions.toml`
141templates (placeholders to fill from Step 1's research, not to invent).
142 
143Read `references/architecture-guide.md` for the current recommended app architecture (UI layer /
144domain / data layer, ViewModel + StateFlow/UiState pattern, unidirectional data flow) and when
145Hilt vs. Koin vs. manual DI make sense.
146 
147Read `references/compose-patterns.md` for common Compose UI patterns: navigation
148(Navigation-Compose), state hoisting, common layout recipes, and Material 3 theming.
149 
150Read `references/common-pitfalls.md` before finishing: covers mistakes that most often break
151freshly generated or edited Android projects (missing permissions, Compose recomposition
152pitfalls, Room migration mistakes, ProGuard/R8 issues, wrong Compose compiler config, etc).
153 
154Read `references/github-actions-workflow.md` now as well (not just at Step 4) so the CI workflow
155file is scaffolded alongside the rest of the project in one pass, rather than as an afterthought.
156 
157## Step 4: Verify via GitHub Actions CI, never locally
158 
159**This project never runs `./gradlew` (build, assembleDebug, tasks, or any other Gradle command)
160locally, in the sandbox, or as a substitute for real verification.** All builds happen through a
161GitHub Actions workflow. This isn't only a fallback for when the Android SDK isn't available
162locally: it's the required build path for this skill, always, even in an environment where
163Gradle happens to be present.
164 
165Every scaffolded (or newly-versioned) app project must include a working CI workflow at
166`.github/workflows/build.yml`. Read `references/github-actions-workflow.md` for the annotated
167workflow template: it handles JDK setup, Android SDK/command-line-tools setup, Gradle caching,
168running a debug build (`assembleDebug`, which needs no signing secrets), running lint/unit tests,
169and uploading the built debug APK as a workflow artifact. That same file also covers the
170separate, opt-in release-signing workflow for when the user actually wants a signed release
171build: don't add release signing unless asked, since it requires the user to configure signing
172secrets in their repo.
173 
174After scaffolding/editing the project:
1751. Make sure `.github/workflows/build.yml` exists and is current (create it if missing, update it
176   if the Kotlin/AGP/JDK version requirements changed in Step 1/2).
1772. Commit and push the changes so the workflow actually runs:
178 
179```bash
180git add .
181git commit -m "Scaffold Android app with CI build workflow"
182git push
183```
184 
1853. Tell the user the push triggers the build automatically, and point them to the repo's Actions
186   tab to watch it and download the debug APK from the workflow run's artifacts once it succeeds.
187   If `git push` fails (no remote configured, no repo yet, auth issue), report the exact error: don't claim the app was verified if it was never actually pushed/built.
1884. If the GitHub CLI (`gh`) is available and authenticated, poll the workflow run's status
189   (`gh run list`, `gh run view <run-id> --log`, or `gh run watch <run-id>`) after pushing, to
190   catch and fix a failed build automatically rather than leaving it for the user to discover: iterate (fix, commit, push, recheck) until the workflow succeeds or you've exhausted
191   reasonable attempts, then report the final state honestly.
192 
193Never tell the user their app "builds fine" based on local/static inspection alone, and never
194attempt to install or invoke a local JDK, Android SDK, or Gradle installation in the sandbox to
195self-verify: the CI workflow is the single source of truth for whether the project actually
196compiles.
197 
198## When editing an existing app rather than starting fresh
199 
200Check the existing project's `libs.versions.toml`/`build.gradle.kts` for versions and conventions
201already in use (Compose vs. Views, Hilt vs. Koin vs. none, existing architecture pattern) and
202match them, rather than imposing different conventions: unless the user is explicitly asking to
203migrate or upgrade something, in which case do the full research step for the new target. Confirm
204`.github/workflows/build.yml` already exists in the project; if it's missing (e.g. an older
205project scaffolded before this workflow was standard), add it now. Still push changes and let CI
206verify: don't run Gradle locally for a small addition either.
207 
208## Reminder: no local Gradle, ever
209 
210Don't run `./gradlew`, install the Android SDK, or otherwise attempt to build/compile the app
211inside this sandbox or on the user's local machine as a substitute for CI. If the user asks "does
212it build?", the honest answer is "the CI workflow will tell us once it's pushed": check the
213Actions run, don't guess from local static inspection alone.
214 
215## Java vs. Kotlin
216 
217Default to Kotlin for any new code. If the user's existing project is Java-based, or they
218explicitly ask for Java, write idiomatic modern Java instead rather than pushing an
219unrequested migration: but mention that Kotlin is Google's recommended default for new Android
220development if it seems relevant.
221