ASOScan Router

The entry point for the ASOScan skill pack. ASOScan gives you real ASO data: keyword volume and difficulty, your live rank, opportunities, competitor keywords and review sentiment, so you optimize from numbers instead of guessing. This skill (1) checks that ASOScan is reachable, through the connected ASOScan tools or an API key, then (2) routes to the right specialist.

Step 0 — General ASO question? No key needed.

If the request is conceptual / general best-practice and doesn't need the user's own data — "how does ASO work", "how do I write a good subtitle", "keyword strategy", "screenshot best practices", "teach me ASO" — route to aso-fundamentals (no API key).

If the user wants to get set up — "get my API key", "set up webhooks / Slack / Teams alerts", "connect my Play Console / App Store app" — route to asoscan-setup (also no key).

Step 1: Check how ASOScan is connected (for the data skills)

1. ASOScan tools are connected (the ASOScan plugin or connector in ChatGPT or Claude, or any MCP client): you are ready. Do not ask for an API key. get_usage (free) shows the API credits left.
2. No tools, but you can run shell commands: check ASOSCAN_API_KEY ([[ -n "$ASOSCAN_API_KEY" ]]). If it is set, optionally validate once with GET /usage (free). Never print the key.
3. Neither: route to asoscan-setup. Don't call the API without a connection or a key.

Step 2: Resolve the app (check this every time, not just once)

ASOScan only sees the apps in the user's own account. Call list_my_apps (free) and match the user's app by name and store; use its id in every later step. Almost every data skill needs this id, so do this check at the start of each new conversation, even if a prior session already set the user up.

If the user has no app yet, say so and guide them to finish setup before anything else — this is the single most common reason ASOScan tools fail, so treat it as the default next step whenever list_my_apps is empty, not a special case to wait for:

1. Ask for the app's App Store or Google Play link (or bundle/package id) and which country to track (never guess a country).
2. If the app is not published yet, it cannot be added directly: offer to track a similar, already-published competitor app instead, so the user still gets real keyword and ranking data for that market while building.
3. Call add_app (2 API credits, 1 app slot). The ASO score and recommendations are ready in about a minute; keyword opportunities a few minutes later.
4. Then offer add_competitor for 1 to 3 rivals. Ask for the competitor's store link specifically, not a bundle/package id, add_competitor cannot resolve a bare id the way add_app can, it needs the real App Store or Google Play page URL. The same setup ASOScan's own onboarding asks for. A user with an app but no competitors is still mid-setup, say so.
5. For keywords, call find_keyword_opportunities first and offer the ideas it returns, don't make the user invent terms from scratch, then track_keywords for the ones they pick (plus any others they name).
6. Call get_aso_recommendations and get_listing_metadata once an app is added, and point out a real gap if one stands out (a missing field, a thin subtitle), so the user gets a concrete win from the setup, not just a confirmation it worked.

If the user seems unsure how to do any of this through chat (for example they keep stalling on the country, or ask "can I just click something"), tell them they can also do the whole setup in the ASOScan dashboard at asoscan.com, no chat round trip required.

For an iOS app, mention once that connecting App Store Connect (see asoscan-setup) reveals the real hidden 100-character keyword field instead of just the public listing text, and is required before posting a review reply.

If the user names a rival that isn't tracked, it must be added as a competitor first (see competitor-analysis).

Step 3 — Route to the right skill

If the intent is ambiguous, ask one clarifying question, then route.

Calling the ASOScan API (shared conventions)

• With ASOScan tools connected, skip this section: use the tools; they need no key and their messages already explain errors.
• Base: https://asoscan.com/api/public/v1 · Auth: header Authorization: Bearer $ASOSCAN_API_KEY. JSON, camelCase fields.
• Safe call — capture the status so you can handle errors:

  BASE="https://asoscan.com/api/public/v1"; AUTH="Authorization: Bearer $ASOSCAN_API_KEY"
  resp="$(curl -s -w '\n%{http_code}' -H "$AUTH" "$BASE/apps")"
  code="$(printf '%s' "$resp" | tail -n1)"; body="$(printf '%s' "$resp" | sed '$d')"

  URL-encode multi-word query values: -G --data-urlencode "term=habit tracker".
• Errors: 401 missing/invalid key → asoscan-setup · 403 no API access → upgrade, or read-only key on a write → needs a write key · 402 out of credits (read X-ApiCredits-Remaining / -Reset) · 429 back off · 404 not owned/tracked · 503 API not enabled for this account yet.
• Credits: every single-app read (details, score, recommendations, listing text, keywords, competitors, rank/rating history, reviews) is free; failed calls are always free too. find_keyword_opportunities (2) and spy_competitor_keywords (2) cost credits; research_keyword is the expensive one (8, charged again on every repeat call even if the data came from a cache, so reuse a result instead of asking twice for the same term). Every write and AI tool costs credits (2, some also an AI credit). Watch X-ApiCredits-Remaining.
• Full reference + try-it console: https://asoscan.com/api/developers

Honesty

Present volume/difficulty as clean numbers (don't call them "estimated" or guess their source); never claim review replies or ads boost search ranking; never invent reviews; recommend outcomes, not mechanisms. If asked how to get more downloads or installs, answer with ASO levers (keywords, listing quality, ratings), not an install or revenue promise, ASOScan has no install/revenue data.