google-play-cli-skills

Agent skills for gplay — a fast, single-binary CLI for the Google Play Developer API. Each skill is a SKILL.md of plain-Markdown instructions that teaches an AI agent (Claude Code and friends) how to drive gplay at the prompt: how to think about the release lifecycle, which command shapes to reach for, and the gotchas the --help text alone won't warn you about.

These skills drive the gplay CLI; they do not replace it. Install gplay first — see the CLI repo.

Install

npx skills add PollyGlot/google-play-cli-skills

This pulls the skills below into your agent's skill directory. After installing, an agent can invoke a skill by name (e.g. gplay-release-flow) whenever the task matches its "Use when".

Catalogue

Start with gplay-cli-usage — it holds the cross-cutting conventions the other skills build on. The rest map one-to-one to a gplay surface.

Skill	Use when
gplay-cli-usage	Running or designing any gplay command — credential/account resolution, --package pinning, output formats, semantic exit codes, --dry-run/--confirm, the implicit Edit lifecycle. The foundation the other skills reference.
gplay-setup	Setting up gplay auth for the first time, switching or rotating service accounts, or diagnosing an auth failure (auth login / status / doctor / list / logout).
gplay-apps	Onboarding one or more packages into gplay's local registry, discovering which apps a credential can reach (apps accessible list), listing/viewing/removing registered apps, pinning one to the repo, or editing app details (default language, contact info).
gplay-release-flow	Uploading a build (AAB, or a legacy APK; large artifacts upload resumably), cutting a release, promoting a build up the track ladder (internal → alpha → beta → production), running or steering a staged production rollout (rollout / halt / resume / complete), inspecting which releases sit on a track, downloading the APKs Play generates, attaching ProGuard/R8 mappings for vitals symbolication, sharing a private Internal App Sharing build, or managing legacy OBB expansion files.
gplay-tracks	Inspecting tracks, creating a closed-testing track before an upload, auditing country availability (read-only), or setting the Google Groups authorized to test a closed track.
gplay-reviews	Triaging recent reviews, filtering by star rating, viewing one review's full user↔developer thread, replying to a user, or bulk-answering reviews from a TSV in CI (the API exposes the last 7 days), or reading the full review history from the monthly GCS CSV reports (one month or a --since/--until range) with reviews history.
gplay-metadata-sync	Editing store listings or screenshots, migrating listing text into version control, localizing a listing, or gating a listing change in CI before it goes live.
gplay-monetization	Putting subscriptions or one-time products under version control, editing a product's prices / offers / listings, reviewing catalog drift in CI, promoting a legacy inappproducts item to the v2 model, or migrating live subscribers to a new price. Declarative pull → edit → apply, but mirror semantics (a live product with no file is a delete) — not the additive stance of metadata.
gplay-compliance	Pushing or validating the Data Safety declaration from a versioned CSV (the only Play compliance surface with an API).
gplay-team	Inviting or off-boarding a Developer-account member, granting or adjusting per-app access, or looking up which permission alias / role bundle to use.
gplay-customapps	Creating a managed Google Play private (organisation-scoped) app from an AAB/APK — the one Play API path that creates an app record. Irreversible, so --confirm-gated and capability-gated.
gplay-vitals	Reading post-launch quality signals — crash / ANR / slow-start / rendering / wakeup / LMK rates, error reports and clustered issues, and Play-detected anomalies. Read-only, on the distinct Play Developer Reporting service (its own OAuth scope).
gplay-orders	Looking up a Google Play order by its order ID (single or batch) from a complaint or payout report, or issuing a refund. Refund moves money and is --confirm-gated; both need explicit financial capabilities never bundled into a role.
gplay-games	Configuring a game's Play Games Services achievements and leaderboards (list/view/create/set/remove), addressed by the numeric Play Games application ID (not the package). Draft-only — publishing to players stays Console-only.
gplay-recovery	Responding to a bad release: staging a draft app recovery, deploying it to force-update impacted users off the broken versionCode, widening its audience (append-only), or cancelling it. Deploy/cancel/add-targeting are --confirm-gated.
gplay-device-tiers	Creating or inspecting device tier configs for tiered content delivery (device groups, an ordered tier set, country sets). Immutable — create/get/list only, no update or delete — so a new config is a new id.
gplay-appstore	Operating a third-party Android app store: mirroring Play's catalog export (one app, or the incremental update-event feed), and taking a hosted app through Google's review path — create the record, apk/image/policy upload its artifacts, submit it to review (irrevocable, --confirm-gated), publish-status set to withdraw or restore it.
gplay-signing	Enrolling an app into Play App Signing with a self-hosted Cloud KMS key, or rotating to a new KMS key (apksigner lineage + reason). Only for organisations that must keep key custody external; Google-managed Play App Signing has no API and stays Console-only. Irreversible, --confirm-gated.

Also covered by the foundation skill: gplay schema — the offline, no-auth Android Publisher API introspection command ([experimental]). It has no dedicated skill yet; gplay-cli-usage documents it next to --help.

Roadmap

The set above tracks the current gplay surface, GA since v1.0.0. Commands the CLI marks [experimental] sit outside that contract — gplay-cli-usage says what that means for CI. Skills for gated surfaces land as those CLI surfaces ship.

Subscriptions & IAP — the last open roadmap item, gated on #51 — shipped in gplay v0.18.0 and is now covered by gplay-monetization. RevenueCat reconciliation is not part of it: gplay wraps the Play side only.

See the CLI's docs/BACKLOG.md for the full roster and gating.

Repo layout

One folder per skill, each holding a SKILL.md:

skills/
  gplay-release-flow/
    SKILL.md

Every SKILL.md opens with YAML frontmatter carrying two required fields:

---
name: gplay-release-flow
description: <what it does> … Use when <the trigger phrasing>.
---

• name — kebab-case, matches the skill's folder name.
• description — one line, ends with a "Use when …" clause so an agent can decide relevance. This is the same text shown in the catalogue above.

A missing or malformed name/description breaks npx skills add, so keep both fields present and well-formed when adding a skill.

Checking a change

python3 scripts/check-skills.py            # needs gplay on PATH
python3 scripts/check-skills.py --offline  # frontmatter, links and style only

The script resolves every gplay invocation in the skills against the installed binary's real command tree and flag set, so a flag that no longer exists, an invented subcommand, or a frontmatter typo fails loudly instead of shipping. CI runs it on every pull request and weekly, since the drift usually comes from a gplay release rather than from a commit here.

License

MIT © 2026 Pavlo Trinko