Update to ASOScan App Store Optimization

{
  "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.",
  "included_files": [],
  "name": "metadata-audit",
  "skill_md_contents": "---\nname: metadata-audit\ndescription: 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.\nmetadata:\n  version: 1.3.1\n---\n\n# Metadata Audit\n\nScore the listing with ASOScan's ASO score, find the gaps, and draft better copy —\nspecific, within limits, and honest.\n\n## When to use\n\n- \"Audit / optimize my app listing.\" · \"What's my ASO score and how do I raise it?\"\n- \"Rewrite my title / subtitle / description.\" · \"What metadata changed recently?\"\n\n## Getting the data (two modes)\n\nPick the first mode that applies, then follow the steps below.\n\n1. **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.\n2. **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.\n3. **Neither**: hand off to **asoscan-setup**. It explains how to connect ASOScan in ChatGPT or Claude, or how to create an API key.\n\nASOScan 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.\n\n| Step | Tool (connected) | API call (key) | API credits |\n|---|---|---|---|\n| Find the app | `list_my_apps` | `GET /apps` | 1 |\n| ASO score | `get_aso_score` | `GET /apps/{id}/aso-score?country=` | 1 |\n| ASOScan recommendations | `get_aso_recommendations` | `GET /apps/{id}/recommendations` | 1 |\n| Current listing text | `get_listing_metadata` | `GET /apps/{id}/metadata?country=` | 1 |\n| Change history | `get_metadata_changelog` | `GET /apps/{id}/metadata/changelog?country=` | 1 |\n| Saved drafts for other languages | `list_localized_drafts` | `GET /apps/{id}/localizations/drafts` | 1 |\n| Draft listing text for another language (AI) | `draft_localized_metadata` | `POST /apps/{id}/localizations/{locale}/draft` | 2 + 1 AI credit, say the cost first |\n\n## Steps\n\n1. **Find the app** — `GET /apps` → note the `id` and `platform` (Apple vs Google —\n   the rules differ).\n2. **ASO score (authoritative)** — `GET /apps/{id}/aso-score?country=` (1 credit) →\n   `{ overall, metadata, ratings, conversion, conversionIsProxy, grade, platform,\n   recommendations[]{ category, severity, title, description } }` (0–100; severity\n   `critical|warning|info`). **Use this as the headline number; don't invent one.**\n3. **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.\n4. **Current metadata**: `GET /apps/{id}/metadata?country=` (1 credit) →\n   `{ title, subtitle, promotionalText, keywords, shortDescription, description,\n   whatsNew, releaseDate }`. A **404** = nothing captured yet.\n5. **Change history**: `GET /apps/{id}/metadata/changelog?country=` (1 credit) →\n   `[{ field, oldValue, newValue, changedAt, oldVersion, newVersion }]`.\n6. **Target keywords**: pull winners from **keyword-opportunities** / **keyword-intelligence**.\n\n## Platform rules to enforce (Apple/Google official, current)\n\n**Apple** — indexed search text = Title + Subtitle + hidden Keyword field (+ primary category):\n\n- Title **30 chars**, Subtitle **30 chars**, Keyword field **100 characters**\n  (non-Latin scripts consume it faster).\n- Keyword field: **commas between terms** (a space is allowed *within* a phrase but\n  costs a character — most list single words and let Apple recombine them across\n  name + subtitle + keywords).\n- **Don't repeat** a word already in Title/Subtitle/**category**; skip **plurals**\n  of included words, **generic** terms (`app`, `game`), **filler** (`the`, `to`),\n  and competitor/trademarked terms.\n- Long **description is NOT indexed** for Apple search — optimize it for conversion.\n  Promotional text (170 chars) isn't a search signal (but updates anytime, no release).\n- Screenshots: the first **1–3** appear in search results.\n\n**Google** — indexed search text = Title + Short description + Full description:\n\n- Title **30 chars**, Short description **80 chars**, Full description **4,000 chars**\n  and it **is indexed** — weave keywords in naturally (Google penalizes stuffing).\n- **Title bans:** emojis, ALL CAPS, \"best/#1/free\", CTAs.\n- Screenshots: up to **8** per device type.\n\nIf a limit is decision-critical, verify against Apple's/Google's official docs first.\n\n## The audit\n\nUse ASOScan's `overall` + pillar scores as the quantitative backbone; weight your\nemphasis toward the lowest pillar. Grade Title/Subtitle, Description, Keywords,\nRatings, Conversion (`conversionIsProxy: true` = estimated until store analytics are\nconnected), and Freshness.\n\n**Always print a score with its denominator.** `overall` is out of **100**;\n`metadata`, `ratings` and `conversion` are each out of **25**. A bare \"metadata 25\"\nreads as a failing grade when it is in fact a perfect one.\n\n**Know what the pillars measure.** `metadata` scores **completeness and limit\ncompliance** — is each indexed field present, and does it use a sensible share of its\ncharacter budget. It does **not** judge whether the copy is any good: nothing checks that\nthe title carries a term users search, or that the subtitle states a benefit rather than a\nslogan. `conversion` is the same shape — it counts assets like screenshots and cannot see\nwhat is in them. So **never tell the user a 25/25 means their copy is optimal**; say the\nfields are complete and in-limit, then do the quality read yourself in the field-by-field\nsection below. That judgement is the value you add on top of the score.\n\n## Output template\n\n```\n### Metadata audit — {App} · {platform} ({country})   ·  credits left: {remaining}\n\n**ASO score: {overall}/100 ({grade})**  (metadata {metadata}/25 · ratings {ratings}/25 · conversion {conversion}/25)\n\n**Top 3 quick wins (<1h):** 1) {exact new text + char count}  2) …\n\n**Field-by-field**\n- **Title** ({used}/30): \"{current}\" → \"{new}\" ({N} chars) — {why}\n- **Subtitle/Short** ({used}/{30|80}): \"{current}\" → \"{new}\" — {why}\n- **Keywords** (Apple, {used}/100): \"{current}\" → \"{new}\" — no dupes vs title/subtitle\n- **Description / What's new:** {fix}\n\n**ASOScan recommendations:** {surface each by severity}\n```\n\nEvery suggestion must be concrete (exact text + char count) and tied to a real\nkeyword or conversion reason. Point the user back to ASOScan to re-score after edits.\n\n## Listing text for another language\n\nUse this when the user wants their listing in another language or country.\n\n1. Read the saved drafts first. If one exists for that locale, show it before writing a new one.\n2. Tell the user a new draft costs 2 API credits and 1 AI credit, then call it with the store locale (for example `de-DE`, `fr-FR`, `es-ES`).\n3. If the answer says ASOScan is preparing the keyword data for that market, nothing was charged. Tell the user to ask again in a minute. Use `force` (the tool's `force` input, or `?force=true`) only when the last \"preparing\" answer is several minutes old.\n4. Show each variant with its character counts against the platform limits above. The draft is saved in ASOScan. ASOScan does not publish listing text to the stores; the user copies it into App Store Connect or Google Play Console.\n\nDescribe the benefit only as Apple documents it: localized name, subtitle and keywords are searchable in every storefront that supports that language, so more people can find the app. Never say a translation raises keyword rank.\n\n## Errors, credits & honesty\n\n- `401` → asoscan-setup · `403` no API access · `402` out of credits · `404` no\n  metadata yet · `503` not enabled yet. Each read = 1 credit.\n- No invented claims/awards/\"#1\" superlatives (also banned in Google titles).\n  Respect limits exactly. Recommend the outcome, not a guaranteed rank.\n- Full reference: <https://asoscan.com/api/developers>\n\n## Related\n\n- **keyword-opportunities** / **keyword-intelligence** — choose the keywords to target.\n- **competitor-analysis** — benchmark against rivals.\n- **review-insights** — turn recurring confusion into clearer copy.\n"
}