app-store-preflight-skills

App Store Preflight Skill

Run pre-submission checks on your iOS/macOS project to catch common App Store rejection patterns.

Prerequisites

• asc CLI — Install via Homebrew: brew install asc (App-Store-Connect-CLI)
• ASC CLI Skills — app-store-connect-cli-skills for asc usage patterns
• jq — Optional, but used by some JSON-inspection examples in the rule docs

Step 1: Identify App Type → Load Checklist

Determine which guidelines apply by loading the relevant checklist from references/guidelines/by-app-type/. Always start with all_apps.md, then add the app-type-specific one:

App Type	Checklist
Every app	references/guidelines/by-app-type/all_apps.md
Subscriptions / IAP	references/guidelines/by-app-type/subscription_iap.md
Social / UGC	references/guidelines/by-app-type/social_ugc.md
Kids Category	references/guidelines/by-app-type/kids.md
Health & Fitness	references/guidelines/by-app-type/health_fitness.md
Games	references/guidelines/by-app-type/games.md
macOS	references/guidelines/by-app-type/macos.md
AI / Generative AI	references/guidelines/by-app-type/ai_apps.md
Crypto & Finance	references/guidelines/by-app-type/crypto_finance.md
VPN	references/guidelines/by-app-type/vpn.md

Full guideline index: references/guidelines/README.md

Step 2: Pull Metadata for Inspection

Pull the latest App Store metadata using the asc CLI:

# Pull canonical metadata JSON for the version you want to review
asc metadata pull --app "<APP_ID>" --version "<VERSION>" --dir ./metadata

asc metadata pull writes app info files to ./metadata/app-info/*.json and version-localization files to ./metadata/version/<VERSION>/*.json.

Most rule examples below assume the canonical JSON layout written by asc metadata pull.

Creative assets (product page headers, search result assets; Guideline 2.3.14) live in App Store Connect's Asset Library. If your asc version doesn't pull them, review them by hand against 2.3.14.

If you already have metadata in another layout (for example fastlane metadata/), either adapt the file-path examples to that structure or pull the canonical asc layout first.

Step 3: Run Rejection Rule Checks

For each category, load the relevant rule files from references/rules/ and inspect. Each rule contains: What to Check, How to Detect, Resolution, and Example Rejection.

Category	Rule Files
Metadata	references/rules/metadata/*.md
Subscription	references/rules/subscription/*.md
Privacy	references/rules/privacy/*.md
Design	references/rules/design/*.md
Entitlements	references/rules/entitlements/*.md

Step 4: Report Findings

Produce a summary report using this template:

## Preflight Report

### ❌ Rejections Found (N)
- [GUIDELINE X.X.X] Description of issue
  - File: path/to/offending/file
  - Fix: What to do

### ⚠️ Warnings (N)
- [GUIDELINE X.X.X] Potential issue

### ✅ Passed (N)
- [Category] All checks passed

Order by severity: rejections first, then warnings, then passed.

Step 5: Autofix + Validate

Some issues can be auto-fixed:

• Competitor terms → Suggest replacement text with competitor names removed
• Metadata character limits → Show current vs. max length
• Missing links → Generate template ToS/PP URLs

After applying any auto-fix, re-run the affected checks to confirm the fix resolved the violation. Only mark as resolved once the re-scan passes.

For issues requiring manual intervention (screenshots, UI redesign), provide clear instructions but do not auto-fix.

Gotchas

• China storefront — Banned AI terms (ChatGPT, Gemini, etc.) are checked across ALL locales, not just zh-Hans. Apple checks every locale visible in the China storefront.
• Privacy manifests — PrivacyInfo.xcprivacy is required even if your app doesn't call Required Reason APIs directly. Third-party SDKs (Firebase, Amplitude, etc.) that use UserDefaults or NSFileManager trigger this requirement transitively.
• asc auth — asc metadata pull requires App Store Connect authentication. Run asc auth login first, or set ASC_KEY_ID, ASC_ISSUER_ID, and one of ASC_PRIVATE_KEY_PATH / ASC_PRIVATE_KEY / ASC_PRIVATE_KEY_B64. If you're unsure what asc is picking up, run asc auth doctor.
• Subscription metadata — Apple requires ToS/PP links in BOTH the App Store description AND the in-app subscription purchase screen. Missing either one is a separate rejection.
• Hidden features (2.5.19) — Feature flags are allowed, but every feature they can turn on must be in the reviewed build, reachable by the reviewer, and described in the review notes. Gating features on review-environment checks (sandbox receipt, TestFlight) is bait-and-switch and can get the developer account terminated.
• Third-party AI (5.1.2(i)) — Proxying AI calls through your own backend doesn't exempt you: if prompts or user content reach OpenAI, Gemini, Anthropic, etc., the app needs a consent screen naming the provider before the first request.
• Sign in with Apple relay domain — New relay addresses use private.icloud.com (from late 2026) in addition to privaterelay.appleid.com. Hard-coded domain checks break for new users.
• SDK minimum — Uploads must be built with the iOS 26 SDK or later (since April 28, 2026). An older Xcode fails at upload, not at review.
• macOS entitlements — Apple will ask you to justify every temporary exception entitlement (com.apple.security.temporary-exception.*). Remove entitlements you don't actively use.

Adding New Rules

Create a .md file in the appropriate references/rules/ subdirectory:

# Rule: [Short Title]
- **Guideline**: [Apple Guideline Number]
- **Severity**: REJECTION | WARNING
- **Category**: metadata | subscription | privacy | design | entitlements

## What to Check
## How to Detect
## Resolution
## Example Rejection