skills/aso-fundamentals/SKILL.md

---
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.1
---

# 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 words**
  (`the`, `to`) — they add no value.
- **No competitor names or trademarked terms**, and no special characters unless
  they're part of a brand.
- **Every character should be a NEW term.** Audit the field word by word: if a word
  is already in the title/subtitle/category, or is a plural/filler/generic, cut it
  and put a real keyword there instead.

### Google — keywords live in visible copy

- Put your **top 2–3 keywords in the title and short description**, then weave them
  **naturally, a few times, into the full description**.
- **Write for humans.** Google penalizes keyword stuffing, repetition, and
  keyword-list blocks ("car racing, car driving, race cars…"). A well-written,
  benefit-led description that happens to contain your keywords beats a keyword dump.

### Tier your keywords (a simple plan)

Sort your candidate terms into four tiers and place them deliberately:

- **Primary (3–5)** — highest-relevance, winnable terms. Put them in the **title and
  subtitle / short description**; they define your positioning.
- **Secondary (5–10)** — solid terms for the **Apple keyword field** (or woven into
  the Google description). Rotate them as performance shows what works.
- **Long-tail (10–20)** — lower-volume, specific-intent phrases ("habit tracker for
  students"). Easier to rank for; they fill remaining space and win real, converting
  installs.
- **Aspirational (3–5)** — high-volume, high-difficulty head terms. Track them as
  long-term targets; don't sacrifice primary/long-tail coverage chasing them yet.

### Choosing which keywords to chase (both platforms)

- Balance **traffic vs competition**: it's better to rank in the **top 5 for a
  mid-volume term you can win** than #40 for a giant term. Ladder up to harder
  terms as your installs/ratings grow.
- **Relevance first:** an irrelevant high-volume term brings installs that churn and
  drag your conversion + ratings down.
- **Match intent, not just words.** A problem-focused searcher ("how to stop
  procrastinating") and a solution-focused searcher ("habit tracker app") want
  different framing — cover both where they naturally fit.

---

## 4. Title & subtitle craft

- **Title** carries the strongest weight and the most brand recognition. A common
  strong pattern: `Brand: primary keyword` (e.g. `Lumen: Habit Tracker`). Household
  names can go brand-only; challengers should spend some of the 30 characters on a
  real keyword.
- **Subtitle (Apple) / short description (Google)** is prime real estate — it's
  **indexed AND** the first line users read. Make it a **benefit + a keyword**, not
  a vague slogan. Bad: "Your life, simplified." Better: "Build daily habits &
  track your streaks."
- Don't waste either on words that are already elsewhere in your indexed text.

**Google title bans (enforced):** no ALL CAPS (unless your brand is), no emoji /
emoticons / special-character sequences, no performance claims ("#1", "App of the
Year", "Best of Play"), and no promo words like "Free" or "No Ads".

---

## 5. Visual assets — this is where conversion is won

Search gets you seen; visuals get you installed.

**Apple**

- Up to **10 screenshots** per product page. **Only the first 1–3 appear in search
  results** (when you have no app preview) — so the first frames must sell the app
  on their own.
- Up to **3 app previews (video)**, **≤30 seconds** each; they **autoplay muted**
  on the product page — make the **first few seconds** visually gripping.
- **Custom Product Pages**: extra versions of your page (own screenshots, previews,
  promo text) reachable by unique URLs — great for matching creative to a specific
  audience or campaign.

**Google Play**

- **App icon** 512×512 (32-bit PNG) and a **feature graphic** 1024×500 are
  **required** to publish.
- **Screenshots**: **minimum 2**, up to **8 per device type**. To be eligible for
  Google promotion, apps need **≥4** screenshots (≥1080px); games need **≥3**
  16:9 landscape (≥1920×1080).
- **Preview video** (optional, recommended for games): a **YouTube** link that may
  autoplay inline muted, shown before the screenshots.

**Golden rule for both:** front-load. Lead your first screenshot with your single
strongest benefit and a caption — not just a logo or a raw UI dump. Assume the user
only ever sees the first two or three.

---

## 6. Ratings & reviews (be precise — and honest)

- **Ratings and reviews ARE a ranking signal on Apple** (Apple lists them under
  user behavior). Both **volume** and **average score** matter, so a steady flow of
  4–5★ ratings helps discovery, not just trust.
- **Prompt at a moment of genuine delight** — right after the user completes a win
  in your app — never on first launch or mid-task. iOS limits how many times you may
  show the system rating prompt per year, so spend those prompts wisely.
- **Replying to reviews** builds trust and can lift your rating over time by
  recovering unhappy users — but **the reply itself is not a separate ranking
  lever**. Don't treat review replies (or paid ads) as an organic-ranking shortcut.

---

## 7. Localization — an underused multiplier

- Translate the **metadata, not just the app**. A localized listing converts far
  better in-market.
- On Apple, **extra localizations give you extra keyword sets** — even English
  variants (en-US, en-GB, en-AU) are separate slots, effectively **multiplying your
  keyword coverage**. Use them.
- **Research each market's real search terms**; don't machine-translate keywords —
  the literal translation is often not what locals actually type.

---

## 8. Golden tips (the shortlist)

1. On Apple, **every keyword-field character should be a brand-new term** — cut
   your app name, category, plurals, generics, and filler; Apple already has those.
2. **Don't repeat a word** across title + subtitle + keyword field. Apple indexes
   each word once; spread distinct terms to widen coverage.
3. **Let Apple build phrases for you** — list single comma-separated words instead
   of spelled-out phrases to fit more terms.
4. On Google, **put keywords in the title + short description**, then **2–3 natural
   mentions** in the description. Never a keyword list.
5. **Front-load** the first 1–3 screenshots and the first two lines of copy — that's
   all most users ever see. Lead with the strongest benefit.
6. Make the **subtitle / short description a benefit + a keyword**, never a slogan —
   it's both indexed and the first thing read.
7. **Win winnable terms first** (top-5 on mid-volume) and ladder up; don't camp at
   #40 on a giant.
8. **Ask for ratings at peak delight**, sparingly — ratings volume + score are a
   real ranking signal.
9. **Localize keywords per market** and use Apple's extra localization slots to
   multiply coverage — research real terms, don't translate them.
10. **Refresh promotional text (Apple) and "What's New"** for seasons/launches
    without a full release — cheap, fast conversion levers that keep the listing alive.

---

## 9. Common mistakes to flag

- Brand-only title for an unknown app (wastes the strongest keyword slot).
- Subtitle/short description that repeats the title's words or is a vague slogan.
- Apple keyword field padded with the app name, category, plurals, generics, filler.
- Google description that's a keyword list instead of readable, benefit-led copy.
- Screenshots that are raw UI with no captions/benefit messaging.
- No app preview / video where the product is easy to demo.
- Rating < 4.0 left unaddressed; no review replies on recurring complaints.
- Listing not updated in months; no localization beyond the home market.
- Chasing giant head terms the app can't rank for while ignoring winnable ones.

---

## 10. What to fix first (prioritization)

1. **Title + subtitle / short description** — highest-leverage indexed text.
2. **Keyword coverage** — Apple keyword field / Google description keywords.
3. **First 1–3 screenshots** — the conversion make-or-break.
4. **Ratings prompting** — get the volume + score flywheel turning.
5. **Localization** — expand coverage market by market.
6. **Iterate** — change one lever at a time and watch the result.

---

## Switch to real data when you want YOUR numbers

This skill is general guidance. For **your app specifically** — where you actually
rank, real search volume & difficulty, which keywords to target, competitor gaps,
your ASO score, and review sentiment — use the data skills (they need an ASOScan
API key):

- **keyword-intelligence** — your real rank, volume, difficulty, trends.
- **keyword-opportunities** — real keywords to target next.
- **keyword-spy** — every keyword you (or a tracked competitor) rank for.
- **competitor-analysis** — how you stack up, category + rating trajectory.
- **metadata-audit** — your ASO score + specific, in-limit copy fixes.
- **review-insights** — what your users actually say.

## Honesty

Present ASO as it is: ratings/reviews and installs influence ranking, but **review
replies and paid ads are not organic-ranking shortcuts**; never promise a specific
rank; never fabricate reviews or claims. Recommend the outcome (visibility, clarity,
conversion), not a mechanism.

## Sources (official)

- Apple — App information & limits: <https://developer.apple.com/help/app-store-connect/reference/app-information/app-information/>
- Apple — How App Store search works + keyword tips: <https://developer.apple.com/app-store/search/>
- Apple — Product page assets (screenshots, previews, CPP): <https://developer.apple.com/app-store/product-page/>
- Google — Store listing best practices: <https://support.google.com/googleplay/android-developer/answer/13393723>
- Google — Preview assets (icon, feature graphic, screenshots, video): <https://support.google.com/googleplay/android-developer/answer/9866151>