docs(skills): add android-maps-sdk skill by dkhawk · Pull Request #2450 · googlemaps-samples/android-samples

dkhawk · 2026-10-08T18:35:43Z

Adds the android-maps-sdk developer skill in .gemini/skills/android-maps-sdk/ for pair programming on Google Maps Android apps.

It covers:

Setting up Google Maps with Compose and Views.
Writing headless JVM tests using Robolectric shadows (android-maps-robolectric).
Pre-flight API key checks via gcloud (verifying package name, debug SHA-1, and enabled APIs before building).
Integrating android-maps-utils for clustering, GeoJSON parsing, and distance calculations.
Practical patterns to avoid common pitfalls (such as using AssetManager instead of ClassLoader for assets, and avoiding duplicate marker rendering when clustering).
Reference guides and templates for camera controls, custom styling, Street View, and modular architecture.

… sample catalog

…sting, and modular architecture

…id-maps-sdk

…invariants

…trictions, robolectric looper, and modularity case study

…loud before building or deploying

…mmendation to android-maps-sdk

…rship, and gcloud apiTargets precondition

snippet-bot · 2026-10-08T19:46:00Z

No region tags are edited in this PR.

This comment is generated by snippet-bot.
If you find problems with this result, please file an issue at:
https://github.com/googleapis/repo-automation-bots/issues.
To update this comment, add snippet-bot:force-run label or use the checkbox below:

Refresh this comment

dkhawk · 2026-10-08T19:46:23Z

@kikoso @LoyalAbbas - Ready for review! Only one approval is needed.

…ce guides

kikoso

Can you take a look at the comments, @dkhawk ? Thanks! Most of them are about local paths and internal references that slipped into the skill.

kikoso · 2026-10-23T13:48:40Z

+
+This skill operates in synergy with official Google Maps Platform Android engineering skills:
+
+- [**`android-maps-compose`**](file:///usr/local/google/home/dkhawk/.gemini/config/skills/android-maps-compose/SKILL.md): Comprehensive guide for building declarative map experiences using Jetpack Compose (`com.google.maps.android:maps-compose`). Use whenever developers target Jetpack Compose or modern declarative UI.


The skill links point to file:///usr/local/google/home/dkhawk/..., so they will be broken for everybody else (same in the routing section below). Could we link to the skills in their repos instead, e.g. https://github.com/googlemaps/android-maps-compose/tree/main/.gemini/skills/android-maps-compose ? Some of them (artemis, android-autonomous-qa, android-monkey-testing) do not seem to be public, so we may want to drop those.

kikoso · 2026-10-23T13:48:41Z

+- **GCP Update Preconditions (`apiTargets` Preservation)**: When calling `gcloud services api-keys update`, all APIs with active traffic in the last 7 days (`maps-android-backend.googleapis.com`, `geocoding-backend.googleapis.com`, `places-backend.googleapis.com`, etc.) MUST be preserved and passed back as `--api-target=service=...` flags. Omitting them causes GCP to reject the update with `FAILED_PRECONDITION`.
+- **Automated Fix via `gcloud`**: If verification fails, the agent must offer to fix it automatically using the `gcloud` CLI (using safe update scripts that preserve existing allowed applications and active `apiTargets`).
+- **Fallback When `gcloud` Fails or is Missing**: If `gcloud` produces authentication errors (e.g., Context Aware Access block, expired credentials) or is missing:
+  1. Offer to fix it automatically once the user authenticates `gcloud` (`gcloud auth login` or `go/gcloud-caa-error`).


go/gcloud-caa-error is an internal link, so it will not work for external developers. Should we remove it here and in secrets_and_security.md?

kikoso · 2026-10-23T13:48:41Z

+
+### 2. Photorealistic 3D Map Experiences &rarr; Point to `android-maps3d-samples`
+If the user is interested in building a **3D map** (photorealistic 3D tiles, 3D meshes, 3D camera fly-tos, 3D polylines/polygons, or 3D model markers):
+* **Recommendation**: Point the user directly to the **Google Maps 3D SDK for Android** (`com.google.android.gms:play-services-maps3d:0.2.0+`).


Just to understand it: is 0.2.0+ intentional? The 3D samples are already on play-services-maps3d 16.0.0.

kikoso · 2026-10-23T13:48:41Z

+```kotlin
+dependencies {
+    // 1. Behavioral JVM Unit Tests (Robolectric Shadows & Truth Matchers)
+    testImplementation("com.google.android.maps.robolectric:shadows:1.1.0-rc01")


I may be missing something, but I cannot find com.google.android.maps.robolectric:shadows (nor the golden and visual artefacts) on Maven Central. If they are not published yet, an agent following this will end up with a build that does not resolve. Could we mark them as upcoming, or point to the repo setup instead?

kikoso · 2026-10-23T13:48:41Z

+
+---
+
+### Step 3: Base Dependency Setup & API Key Security


nit: this is the second Step 3, and the numbering does not match the diagram above (where dependencies are Step 4).

kikoso · 2026-10-23T13:48:41Z

+| `lite_demo` | Lite Mode Map | `GoogleMapOptions.liteMode(true)`, `MapView`, snapshot interaction | `LiteDemoActivity.java` | `LiteDemoActivity.kt` |
+| `lite_list_demo` | Lite Maps in List | `RecyclerView`, `MapView` recycled in ViewHolders, `setMapLocation()` | `LiteListDemoActivity.java` | `LiteListDemoActivity.kt` |
+| `location_source_demo` | Custom Location Source | `setLocationSource()`, `LocationSource.OnLocationChangedListener` | `LocationSourceDemoActivity.java` | `LocationSourceDemoActivity.kt` |
+| `marker_close_on_click` | Marker Click Behavior | `setOnMarkerClickListener()`, consuming click events, popup handling | `MarkerCloseOnClickDemoActivity.java` | `MarkerCloseOnClickDemoActivity.kt` |


nit: there is no MarkerCloseOnClickDemoActivity, I think this one is MarkerCloseInfoWindowOnRetapDemoActivity.

Suggested change

| `marker_close_on_click` | Marker Click Behavior | `setOnMarkerClickListener()`, consuming click events, popup handling | `MarkerCloseOnClickDemoActivity.java` | `MarkerCloseOnClickDemoActivity.kt` |

| `marker_close_on_click` | Marker Click Behavior | `setOnMarkerClickListener()`, consuming click events, popup handling | `MarkerCloseInfoWindowOnRetapDemoActivity.java` | `MarkerCloseInfoWindowOnRetapDemoActivity.kt` |

kikoso · 2026-10-23T13:48:41Z

+        )
+    ) {
+        Marker(
+            state = MarkerState(position = initialLocation),


nit: creating MarkerState directly in composition recreates it on every recomposition. Let's use rememberUpdatedMarkerState (and update the import):

Suggested change

state = MarkerState(position = initialLocation),

state = rememberUpdatedMarkerState(position = initialLocation),

kikoso · 2026-10-23T13:48:41Z

+    Capture["1. Capture Map Screenshot"] --> Diff["2. Fast Local Pixel Diff (< tolerance)"]
+    Diff -->|Passed| Pass["Test PASSED (Zero Network / Zero Quota)"]
+    Diff -->|Failed| AI["3. Gemini Flash Multimodal Semantic Evaluation"]
+    AI -->|Valid Semantic Change| Approve["Test PASSED (Auto-Update Golden Baseline)"]


I am thinking out loud if auto-updating the golden baseline when Gemini approves is a good idea. A regression the model misjudges would silently become the new baseline. Shouldn't we favour failing and asking for a manual update?

kikoso · 2026-10-23T13:48:42Z

+
+---
+
+## 5. Case Study: Boulder Creek Fountains (< 130 Lines Per File)


Being this a public skill, the Boulder Creek Fountains case study is not in this repo, so agents cannot look at it. Do we have a link to the source, or should we remove the section?

kikoso · 2026-10-23T13:48:42Z

+    override fun getSnippet(): String = snippet
+    override fun getZIndex(): Float? = null
+
+    // Ensure equals & hashCode are implemented for accurate item removal


nit: MyItem is a data class, so equals and hashCode are already generated. We can drop the manual overrides and keep the example shorter.

LoyalAbbas · 2026-10-28T08:43:12Z

Can we rename folder name .gemini to .agents so it's general-purpose and works nicely for any AI assistant or coding tool, not just Gemini?

dkhawk added 8 commits October 8, 2026 10:07

feat(skills): introduce android-maps-sdk skill grounded in production…

405d245

… sample catalog

feat(skills): augment android-maps-sdk with TDD, CUJs, robolectric te…

49ae134

…sting, and modular architecture

feat(skills): add golden image testing and AI visual testing to andro…

b92dbfb

…id-maps-sdk

feat(skills): add visual testing rigor and rendered map ground truth …

dcf8f24

…invariants

feat(skills): incorporate learnings on visual testing, pre-flight res…

3619bfe

…trictions, robolectric looper, and modularity case study

feat(skills): mandate pre-flight API key and restriction audit via gc…

7e391cb

…loud before building or deploying

docs: add android-maps-utils synergy, feature catalog, and skill reco…

93fe8c1

…mmendation to android-maps-sdk

docs: add tenets for asset loading discipline, clustering marker owne…

8bd8a6e

…rship, and gcloud apiTargets precondition

dkhawk changed the title ~~feat(skills): introduce android-maps-sdk skill with TDD, pre-flight audits, and utility synergy~~ docs(skills): add android-maps-sdk skill Oct 8, 2026

dkhawk added 2 commits October 8, 2026 12:50

docs: add routing to android-maps-compose and android-maps3d-sdk skills

a21efdf

chore: add license headers to template files in android-maps-sdk skill

902e2ae

dkhawk marked this pull request as ready for review October 8, 2026 19:45

dkhawk requested review from LoyalAbbas and kikoso October 8, 2026 19:46

docs: remove literal region tags from skill documentation and referen…

d7d339a

…ce guides

dkhawk marked this pull request as draft October 8, 2026 20:23

kikoso requested changes Oct 23, 2026

View reviewed changes


		This skill operates in synergy with official Google Maps Platform Android engineering skills:

		- [`android-maps-compose`](file:///usr/local/google/home/dkhawk/.gemini/config/skills/android-maps-compose/SKILL.md): Comprehensive guide for building declarative map experiences using Jetpack Compose (`com.google.maps.android:maps-compose`). Use whenever developers target Jetpack Compose or modern declarative UI.

	\| `marker_close_on_click` \| Marker Click Behavior \| `setOnMarkerClickListener()`, consuming click events, popup handling \| `MarkerCloseOnClickDemoActivity.java` \| `MarkerCloseOnClickDemoActivity.kt` \|
	\| `marker_close_on_click` \| Marker Click Behavior \| `setOnMarkerClickListener()`, consuming click events, popup handling \| `MarkerCloseInfoWindowOnRetapDemoActivity.java` \| `MarkerCloseInfoWindowOnRetapDemoActivity.kt` \|

	state = MarkerState(position = initialLocation),
	state = rememberUpdatedMarkerState(position = initialLocation),


		---

		## 5. Case Study: Boulder Creek Fountains (< 130 Lines Per File)

Conversation

dkhawk commented Oct 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

snippet-bot Bot commented Oct 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

No region tags are edited in this PR.

Uh oh!

dkhawk commented Oct 8, 2026

Uh oh!

kikoso left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LoyalAbbas commented Oct 28, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dkhawk commented Oct 8, 2026 •

edited

Loading

snippet-bot Bot commented Oct 8, 2026 •

edited

Loading