ASOScan App Store Optimization

View saved version →

---
name: aso-fundamentals
description: When the user wants general App Store Optimization guidance, best practices, or to understand how ASO works, with no live data or API key required. Also use when the user mentions "how does ASO work", "app store best practices", "how does keyword indexing work", "how do I write a good title or subtitle", "keyword strategy", "screenshot strategy", "how to get more reviews", "ASO checklist", "why isn't my app ranking" (conceptually), or "teach me ASO". This is the ONE skill in the pack that works without an ASOScan API key. For your app's REAL numbers (rank, volume, difficulty, score, opportunities), use the data skills (keyword-intelligence, keyword-opportunities, competitor-analysis, metadata-audit).
metadata:
  version: 1.3.6
---

# ASO Fundamentals — expert guidance, no data required

Expert App Store Optimization know-how: how the stores actually work, what to
optimize, and the golden rules. **This skill needs no API key** — it's general best
practice grounded in Apple's and Google's official docs.

Best practice only takes you so far without data. **ASOScan** turns each principle
into your real numbers (rank, volume, difficulty, score, opportunities). When the
ASOScan tools are connected in ChatGPT or Claude, the data skills use them directly;
otherwise get set up with **asoscan-setup**, then use the data skills.

> Store rules change. The facts here follow Apple's and Google's current official
> developer documentation (sources at the bottom). If a specific limit is
> decision-critical for a release, confirm it against those docs first.

---

## 1. How store search actually works (the mental model)

**Apple App Store** ranks results on two things:

- **Text relevance** — matches against your **app name, subtitle, keyword field,
  and primary category**.
- **User behavior** — downloads, **ratings and reviews**, and more.

Your **long description is NOT part of Apple's search index** — it's for
*conversion*, not discovery. Put your keyword effort into the name, subtitle, and
keyword field.

**Google Play** works differently: there is **no hidden keyword field**. Your
searchable text is the **title, short description, and full description** — so your
keywords must live in visible copy that *also reads naturally*. Google explicitly
warns against keyword stuffing.

> **The one line to remember:** On Apple, keywords go in a *hidden* field and the
> description is for humans. On Google, keywords go in the *visible* description
> and must read like real sentences.

---

## 2. The metadata fields + limits

| Field | Apple | Google | In search index? |
|---|---|---|---|
| Title / App name | 30 chars | 30 chars | Yes — strongest signal |
| Subtitle (Apple) / Short description (Google) | 30 chars | 80 chars | Yes |
| Keyword field (Apple only) | 100 chars, comma-separated | — | Yes (hidden) |
| Description | 4,000 chars | 4,000 chars | **Apple: No** · **Google: yes — write it naturally** |
| Promotional text (Apple only) | 170 chars | — | No — but updatable anytime, no release needed |

---

## 3. Keyword strategy

### Apple — the hidden 100-character keyword field (golden rules)

Apple's own guidance:

- **Separate terms with commas, no space between terms.** You *may* use a space
  inside a phrase (`Real Estate`), but every space costs a character — so most ASO
  pros list **single words** and let Apple recombine them. Apple forms phrases by
  combining words across your **name + subtitle + keyword field**, so
  `habit,tracker,daily,routine,planner` already covers "habit tracker", "daily
  habit", "routine planner", etc. — without spending characters on the phrases.
- **Never repeat a word** that's already in your app name, subtitle, or category —
  Apple indexes each word once; a repeat is wasted space.
- **Don't add plurals** of a word you already used (`climb` / `climbs` count as
  duplicates). Apple handles the variation.
- **Skip generic, overly broad terms** (`app`, `game`) and **filler

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: asoscan-router
description: The ASOScan ASO skill and companion. Start here for almost any App Store Optimization (ASO) task powered by ASOScan, not only an exact phrase match, including adding or tracking an app, keyword volume or difficulty, app rank or rank tracking, keyword opportunities (including brand/community keyword matches), competitor analysis, review sentiment, review replies, listing text for another language, a metadata/listing audit, or ASO recommendations for an app. Also use when the user mentions "ASO", "app store optimization", "keyword volume", "keyword difficulty", "my app's rank", "keywords my competitor ranks for", "audit my app listing", "what should I improve", or "how do I get more downloads/installs". It checks that the ASOScan tools are connected or an API key is set, then checks the user has finished setup (an app, its tracking country, and at least one competitor), and routes to the right ASOScan skill.
metadata:
  version: 1.3.6
---

# 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_opportuni

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: asoscan-setup
description: When the user wants to set up ASOScan, for example to connect the ASOScan plugin or connector in ChatGPT or Claude, get an API access key for a coding agent, set up webhooks (including Slack or Microsoft Teams alerts), or connect Google Play Console or App Store Connect. Also use when the user mentions "connect ASOScan", "connect my ASOScan account", "get my API key", "set up webhooks", "send alerts to Slack", "connect my Play Console", "connect my App Store account", or "how do I hook this up". Works with no account and no key.
metadata:
  version: 1.3.6
---

# ASOScan Setup & Connect

Guides the user through configuring ASOScan: getting an **API key**, setting up
**webhooks** (incl. Slack / Teams), and **connecting** their Play Console / App
Store Connect accounts. **No API key needed to run this skill** — it's how they get
set up.

> ⚑ **Third-party UIs change — verify live, don't recite from memory.** For any
> step that happens **outside** ASOScan (Slack, Microsoft Teams / Power Automate,
> Google Play Console / Google Cloud, App Store Connect), **look up the current
> official instructions with web search before walking the user through them**, and
> prefer ASOScan's own up-to-date tutorials/docs where linked below. The
> **ASOScan-side** steps in this skill are current; the **external** steps you must
> confirm live each time.
>
> **Gating note:** webhooks and connections may not appear in every account —
> they're rolling out and depend on the plan/feature flags. If the user doesn't see
> a section, tell them the feature may not be enabled for their account yet.

---

## 0. Connect your ASOScan account (ChatGPT, Claude, Claude Code)

First check: can you call the ASOScan tools (for example `get_usage`)?

- **Yes**: the account is connected. Call `get_usage` (free) and tell the user how many API credits are left. Skip the API key section; it is only for coding agents without the tools.
- **No, and you are in ChatGPT or Claude**: tell the user to connect their ASOScan account. In ChatGPT, add the ASOScan plugin from the plugin directory. In Claude, add the ASOScan connector or plugin from the directory. Then sign in to ASOScan (or create an account; new accounts start with a free trial) and allow access. Allowing changes lets ASOScan add apps, keywords and competitors, save drafts, and post review replies the user approves.
- **No, and you are in Claude Code**: `claude plugin marketplace add ASOScan/aso-skills`, then `claude plugin install asoscan@asoscan`, then sign in when Claude Code asks. Or use an API key (section 1).
- **No, and you are in another coding agent**: use an API key (section 1).

To disconnect an assistant later: ASOScan **Settings → Connected AI apps → Disconnect**.

---

## 1. Get your ASOScan API key

Copy this checklist and tick each step:

```
API key setup
- [ ] 1. Create an ASOScan account + add at least one app
- [ ] 2. Settings → API access → New key name → Read-only / Read+write → Create key
- [ ] 3. Copy the key now (asosk_live_… is shown once)
- [ ] 4. export ASOSCAN_API_KEY="asosk_live_…"
- [ ] 5. Verify → expect 200 + your usage
```

**Details:**
1. Sign up at **asoscan.com** and add an app. The API is **owner-scoped** — it works
   on the apps in your account, so you need at least one.
2. **Settings → API access** → type a **New key name** → choose **Read-only** or
   **Read + write** (write lets the skills add keywords & competitors) → **Create
   key**. **Copy it now — `asosk_live_…` is shown only once.**
3. Set it as an environment variable:
   ```bash
   export ASOSCAN_API_KEY="asosk_live_…"     # bash/zsh (add to ~/.zshrc to persist)
   ```
   ```fish
   set -Ux ASOSCAN_API_KEY "asosk_live_…"     # fish
   ```
   ```powershell
   setx ASOSCAN_API_KEY "asosk_live_…"        # Windows PowerShell — open a new terminal after
   ```
4. Verify — a `200` with your usage means you're set:
   ```bash
   curl -s "https://asoscan.com/api/public/v1/usage" -H "

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: competitor-analysis
description: When the user wants to compare an app against its tracked competitors using ASOScan (keyword overlap and gaps, which store category each competitor uses, category chart rank over time, and rating trajectory), or add a new rival by store URL. Also use when the user mentions "compare my app to competitors", "who am I competing with", "add this competitor", "how do I stack up", "am I gaining or losing vs them", "what category do my competitors use", or "category ranking". For a competitor's full keyword list, see keyword-spy.
metadata:
  version: 1.3.6
---

# Competitor Analysis

Position the app against the rivals ASOScan tracks — where it's ahead, where it's
behind, and the single biggest lever — using real rank, rating, and keyword data.

## When to use

- "Compare my app to my competitors."
- "Add `<store URL>` as a competitor."
- "What category do my competitors use / how's my category rank vs theirs?"

## Getting the data (two modes)

Pick the first mode that applies, then follow the steps below.

1. **ASOScan tools are connected** (the ASOScan plugin or connector in ChatGPT or Claude, or any MCP client): use the tool named in the table. Do not ask for an API key and do not run `curl`. Tool results have the same fields as the API responses below, and a list comes back inside `items`. If a tool answers with a message instead of data (reconnect, credits used up, plan limit, "preparing"), pass that message on and stop.
2. **No tools, but you can run shell commands and `ASOSCAN_API_KEY` is set**: make the API call in the table. Base `https://asoscan.com/api/public/v1`, header `Authorization: Bearer $ASOSCAN_API_KEY`, JSON with camelCase fields. Never print the key. Capture the HTTP status and handle errors as described at the bottom.
3. **Neither**: hand off to **asoscan-setup**. It explains how to connect ASOScan in ChatGPT or Claude, or how to create an API key.

ASOScan only sees the apps in the user's own account and the competitors they track. Every call uses API credits (failed calls are free). Before a call that costs more than 2 API credits, or one that uses AI, tell the user the cost and wait for a yes. Before any call that changes data, ask first.

| Step | Tool (connected) | API call (key) | API credits |
|---|---|---|---|
| Find the app | `list_my_apps` | `GET /apps` | free |
| One app's facts (category, rating) | `get_app_details` | `GET /apps/{id}` | free |
| Competitors | `get_competitors` | `GET /apps/{id}/competitors?country=` | free |
| Add a rival by store link (changes data) | `add_competitor` | `POST /apps/{id}/competitors` with `{ "storeUrl": "..." }` | 2, ask first |
| Category rank over time | `get_category_rank` | `GET /apps/{id}/category-rank?country=&days=30` | free |
| Rating history | `get_rating_history` | `GET /apps/{id}/rating-history` | free |

## Steps

1. **Find the app** — `GET /apps` → `{ id, name, category, rating, … }` (your own
   `category` is here).
2. **Competitors** — `GET /apps/{id}/competitors?country=` (free) →
   `[{ id, name, developer, iconUrl, rating, ratingCount, category }]`. The
   `category` is each competitor's **primary store category** — this answers "what
   category do my competitors use?" (only the primary is exposed, not Apple's
   secondary).
3. **Add a rival** (if asked) — `POST /apps/{id}/competitors { "storeUrl": "…" }`
   (2 credits, **write** key). Confirm before writing.
4. **Category rank over time** — `GET /apps/{id}/category-rank?country=&days=30`
   (free) → `{ category, country, rankType, currentRank, points[]{ date, rank } }`.
5. **Rating trajectory** — `GET /apps/{id}/rating-history` (free) →
   `[{ rating, totalRatings, date }]`.
6. **Keyword overlap** — pair with **keyword-spy** on each competitor for the gap list.

Category-rank and rating-history are per-app; to compare a competitor, run the same
reads on that competitor's app id (it must be a tracked competitor).

## How to analyze

- **Category placement*

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: keyword-intelligence
description: When the user wants to analyze keyword performance for an app tracked in ASOScan (real search volume, difficulty, the app's current rank and rank movement, daily rank history, weekly volume/difficulty trends), or live on-demand research for a new term. Also use when the user mentions "how hard is this keyword", "search volume for X", "where do I rank for Y", "is my rank going up or down", "show my rank history", or "research this keyword". For discovering new keywords to target, see keyword-opportunities.
metadata:
  version: 1.3.6
---

# Keyword Intelligence

Turn ASOScan's real keyword data into a clear read on which keywords are worth the
effort and how the app is trending — so you prioritize from numbers, not hunches.

## When to use

- "What's the volume/difficulty of `<keyword>`?"
- "Where does my app rank for `<keyword>`? Is it moving?"
- "Show me my rank history / volume trend for `<keyword>`."
- "Research `<a keyword I don't track yet>`."

## Getting the data (two modes)

Pick the first mode that applies, then follow the steps below.

1. **ASOScan tools are connected** (the ASOScan plugin or connector in ChatGPT or Claude, or any MCP client): use the tool named in the table. Do not ask for an API key and do not run `curl`. Tool results have the same fields as the API responses below, and a list comes back inside `items`. If a tool answers with a message instead of data (reconnect, credits used up, plan limit, "preparing"), pass that message on and stop.
2. **No tools, but you can run shell commands and `ASOSCAN_API_KEY` is set**: make the API call in the table. Base `https://asoscan.com/api/public/v1`, header `Authorization: Bearer $ASOSCAN_API_KEY`, JSON with camelCase fields. Never print the key. Capture the HTTP status and handle errors as described at the bottom.
3. **Neither**: hand off to **asoscan-setup**. It explains how to connect ASOScan in ChatGPT or Claude, or how to create an API key.

ASOScan only sees the apps in the user's own account and the competitors they track. Every call uses API credits (failed calls are free). Before a call that costs more than 2 API credits, or one that uses AI, tell the user the cost and wait for a yes. Before any call that changes data, ask first.

| Step | Tool (connected) | API call (key) | API credits |
|---|---|---|---|
| Find the app | `list_my_apps` | `GET /apps` | free |
| Tracked keywords | `get_tracked_keywords` | `GET /apps/{id}/keywords?country=&rankWindow=7d` | free |
| Rank history | `get_keyword_rank_history` | `GET /apps/{id}/keywords/{keywordId}/history?days=30` | free |
| Volume and difficulty trend | `get_keyword_metrics_history` | `GET /apps/{id}/keywords/{keywordId}/metrics-history?days=180` | free |
| Live research | `research_keyword` | `GET /apps/{id}/keywords/research?term=&country=` | 8, say the cost first |

## Steps

1. **Find the app** — `GET /apps` → each `{ id, name, platform, storeId, category }`.
   Use the `id`.
2. **Tracked keywords + current state** — `GET /apps/{id}/keywords?country=&rankWindow=7d`
   (free). Each row: `{ id, term, country, rank, rankDelta, rankCheckedAt,
   volume, difficulty, isFavorite }`. `rankWindow` = `1d|7d|30d`. Fetch the list
   once and filter locally. The row's `id` is the `{keywordId}` for history calls.
3. **Rank history** — `GET /apps/{id}/keywords/{keywordId}/history?days=30`
   (free) → `[{ rank, recordedAt }]` (days 1–365).
4. **Volume/difficulty trend** — `GET /apps/{id}/keywords/{keywordId}/metrics-history?days=180`
   (free) → `{ term, country, volume[]{ at, value }, difficulty[]{ at, value } }`.
5. **Live research** (a term not tracked yet) — `GET /apps/{id}/keywords/research?term=…&country=US`
   (**8 credits every time, cache hit or not — reuse your own result instead of
   calling it twice for the same term in one conversation, that bills the user
   again for an answer you already have**; URL-encode the term) → `{ term,
   platform, country, volume, diffi

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: keyword-opportunities
description: When the user wants the best untapped keywords for an app tracked in ASOScan (gap-scored suggestions ranked by opportunity score, each showing which competitors already rank for the term). Also use when the user mentions "what keywords should I target", "find keyword opportunities", "what am I missing", "keyword gaps vs my competitors", or "suggest keywords to add". Can also start tracking the chosen terms. For validating a specific term's volume/difficulty, see keyword-intelligence.
metadata:
  version: 1.3.6
---

# Keyword Opportunities

Answer "what should I target next?" with ASOScan's pre-computed, opportunity-scored
suggestions, then track the winners, all from real numbers.

## When to use

- "What keywords should I add / target?"
- "Where are my keyword gaps vs competitors?"
- "Suggest high-opportunity keywords for my app."

## Getting the data (two modes)

Pick the first mode that applies, then follow the steps below.

1. **ASOScan tools are connected** (the ASOScan plugin or connector in ChatGPT or Claude, or any MCP client): use the tool named in the table. Do not ask for an API key and do not run `curl`. Tool results have the same fields as the API responses below, and a list comes back inside `items`. If a tool answers with a message instead of data (reconnect, credits used up, plan limit, "preparing"), pass that message on and stop.
2. **No tools, but you can run shell commands and `ASOSCAN_API_KEY` is set**: make the API call in the table. Base `https://asoscan.com/api/public/v1`, header `Authorization: Bearer $ASOSCAN_API_KEY`, JSON with camelCase fields. Never print the key. Capture the HTTP status and handle errors as described at the bottom.
3. **Neither**: hand off to **asoscan-setup**. It explains how to connect ASOScan in ChatGPT or Claude, or how to create an API key.

ASOScan only sees the apps in the user's own account and the competitors they track. Every call uses API credits (failed calls are free). Before a call that costs more than 2 API credits, or one that uses AI, tell the user the cost and wait for a yes. Before any call that changes data, ask first.

| Step | Tool (connected) | API call (key) | API credits |
|---|---|---|---|
| Find the app | `list_my_apps` | `GET /apps` | free |
| Opportunities | `find_keyword_opportunities` | `GET /apps/{id}/opportunities?country=&limit=50` | 2 |
| Validate a finalist | `research_keyword` | `GET /apps/{id}/keywords/research?term=&country=` | 8, say the cost first |
| Track the picks (changes data) | `track_keywords` | `POST /apps/{id}/keywords` with `{ "terms": [...], "country": "US" }` | 2, ask first |

## Steps

1. **Find the app** — `GET /apps` → use the `id`.
2. **Opportunities** — `GET /apps/{id}/opportunities?country=&limit=50` (**2 credits**,
   limit 1–200). Each row: `{ term, volume, difficulty, opportunityScore,
   competitorRanks[]{ name, rank, isYou } }`. There is **no** "source" field — rank
   by `opportunityScore` and read `competitorRanks` for context (the entry with
   `isYou: true` is the owner; `rank: null` there = you don't rank yet).
3. **(Optional) validate a shortlisted term** — the research call in
   **keyword-intelligence** (8 credits), for a few finalists only.
4. **(Optional) track the picks** — `POST /apps/{id}/keywords` with
   `{ "terms": [...], "country": "US" }` (**2 credits**, needs a **write** key; up
   to 500 terms) → `{ added[], skipped[]{ term, reason } }`.

## How to prioritize

Sort by `opportunityScore`, then sanity-check each candidate:

1. **Relevant?** Would a searcher for this term actually want this app? Drop
   off-topic high-volume terms — irrelevant installs churn.
2. **Winnable?** Is `difficulty` realistic for this app's authority?
3. **A real gap?** In `competitorRanks`, `isYou` has a null/poor rank while rivals
   rank well → the sharpest opportunity.

Group into **Quick wins** (high score, low difficulty, relevant, you don't rank)
and **Watchlist** (promising 

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: keyword-spy
description: When the user wants to reverse-look-up every keyword an app ranks for using ASOScan's keyword-spy (the full set of terms an app appears under, community rank pool plus discovered terms), flagged by whether you already track them. Also use when the user mentions "what keywords does this app rank for", "reverse keyword lookup", "spy on a competitor's keywords", "what search terms is X winning", or "which of their keywords am I missing". For the fuller competitive picture, see competitor-analysis.
metadata:
  version: 1.3.6
---

# Keyword Spy

See the full keyword footprint of an app — yours or a tracked competitor's — with
ASOScan, and mine it for real terms you should be targeting too.

## When to use

- "What keywords does `<app>` rank for?"
- "Spy on `<competitor>`'s keywords."
- "Which of their terms am I not tracking?"

## Getting the data (two modes)

Pick the first mode that applies, then follow the steps below.

1. **ASOScan tools are connected** (the ASOScan plugin or connector in ChatGPT or Claude, or any MCP client): use the tool named in the table. Do not ask for an API key and do not run `curl`. Tool results have the same fields as the API responses below, and a list comes back inside `items`. If a tool answers with a message instead of data (reconnect, credits used up, plan limit, "preparing"), pass that message on and stop.
2. **No tools, but you can run shell commands and `ASOSCAN_API_KEY` is set**: make the API call in the table. Base `https://asoscan.com/api/public/v1`, header `Authorization: Bearer $ASOSCAN_API_KEY`, JSON with camelCase fields. Never print the key. Capture the HTTP status and handle errors as described at the bottom.
3. **Neither**: hand off to **asoscan-setup**. It explains how to connect ASOScan in ChatGPT or Claude, or how to create an API key.

ASOScan only sees the apps in the user's own account and the competitors they track. Every call uses API credits (failed calls are free). Before a call that costs more than 2 API credits, or one that uses AI, tell the user the cost and wait for a yes. Before any call that changes data, ask first.

| Step | Tool (connected) | API call (key) | API credits |
|---|---|---|---|
| Find the app | `list_my_apps` | `GET /apps` | free |
| Is the rival tracked? | `get_competitors` | `GET /apps/{id}/competitors` | free |
| Add the rival by store link (changes data) | `add_competitor` | `POST /apps/{id}/competitors` with `{ "storeUrl": "..." }` | 2, ask first |
| Spy | `spy_competitor_keywords` | `GET /apps/{id}/keyword-spy?country=` | 2 |

## Steps

1. **Find the app** — `GET /apps` → use the `id`.
   - **Own app** → spy it directly.
   - **A rival** → it must be a **tracked competitor** first. Check
     `GET /apps/{id}/competitors`; if absent, add it via
     `POST /apps/{id}/competitors { "storeUrl": "…" }` (2 credits, **write** key),
     then spy the returned competitor's `id`. Add-by-URL only — there's no lookup
     by app name.
2. **Spy** — `GET /apps/{id}/keyword-spy?country=` (**2 credits**) →
   `{ appName, totalKeywordsFound, communityPoolSize, discoveryStatus,
   keywords[]{ term, rank, volume, difficulty, origin, isTracked } }`.
   - `origin` = `"community"` \| `"discovered"`; `isTracked` = already in your set.
   - `discoveryStatus` = `"cached"` \| `"none"`. The public API doesn't trigger a
     fresh crawl, so a just-added competitor may be sparse until ASOScan's
     background discovery has cached results — re-calling won't add more right away.

## How to analyze

1. **Coverage** — how many terms, split by `origin`.
2. **Steal list** (the payoff) — terms the *competitor* ranks for that are relevant
   to your app AND `isTracked = false`. Filter for relevance first.
3. **Overlap** — terms you both rank for (battlegrounds).
4. Feed the best into **keyword-intelligence** (validate) then **keyword-opportunities**
   (track) — the natural next steps in ASOScan.

## Output template

```
### Keyword spy — {target ap

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: metadata-audit
description: When the user wants to audit or improve an app's store listing metadata using ASOScan (the current title, subtitle/short description, description, keyword field, and what's-new, plus ASOScan's ASO score and recommendations and the change history), then draft specific, honest improvements within the platform's character limits. Also use when the user mentions "audit my listing", "improve my metadata", "optimize my title/subtitle/description", "what's my ASO score", "rewrite my app store copy", or "what changed in my listing", or wants listing text drafted for another language ("translate my listing", "localize my listing"). For choosing which keywords to target, see keyword-opportunities.
metadata:
  version: 1.3.6
---

# Metadata Audit

Score the listing with ASOScan's ASO score, find the gaps, and draft better copy —
specific, within limits, and honest.

## When to use

- "Audit / optimize my app listing." · "What's my ASO score and how do I raise it?"
- "Rewrite my title / subtitle / description." · "What metadata changed recently?"

## Getting the data (two modes)

Pick the first mode that applies, then follow the steps below.

1. **ASOScan tools are connected** (the ASOScan plugin or connector in ChatGPT or Claude, or any MCP client): use the tool named in the table. Do not ask for an API key and do not run `curl`. Tool results have the same fields as the API responses below, and a list comes back inside `items`. If a tool answers with a message instead of data (reconnect, credits used up, plan limit, "preparing"), pass that message on and stop.
2. **No tools, but you can run shell commands and `ASOSCAN_API_KEY` is set**: make the API call in the table. Base `https://asoscan.com/api/public/v1`, header `Authorization: Bearer $ASOSCAN_API_KEY`, JSON with camelCase fields. Never print the key. Capture the HTTP status and handle errors as described at the bottom.
3. **Neither**: hand off to **asoscan-setup**. It explains how to connect ASOScan in ChatGPT or Claude, or how to create an API key.

ASOScan only sees the apps in the user's own account and the competitors they track. Every call uses API credits (failed calls are free). Before a call that costs more than 2 API credits, or one that uses AI, tell the user the cost and wait for a yes. Before any call that changes data, ask first.

| Step | Tool (connected) | API call (key) | API credits |
|---|---|---|---|
| Find the app | `list_my_apps` | `GET /apps` | free |
| ASO score | `get_aso_score` | `GET /apps/{id}/aso-score?country=` | free |
| ASOScan recommendations | `get_aso_recommendations` | `GET /apps/{id}/recommendations` | free |
| Current listing text | `get_listing_metadata` | `GET /apps/{id}/metadata?country=` | free |
| Change history | `get_metadata_changelog` | `GET /apps/{id}/metadata/changelog?country=` | free |
| Saved drafts for other languages | `list_localized_drafts` | `GET /apps/{id}/localizations/drafts` | free |
| Draft listing text for another language (AI) | `draft_localized_metadata` | `POST /apps/{id}/localizations/{locale}/draft` | 2 + 1 AI credit, say the cost first |

## Steps

1. **Find the app** — `GET /apps` → note the `id` and `platform` (Apple vs Google —
   the rules differ).
2. **ASO score (authoritative)** — `GET /apps/{id}/aso-score?country=` (free) →
   `{ overall, metadata, ratings, conversion, conversionIsProxy, grade, platform,
   recommendations[]{ category, severity, title, description } }` (0–100; severity
   `critical|warning|info`). **Use this as the headline number; don't invent one.**
3. **Recommendations** (`get_aso_recommendations` or `GET /apps/{id}/recommendations`) → `{ items[]{ id, status, platform, category, priority, title, why, how, expectedImpact, updatedAt }, generatedAt }`. Lead with the highest priority items and use their `why` and `how` in your field-by-field advice.
4. **Current metadata**: `GET /apps/{id}/metadata?country=` (free) →
   `{ title, subtitle, promotionalText,

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: review-insights
description: When the user wants to understand what users say about an app using ASOScan (overall review sentiment plus the top topics, feature requests, and bugs mentioned, and the raw reviews behind them). Also use when the user mentions "what are users saying", "review sentiment", "top complaints", "what features are people asking for", "what bugs are mentioned", or "summarize my reviews". Also use to draft a reply to a review and, after the user approves the exact text, post it ("reply to this review", "write a reply"). Works for your app or a tracked competitor.
metadata:
  version: 1.3.6
---

# Review Insights

Turn ASOScan's analyzed review stream into the few things that matter: how users
feel, what they keep asking for, and what's breaking.

## When to use

- "What are users saying about my app?"
- "Top complaints / feature requests / bugs."
- "Summarize the latest reviews." (also for a tracked competitor)

## Getting the data (two modes)

Pick the first mode that applies, then follow the steps below.

1. **ASOScan tools are connected** (the ASOScan plugin or connector in ChatGPT or Claude, or any MCP client): use the tool named in the table. Do not ask for an API key and do not run `curl`. Tool results have the same fields as the API responses below, and a list comes back inside `items`. If a tool answers with a message instead of data (reconnect, credits used up, plan limit, "preparing"), pass that message on and stop.
2. **No tools, but you can run shell commands and `ASOSCAN_API_KEY` is set**: make the API call in the table. Base `https://asoscan.com/api/public/v1`, header `Authorization: Bearer $ASOSCAN_API_KEY`, JSON with camelCase fields. Never print the key. Capture the HTTP status and handle errors as described at the bottom.
3. **Neither**: hand off to **asoscan-setup**. It explains how to connect ASOScan in ChatGPT or Claude, or how to create an API key.

ASOScan only sees the apps in the user's own account and the competitors they track. Every call uses API credits (failed calls are free). Before a call that costs more than 2 API credits, or one that uses AI, tell the user the cost and wait for a yes. Before any call that changes data, ask first.

| Step | Tool (connected) | API call (key) | API credits |
|---|---|---|---|
| Find the app | `list_my_apps` | `GET /apps` | free |
| Insights | `get_review_insights` | `GET /apps/{id}/reviews/insights` | free |
| Raw reviews | `get_reviews` | `GET /apps/{id}/reviews?page=1&pageSize=20&rating=&sort=newest` | free |
| Saved reply templates | `list_reply_templates` | `GET /apps/{id}/reviews/reply-templates` | free |
| Draft a reply (AI) | `draft_review_reply` | `POST /apps/{id}/reviews/{reviewId}/reply-draft` with `{ "instructions": "...", "autoSelectKeyword": true }` | 2 + 1 AI credit, say the cost first |
| Post a reply (goes to the store) | `post_review_reply` | `POST /apps/{id}/reviews/{reviewId}/reply` with `{ "text": "..." }` | 2, exact text and a clear yes first |

## Steps

1. **Find the app** — `GET /apps` → use the `id`. For a rival, it must be a tracked
   competitor first (see **competitor-analysis**).
2. **Insights** — `GET /apps/{id}/reviews/insights` (free) →
   `{ totalAnalyzed, totalPending, sentiment{ positive, neutral, negative,
   averageScore }, topTopics[]{ label, count }, topFeatureRequests[]{ label, count },
   topBugs[]{ label, count } }`.
3. **Raw reviews** (for evidence) — `GET /apps/{id}/reviews?page=1&pageSize=20&rating=&sort=newest`
   (free; pageSize 1–100; `rating=1..5` to isolate detractors/promoters) →
   `{ items[]{ id, author, rating, title, body, version, country, postedAt,
   developerResponse, developerResponseAt }, page, pageSize, totalCount, totalPages }`.

Lead with insights; pull raw reviews only to quote real examples. If `totalPending`
is high, note that more reviews are still being analyzed.

## How to analyze

- **Sentiment** — the positive/neutral/negative split + `averageScore` (pair with
  

Preview of the first 4,000 characters. Read full instructions →