aso

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 (8 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 (incl. --sentiment), legal
/aso-build	Xcode build & upload	build, archive, upload
/aso-rank	Keyword ranking tracker	check, history, report, drops
/aso-pages	Custom Product Pages & In-App Events	cpp, event

---

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: Apple Search Ads (real keyword volume)

# Search Ads UI → Account Settings → API → create API user, then:
cat > ~/.aso/searchads.json << 'EOF'
{
  "clientId": "SEARCHADS.xxxx",
  "teamId": "SEARCHADS.xxxx",
  "keyId": "YOUR_KEY_ID",
  "privateKeyPath": "~/.aso/searchads-private-key.pem",
  "orgId": 123456
}
EOF

When configured, keyword volume estimates use real impression data from your campaigns (lib/searchads_api.py) instead of heuristics. Keywords without campaign data fall back to the heuristic estimator.

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

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

/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

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

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