Guide · Agent skill
How to use the Google Mobile Ads Android migration agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
This guide explains how to install and use the google-mobile-ads-android-migrate-to-next-gen skill, a set of instructions that lets an AI agent carry out a step-by-step migration of an Android app from the legacy Google Mobile Ads (GMA) SDK to the GMA Next-Gen SDK. It is written for readers who have not used agent skills before. By the end you will know what the skill changes, how to install it, how to ask for it in plain language, and what to check before you trust the result.
Google Mobile Ads Android Migrationgoogle/skills · Apache-2.0 Download the skill Quick start
- 1Check your project. Confirm the app uses Gradle and the legacy com.google.android.gms:play-services-ads library, and that you can raise minSdk to 24 and compileSdk to 34.
- 2Download and unzip the skill. Download the skill ZIP from this page and unzip it to ~/.claude/skills/ for personal use or to the project's .claude/skills/ folder for one project.
- 3Or upload it in the Claude apps. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP.
- 4Ask for the migration. Give the agent a plain request such as migrating the app from play-services-ads to the GMA Next-Gen SDK, and point it at your project folder.
- 5Review the Gradle changes. Check the dependency swap, the minSdk and compileSdk updates and the exclusions before letting the agent continue.
- 6Build and test. Let the agent run gradle build -x test, then test every ad format and callback on real devices before release.
What does this skill make the agent do?
The skill is a single instruction file, SKILL.md, that tells the agent how to migrate an Android codebase from the old play-services-ads library (com.google.android.gms:play-services-ads) to the new ads-mobile-sdk library (com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk). Instead of working from memory, the agent follows a checklist written in the file and uses the mapping tables it contains to decide what to rename.
The checklist covers three phases: configure Gradle, migrate each file, and verify with a build. In the Gradle phase the agent swaps the dependency, raises minSdk to 24 or higher and compileSdk to 34 or higher, and excludes the old play-services-ads and play-services-ads-lite libraries from all dependencies to avoid duplicate symbol errors. In the per-file phase it rewrites imports, class names and method signatures using the API Mapping and Method Mapping tables. In the final phase it runs gradle build -x test and fixes any GMA-related compile errors.
- Updates Gradle dependencies and minimum SDK versions
- Rewrites imports, class names and method signatures using the mapping tables
- Reminds the agent to keep initialization order and UI-thread rules correct
- Runs a clean build to surface remaining compile errors
How do you install the skill?
Download the skill ZIP from this page and unzip it. You can install it for yourself or for one project. For all of your projects, place the unzipped folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.
If you use the Claude apps instead of a local folder, open Settings, go to Capabilities, then Skills, and upload the ZIP there.
- Personal install: ~/.claude/skills/
- Project install: the .claude/skills/ folder inside your Android project
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
How do you trigger the skill with a natural request?
You do not need a special command. The skill describes itself as useful when migrating an existing Android codebase from the old, legacy GMA SDK to GMA Next-Gen SDK, so ask for that outcome in plain words and name the SDKs if you can. Point the agent at your project folder so it can read and edit the files.
Good requests name the starting point and the goal. Mention the old library if you know it, and say whether you want the agent to make the edits or only list what needs to change.
- Migrate this Android app from play-services-ads to the GMA Next-Gen SDK.
- Upgrade our AdMob Android SDK to ads-mobile-sdk and fix the compile errors.
- Check which files in this project still import com.google.android.gms.ads and tell me what maps to what in Next-Gen.
- Update the Gradle setup for GMA Next-Gen and set minSdk and compileSdk to the required levels.
What does the agent need before it starts?
The skill assumes an Android project that uses the Gradle build system, and a Java or Kotlin toolchain that can run gradle build. The agent needs network access to Maven or dl.google.com so it can find the latest SDK version. If Maven is not reachable directly, the skill tells the agent to fall back on curl and the command below, which reads the latest version from the Google metadata file.
Your project must also be able to meet the skill's targets. The skill requires minSdk 24 or higher and compileSdk 34 or higher, so a project that cannot raise those levels is not a good fit.
- Android project built with Gradle
- Java or Kotlin toolchain that can run gradle build
- Network access to Maven or dl.google.com
- Ability to raise minSdk to 24 and compileSdk to 34
curl -sS https://dl.google.com/dl/android/maven2/com/google/android/libraries/ads/mobile/sdk/ads-mobile-sdk/maven-metadata.xml | sed -n 's/.*<latest>\(.*\)<\/latest>.*/\1/p'What safety rules and risks should you know about?
The skill runs scripts and uses the network. The documented script is the curl command above, which fetches version metadata from dl.google.com. Read the command before the agent runs it, and check that the agent is not running anything you did not expect.
The skill's rules include a mandatory UI-thread requirement. The file says that callbacks in the GMA Next-Gen SDK are invoked on a background thread, so UI operations such as Toasts, View updates and Fragment transactions must be wrapped in runOnUiThread {} or Dispatchers.Main.launch {} inside SDK callbacks. The file warns that skipping this will crash the app. It also says to keep MobileAds.initialize() on a background thread and to call it before any other SDK method.
- Review the curl command before the agent runs it
- Check that initialize() runs before other SDK methods and on a background thread
- Keep the com.google.android.gms.ads.APPLICATION_ID meta-data tag in AndroidManifest.xml
- Do not let the agent remove Mediation Adapter classes that still need com.google.android.gms.ads
How do you check the result?
The skill is a guide for the agent, not a guarantee. The agent may miss edge cases, so ads behaviour and crash-free operation still need testing on real devices. Treat the clean build as the first check, not the last.
After the build passes, run the app and exercise every screen that shows an ad, including banners, interstitials, native ads and reward flows. Check that ad callbacks update the UI correctly and that the app starts without crashes.
- Read the diff file by file, especially imports and callbacks
- Confirm the clean build succeeds
- Test ad screens and callbacks on devices
- Check that the Mute This Ad logic has been removed from native ad code, since the skill says it is unsupported in GMA Next-Gen
Tips for better results
Work on a branch or a copy of the project so you can compare changes. Migrate in a planned way: run the Gradle phase first, sync, then move file by file. The skill itself says to sync Gradle before moving on to the next step.
The mapping tables are the agent's reference. If you hit a class that is not in the tables, ask the agent to say so rather than guess. The skill notes that ad preloading methods keep the same API signatures and parameters as the old SDK unless the mapping table says otherwise.
- Use version control so you can review and revert changes
- Sync Gradle after the dependency change before editing code
- Ask the agent to flag anything not covered by the mapping tables
- Keep the APPLICATION_ID meta-data tag, since the User Messaging Platform SDK still needs it
What people use it for
- Moving a production Android app off the legacy play-services-ads library in one planned upgrade
- Renaming imports and class names across many files with the mapping tables as a reference
- Getting a consistent checklist for a team that is doing the same SDK upgrade
- Finding remaining legacy com.google.android.gms.ads references that still need a decision
Frequently asked questions
How do I install the google mobile ads android migration skill?
Download the skill ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. If you use the Claude apps, you can instead upload the ZIP under Settings, Capabilities, Skills.
What does the skill require?
It needs an Android project that uses Gradle, a Java or Kotlin toolchain that can run gradle build, and network access to Maven or dl.google.com. The project must also be able to use minSdk 24 and compileSdk 34.
Is the skill free to use?
The skill is published under the Apache-2.0 licence. This page does not state any price, so check the licence text in the source repository for the terms.
Does it work for iOS or web projects?
No. The mappings are Android-specific, so the skill is not suited to iOS or web projects, or to apps that do not use Google Mobile Ads.
Why does the build fail after migration?
The skill's final step runs gradle build -x test and asks the agent to resolve GMA-related compile errors. If errors remain, check the mapping tables for renamed imports and callbacks, and confirm that the old play-services-ads libraries are excluded in the app-level build file.
Does the skill replace testing?
No. The skill is a guide that the agent follows and may miss edge cases. Ads behaviour and crash-free operation still need testing on devices.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits Android developers who have a Gradle project on the legacy play-services-ads library, can raise minSdk to 24 and compileSdk to 34, and want an agent to do the repetitive renaming with a checklist. It is a poor fit for iOS, web or non-ads projects, and for teams that cannot raise their SDK levels. Plan to test every ad format on devices after the build passes.
Download the skill