Update to ASOScan App Store Optimization

{
  "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).",
  "included_files": [],
  "name": "aso-fundamentals",
  "skill_md_contents": "---\nname: aso-fundamentals\ndescription: 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).\nmetadata:\n  version: 1.3.1\n---\n\n# ASO Fundamentals — expert guidance, no data required\n\nExpert App Store Optimization know-how: how the stores actually work, what to\noptimize, and the golden rules. **This skill needs no API key** — it's general best\npractice grounded in Apple's and Google's official docs.\n\nBest practice only takes you so far without data. **ASOScan** turns each principle\ninto your real numbers (rank, volume, difficulty, score, opportunities). When the\nASOScan tools are connected in ChatGPT or Claude, the data skills use them directly;\notherwise get set up with **asoscan-setup**, then use the data skills.\n\n> Store rules change. The facts here follow Apple's and Google's current official\n> developer documentation (sources at the bottom). If a specific limit is\n> decision-critical for a release, confirm it against those docs first.\n\n---\n\n## 1. How store search actually works (the mental model)\n\n**Apple App Store** ranks results on two things:\n\n- **Text relevance** — matches against your **app name, subtitle, keyword field,\n  and primary category**.\n- **User behavior** — downloads, **ratings and reviews**, and more.\n\nYour **long description is NOT part of Apple's search index** — it's for\n*conversion*, not discovery. Put your keyword effort into the name, subtitle, and\nkeyword field.\n\n**Google Play** works differently: there is **no hidden keyword field**. Your\nsearchable text is the **title, short description, and full description** — so your\nkeywords must live in visible copy that *also reads naturally*. Google explicitly\nwarns against keyword stuffing.\n\n> **The one line to remember:** On Apple, keywords go in a *hidden* field and the\n> description is for humans. On Google, keywords go in the *visible* description\n> and must read like real sentences.\n\n---\n\n## 2. The metadata fields + limits\n\n| Field | Apple | Google | In search index? |\n|---|---|---|---|\n| Title / App name | 30 chars | 30 chars | Yes — strongest signal |\n| Subtitle (Apple) / Short description (Google) | 30 chars | 80 chars | Yes |\n| Keyword field (Apple only) | 100 chars, comma-separated | — | Yes (hidden) |\n| Description | 4,000 chars | 4,000 chars | **Apple: No** · **Google: yes — write it naturally** |\n| Promotional text (Apple only) | 170 chars | — | No — but updatable anytime, no release needed |\n\n---\n\n## 3. Keyword strategy\n\n### Apple — the hidden 100-character keyword field (golden rules)\n\nApple's own guidance:\n\n- **Separate terms with commas, no space between terms.** You *may* use a space\n  inside a phrase (`Real Estate`), but every space costs a character — so most ASO\n  pros list **single words** and let Apple recombine them. Apple forms phrases by\n  combining words across your **name + subtitle + keyword field**, so\n  `habit,tracker,daily,routine,planner` already covers \"habit tracker\", \"daily\n  habit\", \"routine planner\", etc. — without spending characters on the phrases.\n- **Never repeat a word** that's already in your app name, subtitle, or category —\n  Apple indexes each word once; a repeat is wasted space.\n- **Don't add plurals** of a word you already used (`climb` / `climbs` count as\n  duplicates). Apple handles the variation.\n- **Skip generic, overly broad terms** (`app`, `game`) and **filler words**\n  (`the`, `to`) — they add no value.\n- **No competitor names or trademarked terms**, and no special characters unless\n  they're part of a brand.\n- **Every character should be a NEW term.** Audit the field word by word: if a word\n  is already in the title/subtitle/category, or is a plural/filler/generic, cut it\n  and put a real keyword there instead.\n\n### Google — keywords live in visible copy\n\n- Put your **top 2–3 keywords in the title and short description**, then weave them\n  **naturally, a few times, into the full description**.\n- **Write for humans.** Google penalizes keyword stuffing, repetition, and\n  keyword-list blocks (\"car racing, car driving, race cars…\"). A well-written,\n  benefit-led description that happens to contain your keywords beats a keyword dump.\n\n### Tier your keywords (a simple plan)\n\nSort your candidate terms into four tiers and place them deliberately:\n\n- **Primary (3–5)** — highest-relevance, winnable terms. Put them in the **title and\n  subtitle / short description**; they define your positioning.\n- **Secondary (5–10)** — solid terms for the **Apple keyword field** (or woven into\n  the Google description). Rotate them as performance shows what works.\n- **Long-tail (10–20)** — lower-volume, specific-intent phrases (\"habit tracker for\n  students\"). Easier to rank for; they fill remaining space and win real, converting\n  installs.\n- **Aspirational (3–5)** — high-volume, high-difficulty head terms. Track them as\n  long-term targets; don't sacrifice primary/long-tail coverage chasing them yet.\n\n### Choosing which keywords to chase (both platforms)\n\n- Balance **traffic vs competition**: it's better to rank in the **top 5 for a\n  mid-volume term you can win** than #40 for a giant term. Ladder up to harder\n  terms as your installs/ratings grow.\n- **Relevance first:** an irrelevant high-volume term brings installs that churn and\n  drag your conversion + ratings down.\n- **Match intent, not just words.** A problem-focused searcher (\"how to stop\n  procrastinating\") and a solution-focused searcher (\"habit tracker app\") want\n  different framing — cover both where they naturally fit.\n\n---\n\n## 4. Title & subtitle craft\n\n- **Title** carries the strongest weight and the most brand recognition. A common\n  strong pattern: `Brand: primary keyword` (e.g. `Lumen: Habit Tracker`). Household\n  names can go brand-only; challengers should spend some of the 30 characters on a\n  real keyword.\n- **Subtitle (Apple) / short description (Google)** is prime real estate — it's\n  **indexed AND** the first line users read. Make it a **benefit + a keyword**, not\n  a vague slogan. Bad: \"Your life, simplified.\" Better: \"Build daily habits &\n  track your streaks.\"\n- Don't waste either on words that are already elsewhere in your indexed text.\n\n**Google title bans (enforced):** no ALL CAPS (unless your brand is), no emoji /\nemoticons / special-character sequences, no performance claims (\"#1\", \"App of the\nYear\", \"Best of Play\"), and no promo words like \"Free\" or \"No Ads\".\n\n---\n\n## 5. Visual assets — this is where conversion is won\n\nSearch gets you seen; visuals get you installed.\n\n**Apple**\n\n- Up to **10 screenshots** per product page. **Only the first 1–3 appear in search\n  results** (when you have no app preview) — so the first frames must sell the app\n  on their own.\n- Up to **3 app previews (video)**, **≤30 seconds** each; they **autoplay muted**\n  on the product page — make the **first few seconds** visually gripping.\n- **Custom Product Pages**: extra versions of your page (own screenshots, previews,\n  promo text) reachable by unique URLs — great for matching creative to a specific\n  audience or campaign.\n\n**Google Play**\n\n- **App icon** 512×512 (32-bit PNG) and a **feature graphic** 1024×500 are\n  **required** to publish.\n- **Screenshots**: **minimum 2**, up to **8 per device type**. To be eligible for\n  Google promotion, apps need **≥4** screenshots (≥1080px); games need **≥3**\n  16:9 landscape (≥1920×1080).\n- **Preview video** (optional, recommended for games): a **YouTube** link that may\n  autoplay inline muted, shown before the screenshots.\n\n**Golden rule for both:** front-load. Lead your first screenshot with your single\nstrongest benefit and a caption — not just a logo or a raw UI dump. Assume the user\nonly ever sees the first two or three.\n\n---\n\n## 6. Ratings & reviews (be precise — and honest)\n\n- **Ratings and reviews ARE a ranking signal on Apple** (Apple lists them under\n  user behavior). Both **volume** and **average score** matter, so a steady flow of\n  4–5★ ratings helps discovery, not just trust.\n- **Prompt at a moment of genuine delight** — right after the user completes a win\n  in your app — never on first launch or mid-task. iOS limits how many times you may\n  show the system rating prompt per year, so spend those prompts wisely.\n- **Replying to reviews** builds trust and can lift your rating over time by\n  recovering unhappy users — but **the reply itself is not a separate ranking\n  lever**. Don't treat review replies (or paid ads) as an organic-ranking shortcut.\n\n---\n\n## 7. Localization — an underused multiplier\n\n- Translate the **metadata, not just the app**. A localized listing converts far\n  better in-market.\n- On Apple, **extra localizations give you extra keyword sets** — even English\n  variants (en-US, en-GB, en-AU) are separate slots, effectively **multiplying your\n  keyword coverage**. Use them.\n- **Research each market's real search terms**; don't machine-translate keywords —\n  the literal translation is often not what locals actually type.\n\n---\n\n## 8. Golden tips (the shortlist)\n\n1. On Apple, **every keyword-field character should be a brand-new term** — cut\n   your app name, category, plurals, generics, and filler; Apple already has those.\n2. **Don't repeat a word** across title + subtitle + keyword field. Apple indexes\n   each word once; spread distinct terms to widen coverage.\n3. **Let Apple build phrases for you** — list single comma-separated words instead\n   of spelled-out phrases to fit more terms.\n4. On Google, **put keywords in the title + short description**, then **2–3 natural\n   mentions** in the description. Never a keyword list.\n5. **Front-load** the first 1–3 screenshots and the first two lines of copy — that's\n   all most users ever see. Lead with the strongest benefit.\n6. Make the **subtitle / short description a benefit + a keyword**, never a slogan —\n   it's both indexed and the first thing read.\n7. **Win winnable terms first** (top-5 on mid-volume) and ladder up; don't camp at\n   #40 on a giant.\n8. **Ask for ratings at peak delight**, sparingly — ratings volume + score are a\n   real ranking signal.\n9. **Localize keywords per market** and use Apple's extra localization slots to\n   multiply coverage — research real terms, don't translate them.\n10. **Refresh promotional text (Apple) and \"What's New\"** for seasons/launches\n    without a full release — cheap, fast conversion levers that keep the listing alive.\n\n---\n\n## 9. Common mistakes to flag\n\n- Brand-only title for an unknown app (wastes the strongest keyword slot).\n- Subtitle/short description that repeats the title's words or is a vague slogan.\n- Apple keyword field padded with the app name, category, plurals, generics, filler.\n- Google description that's a keyword list instead of readable, benefit-led copy.\n- Screenshots that are raw UI with no captions/benefit messaging.\n- No app preview / video where the product is easy to demo.\n- Rating < 4.0 left unaddressed; no review replies on recurring complaints.\n- Listing not updated in months; no localization beyond the home market.\n- Chasing giant head terms the app can't rank for while ignoring winnable ones.\n\n---\n\n## 10. What to fix first (prioritization)\n\n1. **Title + subtitle / short description** — highest-leverage indexed text.\n2. **Keyword coverage** — Apple keyword field / Google description keywords.\n3. **First 1–3 screenshots** — the conversion make-or-break.\n4. **Ratings prompting** — get the volume + score flywheel turning.\n5. **Localization** — expand coverage market by market.\n6. **Iterate** — change one lever at a time and watch the result.\n\n---\n\n## Switch to real data when you want YOUR numbers\n\nThis skill is general guidance. For **your app specifically** — where you actually\nrank, real search volume & difficulty, which keywords to target, competitor gaps,\nyour ASO score, and review sentiment — use the data skills (they need an ASOScan\nAPI key):\n\n- **keyword-intelligence** — your real rank, volume, difficulty, trends.\n- **keyword-opportunities** — real keywords to target next.\n- **keyword-spy** — every keyword you (or a tracked competitor) rank for.\n- **competitor-analysis** — how you stack up, category + rating trajectory.\n- **metadata-audit** — your ASO score + specific, in-limit copy fixes.\n- **review-insights** — what your users actually say.\n\n## Honesty\n\nPresent ASO as it is: ratings/reviews and installs influence ranking, but **review\nreplies and paid ads are not organic-ranking shortcuts**; never promise a specific\nrank; never fabricate reviews or claims. Recommend the outcome (visibility, clarity,\nconversion), not a mechanism.\n\n## Sources (official)\n\n- Apple — App information & limits: <https://developer.apple.com/help/app-store-connect/reference/app-information/app-information/>\n- Apple — How App Store search works + keyword tips: <https://developer.apple.com/app-store/search/>\n- Apple — Product page assets (screenshots, previews, CPP): <https://developer.apple.com/app-store/product-page/>\n- Google — Store listing best practices: <https://support.google.com/googleplay/android-developer/answer/13393723>\n- Google — Preview assets (icon, feature graphic, screenshots, video): <https://support.google.com/googleplay/android-developer/answer/9866151>\n"
}