Store Publish

store-publish — one JSON, both stores

Takes a mobile app (Flutter, native iOS/Android, React Native, Expo…) from "nothing in the consoles" to "build attached, ready to submit" on App Store Connect and Google Play, with the human touching only the few buttons that have no API. Everything runs through the two official REST APIs with curl, python3 and openssl — no fastlane, Ruby, PyJWT or Google SDKs.

$SKILL below = the folder containing this file (Claude Code ~/.claude/skills/store-publish, Codex ~/.agents/skills/store-publish or <repo>/.agents/skills/store-publish, invoked as $store-publish). Scripts are in $SKILL/scripts/:

Metadata schema: $SKILL/templates/store-metadata.example.json. API cheat sheets and every gotcha we hit shipping real apps: $SKILL/references/asc.md, $SKILL/references/play.md, $SKILL/references/locales.md.

Hard rules

1. Reply in the user's language. Store texts go in whatever locales the metadata lists.
2. Secrets never leave disk. Never print, paste or commit the .p8 key, the service-account JSON, bearer tokens or demo passwords. Key IDs / issuer IDs / service-account emails are identifiers, fine to show.
3. Confirm before the four outward-facing actions: uploading a build (build numbers / version codes are permanent), releasing to a Play track other than internal, submit (App Review), and promote --to production. Everything else is reversible metadata — do it without asking.
4. Read before write, re-run safe. Every step GETs the current state and PATCHes/POSTs accordingly. Prefer --dry-run on the first pass: iOS prints the writes, Android lets Google validate the edit and discards it.
5. Never stop on a failed step. Record the raw API error (it usually lists the allowed values), keep going, and finish with the ✅/❌ summary table the scripts print.
6. "Done" means verified. Finish with publish.py status (re-reads both stores) — never report success from write responses alone.
7. Ask with options, not open questions. In Claude Code use AskUserQuestion (multi-select when several apply, recommended option first). In runtimes without it (Codex CLI, others) print a numbered list, mark the recommended one, and wait. Don't ask what the project or the API can tell you.
8. Don't invent store copy silently. If the project has no listing text, draft it (benefit first, ≤ 30-char names, ≤ 80-char Play short description, ≤ 100-char keywords, no ♥ ★) and show the table before pushing.

Workflow

0. Credentials (once per machine)

• App Store Connect: ASC_KEY_ID / ASC_ISSUER_ID / ASC_KEY_PATH or ~/.appstoreconnect/config.json {"keyId","issuerId","keyPath"}. Needs an App Manager (or Admin) key: ASC → Users and Access → Integrations → App Store Connect API. Test: $SKILL/scripts/asc.sh GET /v1/apps → HTTP 200.
• Google Play: PLAY_SA_JSON or ~/.config/play/service-account.json. Create a service account in any Google Cloud project, then Play Console → Users and permissions → Invite new users with the service account email → grant the app with Release + Store presence permissions. The app itself must already exist in Play Console (no API creates it). Test: python3 $SKILL/scripts/play_publish.py check --package com.x.app.
• If either is missing, ask for it once (options: "I have the key → path", "Help me create one", "Skip this store") and offer to save it with chmod 600.

1. Metadata file

Create store-metadata.json in the project (copy the template). Fill it from what the project already has: existing listing docs, README, Info.plist / pubspec.yaml / build.gradle (name, ids, version), privacy policy and support URLs, screenshot folders (the store-screenshots skill produces store-size PNGs; put the Play feature graphic 1024×500 and icon 512×512 there too). Locale keys can be App Store style (ko, ja, zh-Hans) or Play style (ko-KR, ja-JP, zh-CN) — they are mapped both ways.

python3 $SKILL/scripts/publish.py validate --meta store-metadata.json

Fix everything it lists (lengths, symbols, wrong screenshot sizes, missing files) before touching the APIs.

2. First release — the human-only steps first

Give the user the exact values to type (from the metadata) and tell them which page. Then:

python3 $SKILL/scripts/publish.py listing --meta store-metadata.json --dry-run   # look, fix, then
python3 $SKILL/scripts/publish.py listing --meta store-metadata.json

iOS runs app-info → version → screenshots → age-rating → price-free → review-details. Android runs details → listings → images inside one edit and commits it.

3. Build and ship

Make sure the version in pubspec.yaml / Xcode / Gradle matches app.version, Info.plist has ITSAppUsesNonExemptEncryption=false, and the Android release signing is configured (android/key.properties or signingConfigs). Ask, then:

python3 $SKILL/scripts/publish.py build --meta store-metadata.json          # iOS archive + upload · Android AAB
python3 $SKILL/scripts/publish.py ship  --meta store-metadata.json --track internal

ship waits for Apple to process the build and attaches it to the editable version; on Android it uploads the AAB to the track with What's New from every locale and commits.

4. Updates (already-published app)

Bump app.version (and the build number / versionCode), write whatsNew in every locale, build, then:

python3 $SKILL/scripts/publish.py ship --meta store-metadata.json --release --build-number 18 --track internal

iOS creates the new version, copies the previous texts, sets What's New, uploads screenshots only if the version has none, copies review details, waits for the build and attaches it. --submit also files the review submission. Android uploads the AAB as before; submit --to production --rollout 0.2 promotes it.

5. Verify and hand over

python3 $SKILL/scripts/publish.py status --meta store-metadata.json

Report the table, then list what only the human can do:

1. App Store: App Privacy (first version) → publish.py submit --ios (or the Submit button).
2. Google Play: App content declarations and testers → production rollout (publish.py submit --android, or the button). New personal developer accounts (after Nov 2023) need a closed test with 12 testers for 14 days before production is unlocked.

When something is off