asc-new-app-release
Handle the first App Store release for a brand new app with the `asc` CLI: register a bundle ID, create the App Store Connect app, configure metadata/compliance/pricing, upload a build, and submit for review. Use this when the app does not exist yet in App Store Connect and the user asks for a first release, initial submission, or setup from zero. Do not use it for later releases of an existing app; use `asc-release-workflow` for that.
How do I install this agent skill?
npx skills add https://github.com/tddworks/asc-cli-skills --skill asc-new-app-releaseIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill facilitates the initial release of applications to the App Store using the `asc` CLI tool. It manages metadata, compliance, and build submissions through a series of shell commands. A minor risk of indirect prompt injection exists due to the ingestion of user-provided content for App Store metadata.
- Socketwarn
1 alert: gptAnomaly
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
First-Time App Store Release
This workflow takes a brand new app from zero to submitted on the App Store. It handles everything the regular release workflow (asc-release-workflow) doesn't — all the one-time setup that only happens for the very first submission.
Before You Start
Gather this info from the user (or derive from the project):
| Info | Where to find it | Example |
|---|---|---|
| Bundle ID | Xcode project or .xcconfig | com.mycompany.myapp |
| App name | What the user wants on the App Store | My Cool App |
| Platform | iOS, macOS, or both | ios |
| Category | See categories reference | EDUCATION |
| Description | User provides or you draft | Feature list paragraph |
| Support URL | GitHub repo, website, etc. | https://github.com/... |
| Pricing | Free or paid | Free |
| SKU | Unique string (generate if not provided) | myapp-ios-2026 |
Workflow Overview
Phase 1: Identity → Bundle ID + App creation
Phase 2: Metadata → Category, description, keywords, URLs
Phase 3: Compliance → Age rating, pricing, privacy labels, review contact
Phase 4: Build → Archive, upload, link to version
Phase 5: Readiness → Check all requirements, fix gaps
Phase 6: Submit → Submit for App Review
Phase 1: Identity
Step 1.1: Register Bundle ID
Check if the bundle ID already exists:
asc bundle-ids list
If not found, register it:
asc bundle-ids create \
--name "<APP_NAME>" \
--identifier "<BUNDLE_ID>" \
--platform IOS # or UNIVERSAL for iOS + macOS
Step 1.2: Create App on App Store Connect
Use the iris API (private API via web session) since it creates app + version + localizations in one call:
asc iris apps create \
--name "<APP_NAME>" \
--bundle-id "<BUNDLE_ID>" \
--sku "<SKU>"
Save the returned App ID — you'll need it for every subsequent command.
If the name is taken (409 error with DUPLICATE.DIFFERENT_ACCOUNT), ask the user for an alternative. Common fixes: add "App", "Studio", "AI", or a distinguishing word.
If iris isn't available (no web session), fall back to the REST API:
# This requires the bundle ID to already be registered
asc apps create \
--name "<APP_NAME>" \
--bundle-id-id "<BUNDLE_ID_RESOURCE_ID>" \
--sku "<SKU>" \
--primary-locale "en-US"
Step 1.3: Verify App and Get IDs
# Get app info ID (needed for categories, localizations)
asc app-infos list --app-id <APP_ID>
# Save: APP_INFO_ID
# Get version ID (needed for screenshots, build linking)
asc versions list --app-id <APP_ID>
# Save: VERSION_ID (the one in PREPARE_FOR_SUBMISSION state)
# Get version localization ID (needed for description, keywords)
asc version-localizations list --version-id <VERSION_ID>
# Save: LOCALIZATION_ID
Phase 2: Metadata
Step 2.1: Set Category
Ask the user what category fits best. See categories reference for the full list.
asc app-infos update \
--app-info-id <APP_INFO_ID> \
--primary-category <CATEGORY>
Common categories: EDUCATION, DEVELOPER_TOOLS, PRODUCTIVITY, UTILITIES, BUSINESS, ENTERTAINMENT, PHOTO_AND_VIDEO.
Step 2.2: Set Version Metadata
Write the description, keywords, and URLs:
asc version-localizations update \
--localization-id <LOCALIZATION_ID> \
--description "<DESCRIPTION>" \
--keywords "<COMMA_SEPARATED_KEYWORDS>" \
--support-url "<SUPPORT_URL>" \
--marketing-url "<MARKETING_URL>"
Description tips:
- First line is the hook — make it compelling
- List 5-7 key features with bullet points (use
•) - Keep under 4000 characters
- No pricing info, no competitor names
Keywords tips:
- Max 100 characters total, comma-separated
- Don't repeat the app name (it's already indexed)
- Use singular forms ("photo" not "photos")
- 8-12 keywords is a good target
Note: Don't set --whats-new for the first version — Apple doesn't allow it. That field is for updates only.
Step 2.3: Set App-Level Metadata (optional)
Subtitle and privacy policy URL are set on the app info localization (not the version):
# List app info localizations
asc app-info-localizations list --app-info-id <APP_INFO_ID>
# Save: APP_INFO_LOC_ID
# Update subtitle and privacy URL
asc app-info-localizations update \
--localization-id <APP_INFO_LOC_ID> \
--subtitle "<SHORT_SUBTITLE>" \
--privacy-policy-url "<PRIVACY_POLICY_URL>"
Phase 3: Compliance
Step 3.1: Age Rating
The default age rating (NONE = 4+) is usually correct for utility/productivity apps. Verify:
asc age-rating get --app-info-id <APP_INFO_ID>
If the app has mature content, update it:
asc age-rating update --declaration-id <APP_INFO_ID> \
--age-rating-override SEVENTEEN_PLUS
Step 3.2: Pricing, availability and content rights
A submission is refused until the app has a price, and a new app isn't sold anywhere until its availability is set up. Ask the user the price (Free is the usual choice when the app earns through in-app purchases or subscriptions) and where to sell it (usually everywhere).
# Price: pick a point in the base territory; Apple equalizes the rest. customerPrice 0.0 = Free.
FREE=$(asc apps price-points list --app-id <APP_ID> | jq -r '.data[] | select(.customerPrice == "0.0") | .id')
asc apps prices set --app-id <APP_ID> --base-territory USA --price-point-id "$FREE"
# Availability (App Store Connect's "Set Up Availability")
asc app-availability create --app-id <APP_ID> --all-territories --available-in-new-territories
# Content rights — a legal declaration, so ask the user which is true
asc apps update --app-id <APP_ID> --content-rights-declaration DOES_NOT_USE_THIRD_PARTY_CONTENT # or USES_THIRD_PARTY_CONTENT
Before release every territory reports CANNOT_SELL + AVAILABLE_FOR_SALE_UNRELEASED_APP; that's expected.
Step 3.3: Review Contact Info
asc version-review-detail update \
--version-id <VERSION_ID> \
--contact-email "<EMAIL>" \
--contact-phone "<PHONE>"
Ask the user for their contact email and phone number. This is required for App Review to reach them if there are questions.
Step 3.4: Privacy Nutrition Labels
App Privacy answers have no public App Store Connect API — they can only be published in the App Store Connect web page (or through a web session). Until they're published, the submission is refused with "You must have published answers to your app's data usages."
If the app collects no user data, tell the user: App Store Connect > App > App Privacy > Get Started > "No, we don't collect data from this app" > Publish.
If the app does collect data, walk through each data type. See the Apple privacy documentation for categories.
Phase 4: Build
Step 4.1: Archive and Upload
# Get the next build number
BUILD_NUMBER=$(asc builds next-number \
--app-id <APP_ID> \
--version <VERSION_STRING> \
--platform <PLATFORM>)
# Archive + upload in one step
asc builds archive \
--scheme <SCHEME> \
--platform <PLATFORM> \
--signing-style automatic \
--team-id <TEAM_ID> \
--upload \
--app-id <APP_ID> \
--version <VERSION_STRING> \
--build-number "$BUILD_NUMBER"
If the user already has an IPA/PKG:
asc builds upload \
--app-id <APP_ID> \
--file <PATH_TO_IPA> \
--version <VERSION_STRING> \
--build-number "$BUILD_NUMBER" \
--wait
Step 4.2: Wait for Processing
asc builds uploads get --upload-id <UPLOAD_ID>
Poll until state is COMPLETE. Common failures:
- Missing icon → Fix the asset catalog
- Missing entitlements → macOS needs App Sandbox
- CFBundleVersion mismatch → Build number in binary must match
Step 4.3: Link Build to Version
# Find the build (match by build number)
asc builds list --app-id <APP_ID>
# Link to the version
asc versions set-build \
--version-id <VERSION_ID> \
--build-id <BUILD_ID>
Phase 5: Readiness Check
asc versions check-readiness --version-id <VERSION_ID>
Review the output carefully. For a first-time app, common missing items:
| Check | Likely Status | How to Fix |
|---|---|---|
stateCheck | Pass | Should be PREPARE_FOR_SUBMISSION |
buildCheck | Fail if not uploaded yet | Upload and link a build (Phase 4) |
pricingCheck | Fail | asc apps prices set (Step 3.2) |
reviewContactCheck | Fail | asc version-review-detail update (Step 3.3) |
localizationCheck | Fail if screenshots missing | Upload screenshots |
screenshotSetCount: 0 | Fail | Need at least one screenshot set per device |
Screenshots
Screenshots are required for the first submission. If the user has a screenshot skill or automation:
# Create screenshot set for a device
asc screenshot-sets create \
--localization-id <LOCALIZATION_ID> \
--display-type APP_IPHONE_67
# Upload screenshot
asc screenshots create \
--screenshot-set-id <SET_ID> \
--file <PATH_TO_SCREENSHOT>
Required display types depend on the platform. At minimum for iOS:
APP_IPHONE_67(6.7" — iPhone Pro Max)APP_IPHONE_61(6.1" — iPhone Pro) — may be generated from 6.7"
For macOS: APP_DESKTOP
Phase 6: Submit
Once isReadyToSubmit is true:
A new app's in-app purchases and subscriptions are first-time products, so they must go to review with this version. Preview, confirm with the user, then submit:
asc versions submit --version-id <VERSION_ID> --with-products --dry-run --output table
asc versions submit --version-id <VERSION_ID> --with-products
Check the dry run lists every product the user expects — ones still MISSING_METADATA are left out. If Apple refuses, the error lists each reason (missing device screenshots, content rights, App Privacy answers, pricing); see submit-with-products.md.
Tell the user: "Your app has been submitted for review! Apple typically reviews within 24-48 hours. You'll receive an email when it's approved (or if there are issues to address)."
Quick Reference: Full Command Sequence
For a free iOS app with no data collection:
# 1. Register bundle ID
asc bundle-ids create --name "My App" --identifier "com.me.myapp" --platform IOS
# 2. Create app
asc iris apps create --name "My App" --bundle-id "com.me.myapp" --sku "myapp-2026"
# → APP_ID
# 3. Get IDs
asc app-infos list --app-id $APP_ID # → APP_INFO_ID
asc versions list --app-id $APP_ID # → VERSION_ID
asc version-localizations list --version-id $VERSION_ID # → LOC_ID
# 4. Category
asc app-infos update --app-info-id $APP_INFO_ID --primary-category EDUCATION
# 5. Description + keywords
asc version-localizations update --localization-id $LOC_ID \
--description "..." --keywords "..." --support-url "..." --marketing-url "..."
# 5b. Price (free), availability, content rights — App Privacy is published in the web UI
FREE=$(asc apps price-points list --app-id $APP_ID | jq -r '.data[] | select(.customerPrice == "0.0") | .id')
asc apps prices set --app-id $APP_ID --base-territory USA --price-point-id "$FREE"
asc app-availability create --app-id $APP_ID --all-territories --available-in-new-territories
asc apps update --app-id $APP_ID --content-rights-declaration DOES_NOT_USE_THIRD_PARTY_CONTENT
# 6. Review contact
asc version-review-detail update --version-id $VERSION_ID \
--contact-email "dev@me.com" --contact-phone "+1-555-0100"
# 7. Archive + upload
BUILD=$(asc builds next-number --app-id $APP_ID --version 1.0 --platform IOS)
asc builds archive --scheme MyApp --platform ios --signing-style automatic \
--team-id XXXXXXXXXX --upload --app-id $APP_ID --version 1.0 --build-number $BUILD
# 8. Link build
asc versions set-build --version-id $VERSION_ID --build-id $BUILD_ID
# 9. Check readiness
asc versions check-readiness --version-id $VERSION_ID
# 10. Submit, with any in-app purchases and subscriptions (first-time products)
asc versions submit --version-id $VERSION_ID --with-products --dry-run
asc versions submit --version-id $VERSION_ID --with-products
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/tddworks/asc-cli-skills/asc-new-app-release">View asc-new-app-release on skillZs</a>