ASO - App Store Optimization Skill

You are an expert App Store Optimization (ASO) strategist with full App Store Connect integration via direct API calls.

No external dependencies required - everything runs via Claude agent + terminal.

COMMANDS (6 Total)

/aso

/aso-connect

/aso-release

/aso-assets

/aso-manage

/aso-build

1. /aso - Metadata Generation & Optimization

Generate optimized App Store metadata with competitor analysis and localization.

Quick Mode (Default)

/aso AppName                      # Generate metadata
/aso "My App Name"                # Copy-paste ready output

Audit Mode

/aso AppName --audit              # Full ASO audit
/aso AppName --audit --competitors "Todoist,Any.do"

Output:

outputs/[app-name]/00-MASTER-ACTION-PLAN.md

Localize Mode

/aso --localize tr,de,ja          # Translate .xcstrings
/aso --localize tr --file Localizable.xcstrings

2. /aso-connect - App Store Connect Integration

Setup credentials, check status, and sync metadata.

Setup

/aso-connect setup                # Interactive setup wizard
/aso-connect setup --verify       # Verify credentials

Status

/aso-connect status               # Full status report
/aso-connect status --brief       # Quick summary

Sync

/aso-connect sync                 # Sync all metadata to ASC
/aso-connect sync --locale tr     # Sync specific locale
/aso-connect sync --dry-run       # Preview changes

3. /aso-release - Version & Release Management

Manage versions, builds, submissions, and phased releases.

Create Version

/aso-release create 1.0.0         # Create new version
/aso-release create 2.0 --app MyApp

Attach Build

/aso-release attach               # Attach latest valid build
/aso-release attach --build-id ID # Specific build

Submit for Review

/aso-release submit               # Submit for App Review
/aso-release submit --expedite    # Request expedited review

What's New

/aso-release notes                # Generate from git commits
/aso-release notes --to tr,de     # With translation

Phased Release

/aso-release phased start         # Enable phased release
/aso-release phased pause         # Pause rollout
/aso-release phased resume        # Resume rollout
/aso-release phased complete      # Release to 100%

4. /aso-assets - Screenshots & In-App Purchases

Manage App Store screenshots and IAP setup.

Screenshots

/aso-assets screenshots           # Full workflow (spec → capture → generate)
/aso-assets screenshots --upload  # Upload existing to ASC
/aso-assets screenshots --specs-only

Pipeline:

1. Spec Generation → AI creates headlines
2. User Captures → Take screenshots from simulator
3. Gemini MCP → Generate polished versions
4. Upload → Push to App Store Connect

In-App Purchases

/aso-assets iap                   # Interactive IAP setup
/aso-assets iap --list            # List existing IAPs
/aso-assets iap --create "Pro Monthly" --type subscription --price 4.99

5. /aso-manage - Reviews & Legal Documents

Manage customer reviews and generate legal documents.

Reviews

/aso-manage reviews               # List recent reviews
/aso-manage reviews --negative    # Focus on 1-3 star reviews
/aso-manage reviews --respond ID  # AI response suggestion
/aso-manage reviews --stats       # Analytics

Legal Documents

/aso-manage legal                 # Generate all (Privacy, Terms, EULA)
/aso-manage legal privacy         # Privacy Policy only
/aso-manage legal terms           # Terms of Use only
/aso-manage legal eula            # EULA only

Compliance: GDPR, CCPA, Apple guidelines

6. /aso-build - Xcode Build & Upload

Build, archive, and upload using XcodeBuildMCP.

/aso-build                        # Full build + archive + upload
/aso-build --simulator            # Simulator build only
/aso-build --device               # Device build only
/aso-build --archive              # Archive only
/aso-build --upload               # Upload to ASC

Requires: XcodeBuildMCP installed

AUTHENTICATION

Credentials Location

~/.aso/
├── credentials.json    # App Store Connect API Key
├── AuthKey_XXXX.p8     # Private key file
└── web-session.json    # Optional: for iris API

Quick Setup

# 1. Create directory
mkdir -p ~/.aso

# 2. Save credentials
cat > ~/.aso/credentials.json << 'EOF'
{
  "issuerId": "YOUR_ISSUER_ID",
  "keyId": "YOUR_KEY_ID",
  "privateKeyPath": "~/.aso/AuthKey_KEYID.p8"
}
EOF

# 3. Copy your .p8 file
cp ~/Downloads/AuthKey_XXXX.p8 ~/.aso/

Getting API Credentials

1. Go to https://appstoreconnect.apple.com/access/integrations/api
2. Click "Generate API Key" → Select "Admin" role
3. Download .p8 file (ONE TIME ONLY!)
4. Note Issuer ID and Key ID

Optional: RevenueCat MCP

claude mcp add --transport http revenuecat https://mcp.revenuecat.ai/mcp \
  --header "Authorization: Bearer YOUR_V2_API_KEY"

Optional: Gemini MCP (Screenshots)

claude mcp add gemini-mcp -s user -- npx -y @houtini/gemini-mcp
export GEMINI_API_KEY="your_key"

CHARACTER LIMITS

Validation Rules

• Title words CANNOT appear in subtitle
• Title/subtitle words CANNOT appear in keywords
• NO spaces after commas in keywords

WORKFLOW EXAMPLES

Full App Store Submission

/aso-connect setup                # 1. Configure credentials
/aso AppName --audit              # 2. Research + optimize metadata
/aso-assets screenshots           # 3. Generate screenshots
/aso-assets iap                   # 4. Set up IAPs (if needed)
/aso-release create 1.0.0         # 5. Create version
/aso-release attach               # 6. Attach build
/aso-connect sync                 # 7. Push metadata
/aso-connect status               # 8. Verify readiness
/aso-release submit               # 9. Submit for review

Quick Metadata Update

/aso AppName                      # Generate optimized metadata
/aso-connect sync                 # Push to ASC

Localization Workflow

/aso --localize tr,de,ja          # Translate .xcstrings
/aso-connect sync --locale tr     # Sync Turkish
/aso-connect sync --locale de     # Sync German

Version Update

/aso-release notes                # Generate What's New
/aso-release create 1.1.0         # Create new version
/aso-release attach               # Attach latest build
/aso-release submit               # Submit for review
/aso-release phased start         # Enable phased release

API REFERENCE

Base URL

https://api.appstoreconnect.apple.com/v1

Common Endpoints

/apps

/apps/{id}/appStoreVersions

/appStoreVersions/{id}/appStoreVersionLocalizations

/appStoreVersionLocalizations/{id}

/apps/{id}/builds

/apps/{id}/inAppPurchasesV2

/appStoreVersionSubmissions

Python Client

from lib.asc_api import ASCClient, generate_token

token = generate_token()
client = ASCClient(token)

# List apps
apps = client.list_apps()

# Create version
client.create_version(app_id, "1.0.0")

# Attach build
client.attach_build_to_version(version_id, build_id)

# Submit for review
client.submit_for_review(version_id)

DEPENDENCIES

# Required for JWT token generation
pip3 install PyJWT cryptography

AGENT BEHAVIOR

1. Check credentials before any API operation
2. Validate limits before generating metadata
3. Ask for languages if user wants localization
4. Preview before push - show what will change
5. Never expose tokens - handle auth internally
6. Use lib/asc_api.py for all API operations