Skip to content
Back to search

ios-app-store-submit

Claude Code skill for automating iOS App Store submission.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zestfulpulse--ios-app-store-submit/badge.svg)](/listings/zestfulpulse--ios-app-store-submit)

HTML

<a href="/listings/zestfulpulse--ios-app-store-submit"><img src="/api/listings/zestfulpulse--ios-app-store-submit/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Clone the existing repository into the Claude Code skill directory:

mkdir -p ~/.agents/skills
git clone https://github.com/ZestfulPulse/ios-app-store-submit.git ~/.agents/skills/ios-app-store-submit
ln -s ../../.agents/skills/ios-app-store-submit ~/.claude/skills/ios-app-store-submit

This is the Claude Code skill for the complete workflow. Claude Code discovers skills under `~/.claude/skills/`, so the same skill can be used from any iOS or Flutter project.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 281 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: ios-app-store-submit
  3. description: Build, sign, and submit a Flutter/iOS app to the App Store Connect — covers Xcode archive/export, code signing (including headless-Mac keychain workarounds), the `asc` CLI for App Store Connect metadata automation, screenshot handoff, and final review submission. Use when asked to build and upload an iOS app, set up App Store code signing, fix a rejected/failed App Store Connect upload, automate App Store Connect metadata, or submit an app for App Store review. Triggers: "빌드해서 제출", "App Store 제출", "archive and upload", "TestFlight에 올려줘", "asc CLI로 메타데이터".
  4. ---
  5. # iOS App Store Build & Submit
  6. End-to-end playbook for taking a Flutter/iOS app from "code is done" to "submitted for App Store review," written for headless/agent-driven Mac environments (no interactive Xcode GUI session, no GUI keychain prompts available). Validated end-to-end on a real submission (2026-08-05) that hit — and worked around — every pitfall documented below.
  7. **This skill is project-agnostic.** Never hardcode bundle IDs, App Store Connect App IDs, Team IDs, or certificate names from a prior run — always derive them from the current project (see Step 0).
  8. ## When NOT to use this
  9. - Pure UI/feature work with no build/signing/submission component — just do the work directly.
  10. - If the user has an interactive Xcode session open and wants to do signing themselves — offer to guide them through Xcode's GUI instead of fighting headless keychain limitations for no reason.
  11. ## Step 0 — Discover the project
  12. Before anything else, gather facts from the current project (don't ask the user for things you can read yourself):
  13. ```bash
  14. # Bundle ID, team ID, current device family
  15. grep -n "PRODUCT_BUNDLE_IDENTIFIER\|DEVELOPMENT_TEAM\|TARGETED_DEVICE_FAMILY" ios/Runner.xcodeproj/project.pbxproj | sort -u
  16. # App version / build number
  17. grep "^version:" pubspec.yaml # Flutter: X.Y.Z+N
  18. # Is asc CLI already installed and authenticated?
  19. which asc && asc auth status
  20. # Is this app already registered in App Store Connect?
  21. asc apps list --output table
  22. ```
  23. If `asc` isn't installed or there's no cached auth, walk the user through generating an App Store Connect API key (they must do this themselves — only the account holder/Admin can):
  24. 1. https://appstoreconnect.apple.com/access/integrations/api → generate key → **App Manager** role (least privilege that still covers everything this skill needs) → download the `.p8` immediately (one-time download).
  25. 2. Get the file to you as a file (Drive link, etc.), never ask them to paste the raw key text in chat. Save it under `~/.asc/keys/` with `chmod 600`.
  26. 3. Register it:
  27. ```bash
  28. asc auth login --name "<project>" --key-id "<KEY_ID>" --issuer-id "<ISSUER_ID>" \
  29. --private-key "~/.asc/keys/AuthKey_<KEY_ID>.p8" --network --bypass-keychain
  30. ```
  31. **`--bypass-keychain` is required in headless sessions** — plain `asc auth login` fails with `-25308 User interaction is not allowed` because macOS Keychain wants a GUI unlock prompt that doesn't exist here.
  32. ## Step 1 — iOS Simulator does not work for ML/vision-heavy apps on Apple Silicon
  33. If the app uses `google_mlkit_*` (or similar plugins shipping arm64-simulator-incomplete binaries), **the app cannot even install on any iOS Simulator on an Apple Silicon Mac** ("Failed to find matching arch for input file"). Don't waste time debugging this — confirm real-device testing is the only option for that Mac, and check `flutter devices` for a wirelessly-paired iPhone/iPad before assuming none is available.
  34. For screenshots specifically: if simulators are unusable, **don't fabricate screens**. Ask the user to capture the real screens on their device, or use `xcrun devicectl` to install/launch things yourself if the device is paired (see Step 6).
  35. ## Step 2 — Code signing (the actual hard part)
  36. ### 2a. The core headless-Mac problem
  37. The **login keychain requires interactive unlock** in most agent/headless sessions. Any operation that touches it — `asc auth login` without `--bypass-keychain`, `security import` into `login.keychain`, or even `codesign` using an *existing* identity that's already in `login.keychain` — can fail with `-25308 User interaction is not allowed` or `errSecInternalComponent`. This is true even for identities that work fine when the same Mac is used interactively (e.g., via a prior Xcode session).
  38. **Fix: use a dedicated, non-interactive keychain for the whole session**, exactly like a CI runner would:
  39. ```bash
  40. KC_PASS="build-$(date +%s | tail -c 6)"
  41. security create-keychain -p "$KC_PASS" build.keychain
  42. security unlock-keychain -p "$KC_PASS" build.keychain
  43. security set-keychain-settings -lut 21600 build.keychain
  44. security list-keychains -d user -s build.keychain login.keychain
  45. ```
  46. Keep `$KC_PASS` around (write it to a gitignored file) — you'll need it again for `security set-key-partition-list`.
  47. ### 2b. Generate certificates without ever touching a keychain interactively
  48. `asc certificates create --generate-csr` creates the private key and CSR as **plain files** — no keychain interaction at all — then submits the CSR to Apple:
  49. ```bash
  50. asc certificates list --output table # check what already exists first
  51. asc certificates create --certificate-type IOS_DISTRIBUTION --generate-csr \
  52. --key-out ./signing/dist.key --csr-out ./signing/dist.csr \
  53. --common-name "<App> Distribution" --email "<contact-email>"
  54. # For a real-device dev/profile build later, also:
  55. # asc certificates create --certificate-type IOS_DEVELOPMENT --generate-csr ...
  56. ```
  57. Fetch/create the matching provisioning profile:
  58. ```bash
  59. asc signing fetch --bundle-id "<bundle.id>" --profile-type IOS_APP_STORE \
  60. --certificate-type IOS_DISTRIBUTION --create-missing --output ./signing
  61. # For device installs: --profile-type IOS_APP_DEVELOPMENT --device "<ASC device ID>"
  62. # (asc devices list to find/confirm the device is already registered)
  63. ```
  64. ### 2c. Import into build.keychain — OpenSSL 3.x needs `-legacy`
  65. ```bash
  66. openssl x509 -inform DER -in ./signing/<serial>.cer -out ./signing/dist.pem
  67. openssl pkcs12 -export -legacy -inkey ./signing/dist.key -in ./signing/dist.pem \
  68. -out ./signing/dist.p12 -passout pass:temp
  69. ```
  70. Without `-legacy`, OpenSSL 3.x's default PKCS12 encryption makes macOS `security import` fail with `"MAC verification failed during PKCS12 import (wrong password?)"` — **the password is fine, it's an algorithm-compatibility issue.**
  71. ```bash
  72. security import ./signing/dist.p12 -k build.keychain -P temp -T /usr/bin/codesign -T /usr/bin/security
  73. security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "$KC_PASS" build.keychain
  74. security find-identity -v -p codesigning build.keychain # confirm it shows up
  75. ```
  76. Install the provisioning profile at the standard location:
  77. ```bash
  78. UUID=$(security cms -D -i ./signing/<profile>.mobileprovision 2>/dev/null | plutil -extract UUID xml1 -o - - | sed -n 's/.*<string>\(.*\)<\/string>.*/\1/p')
  79. cp ./signing/<profile>.mobileprovision ~/Library/MobileDevice/Provisioning\ Profiles/"$UUID.mobileprovision"
  80. ```
  81. ### 2d. Scope manual signing to the app target ONLY — never pass signing flags globally
  82. If you pass `CODE_SIGN_STYLE=Manual` etc. as global `xcodebuild` command-line overrides, **every CocoaPods/SPM framework/library target in the build breaks** with errors like `"X does not support provisioning profiles, but provisioning profile Y has been manually specified."` — because those overrides apply to every target in the workspace, including libraries that must never be signed with a profile.
  83. Instead, edit `ios/Runner.xcodeproj/project.pbxproj` and add exactly these three keys **only inside the Runner (app) target's Release/Profile `XCBuildConfiguration` blocks** (there are usually two sets of Debug/Release/Profile blocks in this file — a project-level one and a target-level one; the target-level one is the one that also has `PRODUCT_BUNDLE_IDENTIFIER` in the same block):
  84. ```
  85. CODE_SIGN_STYLE = Manual;
  86. CODE_SIGN_IDENTITY = "<exact string from `security find-identity -v -p codesigning build.keychain`>";
  87. PROVISIONING_PROFILE_SPECIFIER = "<profile name>";
  88. ```
  89. **Before editing:** `project.pbxproj` indentation is tabs, and the depth is easy to miscount by eye. Verify exact whitespace first:
  90. ```bash
  91. python3 -c "
  92. with open('ios/Runner.xcodeproj/project.pbxproj') as f:
  93. lines = f.readlines()
  94. for i in range(START, END): print(repr(lines[i]))
  95. "
  96. ```
  97. then construct the Edit's `old_string` from that exact output — don't hand-type indentation.
  98. Also, use the **exact identity string** from `security find-identity`, not a generic prefix like `"iPhone Developer"` — if both a Development and Distribution identity (or an old login-keychain identity and a new build-keychain one) are visible in the combined search list, a generic prefix can non-deterministically match the wrong one, producing `"Provisioning profile X doesn't include signing certificate Y"`.
  99. Tell codesign which keychain to use for the archive step:
  100. ```bash
  101. asc xcode archive --workspace ios/Runner.xcworkspace --scheme Runner --configuration Release \
  102. --archive-path .asc/artifacts/Runner.xcarchive \
  103. --xcodebuild-flag="OTHER_CODE_SIGN_FLAGS=--keychain build.keychain"
  104. ```
  105. ## Step 3 — Archive → Export → Validate → Upload
  106. ```bash
  107. asc xcode export-options generate --archive-path .asc/artifacts/Runner.xcarchive \
  108. --signing-style manual --team-id "<TEAM_ID>" --output-path .asc/artifacts/ExportOptions.plist
  109. ```
  110. If this fails with `"manual export options require provisioning profile mappings"`, don't fight it — **write the plist by hand**, it's a small, well-known format:
  111. ```xml
  112. <?xml version="1.0" encoding="UTF-8"?>
  113. <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
  114. <plist version="1.0"><dict>
  115. <key>method</key><string>app-store-connect</string>
  116. <key>teamID</key><string>TEAM_ID</string>
  117. <key>signingStyle</key><string>manual</string>
  118. <key>provisioningProfiles</key><dict><key>BUNDLE_ID</key><string>PROFILE_NAME</string></dict>
  119. <key>signingCertificate</key><string>iPhone Distribution</string>
  120. <key>uploadSymbols</key><true/>
  121. </dict></plist>
  122. ```
  123. ```bash
  124. asc xcode export --archive-path .asc/artifacts/Runner.xcarchive \
  125. --ipa-path .asc/artifacts/Runner.ipa --export-options .asc/artifacts/ExportOptions.plist
  126. ```
  127. `asc xcode validate` wraps `altool`, which needs **its own separate credential file** (not the `asc auth` store):
  128. ```bash
  129. mkdir -p ~/.appstoreconnect/private_keys
  130. cp ~/.asc/keys/AuthKey_<KEY_ID>.p8 ~/.appstoreconnect/private_keys/
  131. asc xcode validate --ipa .asc/artifacts/Runner.ipa --api-key "<KEY_ID>" --api-issuer "<ISSUER_ID>"
  132. ```
  133. Upload and attach to a version:
  134. ```bash
  135. asc publish appstore --app "<APP_ID>" --ipa .asc/artifacts/Runner.ipa --version "<X.Y>" --wait
  136. ```
  137. If the upload fails, the CLI often only surfaces a bare error code. Get the real reason directly from the API:
  138. ```bash
  139. TOKEN=$(asc auth token --confirm 2>/dev/null)
  140. curl -s "https://api.appstoreconnect.apple.com/v1/buildUploads/<UPLOAD_ID>" \
  141. -H "Authorization: Bearer $TOKEN" | jq '.data.attributes.state'
  142. ```
  143. A common real failure: **missing a legacy `Info.plist` usage-description key alongside a newer granular one** — e.g., `NSCalendarsFullAccessUsageDescription` present but plain `NSCalendarsUsageDescription` missing (error 90683). Check every usage-description key the app declares has both the classic and any newer granular variant Apple currently expects.
  144. **Bump the build number for every re-upload.** After editing `pubspec.yaml`'s `+N`, run `flutter build ios --config-only --release` to regenerate `ios/Flutter/Generated.xcconfig` before re-archiving — a plain `flutter pub get` does not refresh it.
  145. ## Step 4 — Screenshots
  146. Delegate to the **`app-store-screenshots`** skill for the actual editor. Two things this skill adds on top of that:
  147. - **Don't trust a remembered screenshot size.** Whatever display-size guidance you have (6.9", 6.7", whatever) may be stale. If a real upload rejects a screenshot for wrong dimensions, that error is ground truth — fix the editor's export config to match it immediately, don't argue with it.
  148. - **Don't fabricate screens.** If the simulator can't run the app (Step 1) and a claimed feature has no real screen backing it (e.g., a headline promises something the UI doesn't actually show yet), stop and either add the missing UI for real or renegotiate the shot list with the user — never approximate.
  149. ## Step 5 — App Store Connect metadata (what `asc` can and can't do)
  150. **Can automate (public API):**
  151. | Field | Command |
  152. |---|---|
  153. | Name/subtitle/description/keywords/URLs | `asc metadata pull` → edit JSON → `asc metadata validate` → `asc metadata push` |
  154. | Primary category | `asc categories set --app <ID> --primary <CATEGORY>` |
  155. | Content rights | `asc apps update --id <ID> --content-rights DOES_NOT_USE_THIRD_PARTY_CONTENT` |
  156. | Build encryption declaration | `asc builds update --app <ID> --latest --uses-non-exempt-encryption=false` |
  157. | Age rating | `asc age-rating edit --app <ID> --all-none` (then override specific fields if the app actually has relevant content) |
  158. | Copyright | `asc versions update --version-id <ID> --copyright "YYYY Name"` |
  159. | Price (free) | `asc app-setup pricing set --app <ID> --free` |
  160. | Review contact/notes | `asc review details-create --version-id <ID> --contact-first-name ... --contact-phone ...` — **get the real name/phone from the user, never invent placeholder values here** |
  161. **Cannot automate — needs the user in a browser:**
  162. - **App Privacy (data-use declarations)** — not in the public API at all. `asc web privacy` needs an interactive Apple ID browser session; don't attempt it headlessly. Draft the recommended answers for the user, then have them fill it in **and explicitly click Publish** — saving without publishing still blocks submission with `"You must have published answers to your app's data usages"` at the final `review submit` step, and this failure mode isn't visible in `asc validate` beforehand (it only shows as a non-blocking "info" note there).
  163. **Territory/pricing availability has a real API quirk:** `asc pricing availability create --territory X` can fail with an error naming a completely unrelated territory code (changes on every retry) — this isn't user error, it's because App Store Connect's `POST /v2/appAvailabilities` requires the **entire territory catalog** (~175 entries) in the initial creation call, not just the ones you care about. Work around it directly:
  164. ```bash
  165. TOKEN=$(asc auth token --confirm 2>/dev/null)
  166. curl -s "https://api.appstoreconnect.apple.com/v1/territories?limit=200" -H "Authorization: Bearer $TOKEN" \
  167. | jq -r '.data[].id' > /tmp/all_territories.txt
  168. python3 - <<'EOF'
  169. import json
  170. territories = [l.strip() for l in open('/tmp/all_territories.txt') if l.strip()]
  171. WANT_AVAILABLE = {"KOR"} # <-- set desired territory codes here
  172. data, included = [], []
  173. for t in territories:
  174. lid = f"${{ta_{t}}}" # literal "${...}" local-id format, required by the API
  175. data.append({"type": "territoryAvailabilities", "id": lid})
  176. included.append({"type": "territoryAvailabilities", "id": lid,
  177. "attributes": {"available": t in WANT_AVAILABLE},
  178. "relationships": {"territory": {"data": {"type": "territories", "id": t}}}})
  179. body = {"data": {"type": "appAvailabilities",
  180. "attributes": {"availableInNewTerritories": False},
  181. "relationships": {"app": {"data": {"type": "apps", "id": "APP_ID"}},
  182. "territoryAvailabilities": {"data": data}}},
  183. "included": included}
  184. json.dump(body, open('/tmp/avail_body.json', 'w'))
  185. EOF
  186. curl -s -X POST "https://api.appstoreconnect.apple.com/v2/appAvailabilities" \
  187. -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d @/tmp/avail_body.json
  188. ```
  189. ## Step 6 — Submit
  190. ```bash
  191. asc validate --app "<APP_ID>" --version "<X.Y>" --platform IOS # iterate to 0 blocking errors
  192. asc review submit --app "<APP_ID>" --version "<X.Y>" --build "<BUILD_ID>" --confirm
  193. ```
  194. If that wrapper errors with `"does not contain target version"` despite the item genuinely being attached (`asc review items-list --submission <ID>` shows it `READY_FOR_REVIEW`), drop to the lower-level command — it's more reliable:
  195. ```bash
  196. asc review submissions-submit --id "<SUBMISSION_ID>" --confirm
  197. ```
  198. Confirm with `asc review status --app "<APP_ID>"` — look for `reviewState: WAITING_FOR_REVIEW` and `blockerCount: 0`.
  199. ## Step 7 (bonus) — Get a real, standalone-launchable build onto the user's device
  200. Users often expect their personal iPhone to run a normal (non-Xcode-tethered) build once you've done all this work. A plain **Debug** build always needs Xcode/the Dart VM attached to launch — that's expected, not a bug, and no amount of signing fixes it. The fix is running **Profile or Release** mode instead:
  201. ```bash
  202. flutter devices # confirm a wirelessly-paired device
  203. flutter build ios --profile # or --release; needs its own dev-signing setup per Step 2 if the
  204. # Release config is already pointed at an App Store profile
  205. # (App Store profiles cannot sideload to an arbitrary device)
  206. ```
  207. If `flutter build`/`flutter install` fails with the same keychain issues as Step 2, repeat the Step 2 signing setup with an `IOS_APP_DEVELOPMENT` certificate/profile instead of `IOS_DISTRIBUTION`, applied to the **Profile** (or Debug) target config block instead of Release.
  208. To install without `flutter install` (e.g., if you already have a `.app`/`.ipa`):
  209. ```bash
  210. xcrun devicectl device install app --device "<UDID>" "path/to/Runner.app"
  211. xcrun devicectl device process launch --device "<UDID>" "<bundle.id>"
  212. ```
  213. ## Icon/logo swaps
  214. When the user supplies a new app icon image:
  215. 1. **Actually look at it first** (Read tool) before resizing anything — a file that's the right pixel dimensions can still be a marketing mockup with placeholder text ("your name here") rather than an icon design. Confirm before applying.
  216. 2. Generate all required sizes from one source with Pillow (bundled: `scripts/gen_app_icons.py`).
  217. 3. Every binary change (icon included) needs a build-number bump and a fresh archive/export/upload — icons are baked into the binary, not metadata.
  218. ## Bundled scripts
  219. - `scripts/gen_app_icons.py` — regenerates iOS/macOS/Android launcher icons from one source PNG. Edit the paths at the top for the target project, or pass them as arguments if you extend it.
  220. - `scripts/setup_build_keychain.sh` — the Step 2a/2c keychain bootstrap as a single idempotent script (create-or-reuse keychain, unlock, add to search list). Import certificates separately per Step 2b/2c since those are certificate-specific.
README.md · README · 334 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # ios-app-store-submit
  2. [🇺🇸 English](README.md) | [🇰🇷 한국어](README.ko.md)
  3. ![Release](https://img.shields.io/github/v/release/ZestfulPulse/ios-app-store-submit)
  4. ![License](https://img.shields.io/github/license/ZestfulPulse/ios-app-store-submit)
  5. ![Stars](https://img.shields.io/github/stars/ZestfulPulse/ios-app-store-submit)
  6. ![Last Commit](https://img.shields.io/github/last-commit/ZestfulPulse/ios-app-store-submit)
  7. > **From automating App Store submission to deciding whether an iOS app is actually ready to submit, and helping recover when review fails.**
  8. `ios-app-store-submit` preserves the existing **Archive → Upload → Submit** workflow while adding evidence-driven Readiness, Apple Review Guidelines, Privacy, and HIG/Design checks before submission.
  9. This is the evolution of ios-app-store-submit, not a new repository. The public release target is **v2.0.0**.
  10. ## v2 Architecture
  11. ![ios-app-store-submit v2 architecture](assets/infographics/ios-app-store-submit-v2-architecture.svg)
  12. v2 preserves the original build, signing, upload, and submission workflow while adding evidence-driven intelligence before and after App Review.
  13. ## Current Status
  14. | Area | Status | Description |
  15. |---|---|---|
  16. | Readiness Core | ✅ | Technical / Metadata / Reviewability |
  17. | Safe Auto-Fix | ✅ | Plan → Apply → Verify → Rollback |
  18. | Apple Pre-Review | ✅ | App Review Guidelines preflight |
  19. | Privacy Intelligence | ✅ | Permissions, Privacy Manifest, SDK and network evidence |
  20. | HIG / Design Review | ✅ | Accessibility, Layout, Localization, Interaction |
  21. | Rejection Recovery | ✅ | Rejection → cause → fix plan → verification → reply draft |
  22. | Closed-loop Resubmission | ✅ | User-approved, evidence-bound resubmission orchestration |
  23. The v2.0.0 release combines all seven phases behind read-only inspection and explicit external-mutation gates.
  24. ## What Makes It Different?
  25. Traditional submission automation:
  26. ```text
  27. Archive → Validate → Upload → Submit
  28. ```
  29. The enhanced workflow:
  30. ```text
  31. App Project
  32. ↓
  33. Readiness
  34. ↓
  35. Apple Pre-Review
  36. ↓
  37. Privacy Intelligence
  38. ↓
  39. HIG / Design Review
  40. ↓
  41. Safe Fix → Verify
  42. ↓
  43. Archive → Upload → Submit
  44. ↓
  45. Apple Review
  46. ↓
  47. Rejection Recovery
  48. ↓
  49. Verify → User Approval → Resubmit → Verify
  50. ```
  51. The core idea is simple: **review the app before sending it to Apple.**
  52. ## Design Principles
  53. ### Evidence before confidence
  54. Missing evidence is not treated as success.
  55. ```text
  56. UNKNOWN ≠ PASS
  57. ```
  58. ### Safe fixes only
  59. Risky or semantic changes such as bundle identifiers, signing, certificates/provisioning, privacy semantics, user-authored content, UI semantics, navigation, and legal copy are not silently changed.
  60. ### Verify before claim
  61. Rejection recovery must not tell a reviewer that an issue is `Fixed` or `Resolved` without supporting verification evidence.
  62. ### No external mutation by inspection
  63. Inspection modes do not perform network calls, mutate App Store Connect, change signing state, or submit the app by default.
  64. ## Install
  65. Clone the existing repository into the Claude Code skill directory:
  66. ```bash
  67. mkdir -p ~/.agents/skills
  68. git clone https://github.com/ZestfulPulse/ios-app-store-submit.git ~/.agents/skills/ios-app-store-submit
  69. ln -s ../../.agents/skills/ios-app-store-submit ~/.claude/skills/ios-app-store-submit
  70. ```
  71. This is the Claude Code skill for the complete workflow. Claude Code discovers skills under `~/.claude/skills/`, so the same skill can be used from any iOS or Flutter project.
  72. ## Prerequisites
  73. - Apple Developer Program membership with appropriate App Store Connect access
  74. - Xcode and Flutter installed locally
  75. - The [`asc` CLI](https://github.com/rorkai/app-store-connect-cli-skills)
  76. - An App Store Connect API key stored locally under `~/.asc/keys/` with restrictive permissions; never place credentials in reports or commands
  77. Headless signing uses a dedicated build keychain and the bundled `scripts/setup_build_keychain.sh`. Archive/export/upload still follow the existing skill guidance; signing and provisioning changes are never inferred by readiness inspection.
  78. ## Use
  79. Ask Claude Code naturally, for example:
  80. > “Build and submit this app to App Store Connect.”
  81. > “Run the readiness and Apple pre-review checks.”
  82. > “Analyze this rejection and prepare a verified resubmission plan.”
  83. ## Quick Start
  84. Basic inspection:
  85. ```bash
  86. python3 scripts/readiness_check.py /path/to/your/app
  87. ```
  88. Recommended full pre-submission inspection:
  89. ```bash
  90. python3 scripts/readiness_check.py \
  91. /path/to/your/app \
  92. --pre-review \
  93. --privacy \
  94. --design
  95. ```
  96. Machine-readable JSON:
  97. ```bash
  98. python3 scripts/readiness_check.py \
  99. /path/to/your/app \
  100. --pre-review \
  101. --privacy \
  102. --design \
  103. --json
  104. ```
  105. ## Understanding Results
  106. | Status | Meaning |
  107. |---|---|
  108. | `PASS` | No issue found within the implemented inspection scope |
  109. | `RISK` | A risk signal deserves review |
  110. | `UNKNOWN` | Required evidence is missing |
  111. | `BLOCKED` | A deterministic pre-submission problem was found |
  112. A `PASS` is not a guarantee of App Store approval.
  113. ## Core Features
  114. ### Readiness Core
  115. Inspects technical readiness, metadata, and reviewability with evidence and provenance.
  116. ### Safe Auto-Fix
  117. ```text
  118. Finding → Fix Plan → Diff → Apply → Verify
  119. ↓
  120. Rollback on failure
  121. ```
  122. Includes stale-plan detection and before/after hash evidence.
  123. ### Apple Pre-Review
  124. Uses a normalized offline registry derived from Apple Review Guidelines. Current categories include Performance, Metadata, Privacy, and Review Access. Heuristics alone cannot block submission.
  125. ### Privacy Intelligence
  126. Inspects local evidence including:
  127. - `Info.plist` permissions
  128. - `PrivacyInfo.xcprivacy`
  129. - Required Reason API evidence
  130. - SDK / package dependencies
  131. - Network/backend signals
  132. - Privacy Policy evidence
  133. Access is deliberately separated from collection.
  134. ```text
  135. Location permission present
  136. → ACCESS = YES
  137. → COLLECTION = UNKNOWN
  138. → TRACKING = UNKNOWN
  139. ```
  140. ### HIG / Design Review
  141. Covers Accessibility, Layout, Localization, and Interaction. Questions requiring rendered UI evidence remain `UNKNOWN` instead of being falsely passed.
  142. ## Rejection Recovery
  143. Target flow:
  144. ```text
  145. Apple Rejection
  146. ↓
  147. Parse
  148. ↓
  149. Guideline / Privacy / HIG Mapping
  150. ↓
  151. Root Cause
  152. ↓
  153. Fix Plan
  154. ↓
  155. Verification
  156. ↓
  157. Reply Draft
  158. ```
  159. Intended usage:
  160. ```bash
  161. python3 scripts/readiness_check.py \
  162. /path/to/your/app \
  163. --rejection /path/to/rejection.txt
  164. ```
  165. Unverified changes are not allowed to become verified reviewer-facing claims.
  166. ## Closed-loop Resubmission
  167. Phase 7 completes the recovery loop:
  168. ```text
  169. Inspect → Pre-Review → Privacy → Design → Fix → Verify → Submit
  170. → Review → Recover → Verify → User Approval → Resubmit
  171. ```
  172. Build a read-only plan from a local Phase 6 recovery report:
  173. ```bash
  174. python3 scripts/readiness_check.py \
  175. /path/to/your/app \
  176. --resubmit-plan /path/to/recovery-report.json
  177. ```
  178. The plan prints exact discovered App Store Connect IDs, command previews, blockers, approval status, and a binding digest. It performs zero external mutation. Record approval separately, then execute only the exact approved digest:
  179. ```bash
  180. python3 scripts/readiness_check.py \
  181. /path/to/your/app \
  182. --resubmit-plan /path/to/recovery-report.json \
  183. --approve-resubmit \
  184. --approval-digest PLAN_DIGEST
  185. python3 scripts/readiness_check.py \
  186. /path/to/your/app \
  187. --resubmit-plan /path/to/recovery-report.json \
  188. --execute-resubmit \
  189. --approval-digest PLAN_DIGEST
  190. ```
  191. There is no auto-resubmit. A changed build, version, reply, fix evidence, or plan digest makes the approval stale. Execution requires all gates, `ready_to_send`, and read-only post-submit state verification such as `WAITING_FOR_REVIEW` or `IN_REVIEW`.
  192. ## Actual Submission
  193. The existing submission workflow remains intact:
  194. ```text
  195. asc xcode archive
  196. asc publish appstore
  197. asc review submit
  198. ```
  199. The intelligence layer adds safeguards around the submission engine rather than replacing it.
  200. ## Safety Boundaries
  201. Inspection does not automatically perform:
  202. - App Store Connect mutations
  203. - Apple review submission
  204. - GitHub mutations
  205. - Certificate / provisioning / signing changes
  206. - App Privacy answer publication
  207. - Risky UI or privacy semantic changes
  208. - Automatic resubmission; explicit user approval is always required
  209. ## Roadmap
  210. ```text
  211. Phase 1 Readiness Core ✅
  212. Phase 2 Safe Auto-Fix ✅
  213. Phase 3 Apple Pre-Review ✅
  214. Phase 4 Privacy Intelligence ✅
  215. Phase 5 HIG / Design Review ✅
  216. Phase 6 Rejection Recovery ✅
  217. Phase 7 Closed-loop Resubmission ✅
  218. ```
  219. Target closed loop:
  220. ```text
  221. Inspect → Fix → Verify → Submit
  222. ↓
  223. Apple Review
  224. ↙ ↘
  225. Approved Rejected
  226. ↓
  227. Recover
  228. ↓
  229. Verify
  230. ↓
  231. User Approval
  232. ↓
  233. Resubmit
  234. ```
  235. ## Project Philosophy
  236. The biggest risk in App Store automation is not insufficient automation. It is **automation pretending to know what it cannot prove**.
  237. - Decide when evidence supports a decision.
  238. - Keep insufficiently supported facts `UNKNOWN`.
  239. - Automate only bounded safe changes.
  240. - Never claim resolution before verification.
  241. - Maintain explicit approval boundaries around external mutations.
  242. ## Bundled Scripts
  243. - `scripts/readiness_check.py` — read-only readiness, pre-review, privacy, design, recovery, and resubmission planning gates.
  244. - `scripts/gen_app_icons.py` — regenerates launcher icon sizes from one source PNG.
  245. - `scripts/setup_build_keychain.sh` — creates/unlocks the dedicated headless signing keychain.
  246. ## License
  247. See the repository license file.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.