How to use the Play Billing Library Upgrade agent skill

What does the Play Billing Library Upgrade skill make the agent do?

The skill gives an agent a fixed procedure for migrating an Android project from a legacy Google Play Billing Library version to the latest stable version. The agent first tells you what it is about to do, then finds the billing dependency (for example com.android.billingclient:billing) in build.gradle, build.gradle.kts or libs.versions.toml.

If the first build fails, the agent scans the source for deprecated APIs to estimate the real starting version. It then decides between a direct migration and a stepped migration, moving two major versions at a time when the project is more than two versions behind. For each jump it reads the official migration guide and the Deprecations and Breaking Changes sections of the release notes, and it turns them into a checklist.

The agent then edits code and build files, runs ./gradlew assembleDebug, ./gradlew test and a clean build, and checks the project against a version-specific checklist so deprecated APIs are not missed.

Install the skill from the ZIP download

Download the ZIP of the skill from this page and unzip it. The skill folder contains SKILL.md, references/migration-logic.md and references/version-checklist.md.

You have two options. For a personal setup, place the unzipped folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder so it applies only to that codebase.

If you use the Claude apps instead, you can upload the skill under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Project only: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills

How do you trigger the skill with a natural request?

You do not need a special command. Describe the task in plain language that mentions Play Billing or the billing library and a move to a newer version. The skill's description covers upgrading or migrating an Android project from any legacy PBL version to the latest stable PBL.

Include the project location and anything that matters, such as the current version if you know it, or a note that the app has several old in-app purchase or subscription flows.

• "Upgrade the Play Billing Library in this Android project to the latest stable version."
• "Migrate our billing code from PBL v4 to the newest release, in stages if needed."
• "Our app is several Play Billing versions behind. Plan and carry out the upgrade, then run the tests."

What does a run look like?

Expect the agent to announce its intent, then report the detected effective version and the target, and state whether it plans a direct or stepped migration. During execution it explains each step before running it and summarises the result afterwards.

At the end the agent produces a final report explaining why changes were made, for example an SDK update required by a newer PBL, or removal of custom retry code that the library now handles. It may also suggest newer features that your app does not use yet.

• Reads the dependency and attempts a build
• Plans a direct or stepped path and prints a checklist
• Edits Gradle files and code, then runs ./gradlew assembleDebug, ./gradlew test and ./gradlew clean assembleDebug
• Runs ./gradlew sync and ./gradlew build so you can test the app manually

What does the skill need before you start?

The project must use Gradle, with a build.gradle or build.gradle.kts file. You need Android Studio or a Gradle toolchain that can run ./gradlew commands. The agent also needs internet access so it can consult Google's migration guides and release notes.

Use version control before you start. The agent edits code across the project, and changes can be hard to review or revert without a clean commit to return to.

• Android project using Gradle
• Android Studio or a Gradle toolchain able to run ./gradlew
• Internet access for the agent to read Google's guides and release notes
• Version control and existing unit tests

What are the safety notes for scripts and network access?

This skill runs scripts and uses the network. The network access is needed so the agent can read the official migration guides and release notes. Review what the agent runs, since it executes Gradle commands in your project.

The skill relies on builds and unit tests as its checks. It does not verify purchase or payment behaviour on a real device, so you must test purchases yourself before release.

• Runs scripts: yes, including Gradle builds and tests
• Uses network: yes, to consult Google's documentation
• Review the diff and keep the change under version control

Tips for a smoother upgrade

Give the agent a clean working tree and a passing test suite before starting, so any new failure is easy to attribute. Read the checklist the agent prints and ask about items that do not apply to your app.

For a large jump, let the stepped migration run in full rather than skipping intermediate builds. Each intermediate build is there to catch breaking changes that would otherwise be missed.

• Commit or stash your work first
• Run tests before and after the upgrade
• Review every change in the diff
• Test purchase flows manually on a device