ASO - App Store Optimization Skill

Description

--- name: aso description: Complete App Store Optimization toolkit - generate metadata in any language, analyze competitors, optimize keywords, set up IAPs/subscriptions, and submit to App Store Connect via direct API user-invocable: true --- # 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) | Command | Purpose | Subcommands | |---------|---------|-------------| | `/aso` | Metadata generation & optimization | quick, audit, localize | | `/aso-connect` | App Store Connect integration | setup, status, sync | | `/aso-release` | Version & release management | create, attach, submit, notes, phased | | `/aso-assets` | Screenshots & IAPs | screenshots, iap | | `/aso-manage` | Reviews & legal documents | reviews, legal | | `/aso-build` | Xcode build & upload | build, archive, upload | --- ## 1. /aso - Metadata Generation & Optimization Generate optimized App Store metadata with competitor analysis and localization. ### Quick Mode (Default) ```bash /aso AppName # Generate metadata /aso "My App Name" # Copy-paste ready output ``` ### Audit Mode ```bash /aso AppName --audit # Full ASO audit /aso AppName --audit --competitors "Todoist,Any.do" ``` Output: `outputs/[app-name]/00-MASTER-ACTION-PLAN.md` ### Localize Mode ```bash /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 ```bash /aso-connect setup # Interactive setup wizard /aso-connect setup --verify # Verify credentials ``` ### Status ```bash /aso-connect status # Full status report /aso-connect status --brief # Quick summary ``` ### Sync ```bash /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 ```bash /aso-release create 1.0.0 # Create new version /aso-release create 2.0 --app MyApp ``` ### Attach Build ```bash /aso-release attach # Attach latest valid build /aso-release attach --build-id ID # Specific build ``` ### Submit for Review ```bash /aso-release submit # Submit for App Review /aso-release submit --expedite # Request expedited review ``` ### What's New ```bash /aso-release notes # Generate from git commits /aso-release notes --to tr,de # With translation ``` ### Phased Release ```bash /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 ```bash /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 ```bash /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 ```bash /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 ```bash /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. ```bash /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 ```bash # 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 ```bash claude mcp add --transport http revenuecat https://mcp.revenuecat.ai/mcp \ --header "Authorization: Bearer YOUR_V2_API_KEY" ``` ### Optional: Gemini MCP (Screenshots) ```bash claude mcp add gemini-mcp -s user -- npx -y @houtini/gemini-mcp export GEMINI_API_KEY="your_key" ``` --- ## CHARACTER LIMITS | Field | Apple | Google | |-------|-------|--------| | Title | 30 | 50 | | Subtitle | 30 | - | | Keywords | 100 | - | | Promo Text | 170 | 80 | | Description | 4000 | 4000 | ### 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 ```bash /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 ```bash /aso AppName # Generate optimized metadata /aso-connect sync # Push to ASC ``` ### Localization Workflow ```bash /aso --localize tr,de,ja # Translate .xcstrings /aso-connect sync --locale tr # Sync Turkish /aso-connect sync --locale de # Sync German ``` ### Version Update ```bash /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 | Operation | Method | Endpoint | |-----------|--------|----------| | List Apps | GET | `/apps` | | List Versions | GET | `/apps/{id}/appStoreVersions` | | Get Localizations | GET | `/appStoreVersions/{id}/appStoreVersionLocalizations` | | Update Localization | PATCH | `/appStoreVersionLocalizations/{id}` | | List Builds | GET | `/apps/{id}/builds` | | List IAPs | GET | `/apps/{id}/inAppPurchasesV2` | | Submit for Review | POST | `/appStoreVersionSubmissions` | ### Python Client ```python 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 ```bash # 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

Security Status