ASO research

Search is where almost all of a new app's impressions come from, and the app can only appear for words that are in three short fields. Choosing those words by intuition wastes the launch. This skill replaces intuition with what the store shows: real result pages, real autocomplete, real competitors, in each country that matters.

Two files carry the weight:

• references/aso-knowledge-base.md: how App Store search works, the rules for each field, which locales each country's store reads, and how solid each claim is. It is where "everyone knows" ASO advice is separated from what Apple documents and what was measured. Before proposing anything, read sections 2 to 5 (fields, keyword rules, locales, ranking), 11 (category) and 14 (naming). The rest (screenshots, conversion benchmarks, page tests, ratings, ads, Google Play) is for when the task touches it.
• scripts/store-research.mjs: the data. No account needed. Paths are relative to this skill's folder; run it from the app's repository with its absolute path.

node scripts/store-research.mjs rank us "shared grocery list" "family shopping list" --app <id>   # the real first page
node scripts/store-research.mjs hints de "einkaufsliste"                                          # what people type
node scripts/store-research.mjs sweep us us-terms.txt --app <id> --out sweep-us.json              # many terms, one table
node scripts/store-research.mjs lookup us <id> <id> --full                                        # rivals: subtitle, in-app prices, text
node scripts/store-research.mjs shots us <id> <id> --count 3 --out store/research/rivals          # rivals' first screenshots, to look at
node scripts/store-research.mjs reviews us <id> --max-stars 2                                     # what their users complain about
node scripts/store-research.mjs chart us 6007 free                                                # a category's top chart
node scripts/store-research.mjs search us "grocery list"                                          # broad discovery (NOT a ranking)

Only rank and sweep show what a shopper sees. The search command's order is a different algorithm; never quote it as a ranking. rank prints !! when the store appears to have answered a different query than the one typed.

What you deliver

store/research/aso-report.md in the app's repo, and a short version of its first section sent to the owner for approval. Nothing is entered in the store from this skill. The owner sees everything before any edit: the proposal is approved first, then store-listing and app-store-connect act on it.

Which countries to research: the ones the owner profile (~/.claude/app-launch-profile.md) names, if there is one; otherwise the owner's own market and the United States, plus what they answer when asked on day one.

The work

1. Know the app

From the code and the owner's words: what it does, for whom, the one thing it does that rivals do not, how it earns money, which languages it speaks. Write the user's problem in the user's own words; those words are the first seed terms.

For an app that is already live, also record the baseline: what the public listing says now (lookup --full), where it ranks for its obvious terms, and its App Analytics for the last weeks (impressions, page views, downloads, by source and by country). Analytics needs a signed-in browser (../app-launch/references/computer-use.md) or an analytics report request. Read the numbers carefully: how many downloads came straight from search results versus the product page, and which country converts. State sample sizes, and do not draw conclusions from a few dozen impressions.

2. Collect what people type

Start with 20 to 40 seed terms: the problem, the audience ("family", "couples", "roommates"), the object ("list", "planner"), the verbs. Feed each to hints in every target country and keep what autocomplete offers back; those are searches real people make often enough for Apple to suggest. Follow the chains (a suggestion is the next seed). Translate nothing: in each country, start from how a local would say it and let autocomplete correct you.

Apple gives no search volumes without an Apple Search Ads account. Autocomplete presence and position is the proxy; say so in the report instead of inventing numbers.

3. Find the competitors

rank the ten strongest terms in the main country. The apps that keep appearing are the competitors, whatever category they sit in. For the top eight to twelve, lookup --full and record: name, subtitle, rating and count, what they charge (the in-app purchase list), last update. Download their first screenshots with shots and look at them (Read the image files): write down the headline each one leads with. A line three rivals already use is a line to avoid.

Then their reviews, the low ones especially: what users of the leaders complain about is positioning handed to you. Apple serves only about ten "most helpful" reviews per app without an account, mostly positive, so --max-stars 2 often returns nothing. When it does, search the web for complaints about the app, or send a browser task to the product page; say in the report how many low reviews you actually read.

Check the category's top chart for who dominates it and how new the newest app on it is.

4. Measure each term

Put each country's candidate terms in its own file (they are different words in each language) and sweep them. For each term the table gives: whether autocomplete offers the exact term and how high, how many first-page titles carry the exact phrase, the smallest and the median rating count in the top five, and how many apps with under 50 ratings sit in the top ten. A term is open to a new app when:

• people search it (autocomplete offers it),
• it describes the app truthfully,
• newcomers already rank for it: apps with few ratings in the top ten, a low minimum in the top five.

A new app cannot outrank an 80,000-rating leader on a two-word head term. It can reach the first page for a longer phrase that its own title matches exactly. Find that phrase; it becomes the descriptive half of the name.

In a young niche most terms pass that test. Then choose between them in this order: the phrase that names the app's main job most literally; the one autocomplete ranks higher from the shortest seed; the one with fewer exact-title matches on its first page; the one that fits in the name beside the brand. Autocomplete position is a weak signal, so say which terms were close. If the owner has an Apple Ads account, its search popularity score is better evidence and worth one browser task.

5. Test the brand name in the store

Two different problems, both checked with rank in every target country:

• The store rewrites the brand. rank <cc> "<brand>" shows another brand's apps and the !! warning. Users who search the app's name will not find it until the store learns the word, which takes downloads. Report it plainly, with the countries. It does not by itself mean dropping the brand: brand first, then the descriptive phrase, with the phrase doing the finding.
• Others already use the name. rank <cc> "<brand>" and rank <cc> "<brand> <what the app is>" list apps called the same or one letter off. In the same niche this is serious: the app will be mistaken for them, their ratings outrank it on its own name, and App Store Connect refuses an app name that is already taken, so the exact name you want may not be available at all. Then recommend a different or modified brand, with two or three tested alternatives, before anything is created under the old one. In an unrelated category it is only worth a line in the report.

A common word or a near-miss of a famous brand has both problems. Checking trademarks is beyond these tools; say that it was not done.

When the owner asks whether one name order is better than another, test both phrasings in real results across the countries and give one answer with the evidence. Do not answer from theory, and do not flip when pushed without new data.

6. Decide

Following the field rules in the knowledge base:

• Name: brand, colon, the winnable phrase, in 30 characters. When they do not fit, keep the phrase whole and in the order people type it and choose a shorter phrase that passed step 4; do not truncate a phrase or drop the brand. A word that had to go moves to the subtitle.
• Subtitle: the second-best phrase, in words not used in the name, readable as a line of text a person would write. Two keywords joined by "&" is not a subtitle.
• Keywords: 100 characters of words that combine with the name and subtitle into the remaining phrases; no repeats, no category words, no competitor names. (Apple's field reference says 100 bytes; a 100-character field with accents has been accepted. Treat characters as the limit and shorten if App Store Connect refuses.)
• Category: primary where the app competes best and is honestly described; secondary for the other audience. Look at where the rivals sit and how crowded each chart is.
• Locales: the countries the owner cares about, plus the locales that those countries' stores read beyond their own (the table in the knowledge base). Each added locale is 160 more indexed characters. Every locale gets its own researched terms, steps 2 to 4 again in that country. This skill decides the name, subtitle and keyword field for every locale; store-listing takes them as given and writes the rest.
• Price position if the app sells something: what the rivals charge and for what.

Run the per-country research in parallel, one subagent per language market, each with this skill's script, the seed list, and the instruction to return the sweep table and its chosen name, subtitle and keywords with the evidence. A subagent's ranking claims are checked with a rank call of your own before they go in the report.

7. Write the report

# <App>: ASO research (<date>)

## Proposal (for approval)
Per locale: name · subtitle · keywords, with character counts. Category. Locales and why. Price position.
What changes versus today, if the app is live.

## Why
The phrase we can win and the evidence (the result page today, who is on it, their rating counts).
What we are not trying to win yet, and why.

## Baseline (live apps)
Analytics with dates and sample sizes; current positions.

## Competitors
Table: app · name and subtitle · ratings · price model · last update · what the first screenshots say.
What their users complain about.

## Keywords by country
Table per country: term · autocomplete position · exact-title matches · top-5 ratings min/median · apps under 50 ratings in the top ten · our position · decision.

## Brand check
How each store treats the brand name; other apps with the same or a similar name, and in which category.

## For the screenshots and the description
The words users use; the claims rivals make; the gap to show.

## Not verified
What could not be measured (search volumes, anything behind a login), and what was inferred.

Then send the owner the proposal message (../app-launch/references/owner-inputs.md has its shape): the Proposal section, briefly, with the two or three facts that justify it and anything they should be warned about, asking for a yes. For a new app it also carries the one step that follows from it, creating the app record under the approved name. While waiting, the screenshots' storyboard and the description draft can start; they are easy to adjust if a word changes.

Nobody on the team may read the languages you researched. Say so in the report, and mark the foreign-language choices you are least sure of.

Honesty in research

• Result pages change by day and by person. Quote positions with the date, and re-check the ones a decision rests on.
• "First page" from the web store is the first ten to twelve results; it is the closest public view of ranking, not a guarantee of what every phone shows.
• A claim from a tool vendor's blog is a lead, not a fact. The knowledge base marks which is which; keep the marks when you repeat a claim.
• If you told the owner something that later proves wrong, correct it in the next message, with the right number.