ASO Audit
by appeeky / aso-skills
Use it when you want a full ASO health audit, review your App Store listing quality, or diagnose why your app isn't ranking.
Packs the highest-opportunity terms into an iOS app's 100-character keyword field per locale, without repeating words already in the title or subtitle.
Listed ·Updated
AGENT ROLE: Autonomous iOS metadata optimizer. Tokenize the listing, remove indexing waste, pack the 100-char keyword field per locale without cross-field or cross-localization duplication, and emit the JSON in references/output.schema.json.
Maximize the number of unique indexable words (and the search-phrase combinations Apple forms from them) across an app's title, subtitle, and hidden keyword field, for each localization, subject to the hard 100-character keyword-field limit and Apple's indexing rules (stop words ignored, duplicates wasted, words auto-combined across fields and localizations serving the same storefront).
metadata (REQUIRED): local JSON with app_id and locales[], each {locale, priority, title, subtitle, current_keywords, candidates[]}; every candidate is {term, volume?, difficulty?}.volumes (OPTIONAL via --volumes): a CSV exported from your ASO tool with a term column (term/keyword/search term/query), a volume column (volume/search volume/popularity/search popularity/traffic) and, optionally, a difficulty column (difficulty/keyword difficulty/kd/competition). It fills volume and difficulty for candidates that lack them; values in metadata win.--metadata, with zero network calls.--volumes. A search popularity score (such as Apple's 1 to 100 scale shown in Apple Ads) works as the volume column; the ranking only needs relative values.scripts/keyword_field_optimizer.py --metadata listing.json [--volumes volumes.csv].STEP 1 — TOKENIZE each locale's title + subtitle into a covered set (lowercase, non-alphanumeric split, naive singularization, stop words removed). These words are already indexed; repeating them anywhere is waste.
STEP 2 — BUILD the candidate token pool from candidates[] plus the current keyword field (so existing terms are not silently lost), filling a missing volume/difficulty from --volumes (matched on the whole term, case-insensitive). Assign each token the best opportunity = volume / (difficulty + 10) of any term it appears in; unknown-volume tokens keep opportunity=null.
STEP 3 — RANK tokens by opportunity desc, then first-seen order.
STEP 4 — PACK per locale in priority order (1 first). For each ranked token DROP it with a reason IF it is a stop word (stopword), already in title/subtitle (in_title_subtitle), or already placed in an earlier locale (duplicate_across_locale); ELSE place it IF len(field) + len(token) + 1 ≤ 100, joining with commas and NO spaces; ELSE DROP over_budget.
STEP 5 — DEDUPE across localizations via a shared placed-set, so the second and third localizations extend coverage instead of repeating it.
STEP 6 — PROJECT coverage: indexable = covered ∪ placed; estimate combinations as n + C(n,2) (unigrams + unordered bigrams); report per-locale and listing-wide combinations_gained.
--metadata or --volumes file STOPs error.code="INPUT_MISSING"/"INPUT_INVALID"; a --volumes file without a term and a numeric volume column STOPs INPUT_INVALID and names the accepted column names.metadata or --volumes) THEN status="insufficient": tokens are still packed, but by input order, and a warning states ranking is not opportunity-driven. NEVER invent volumes.brand_tokens_excluded and never placed into the keyword field (already indexed by the title).One JSON object per references/output.schema.json. No prose.
scripts/keyword_field_optimizer.py — tokenizer, cross-field/locale dedupe, greedy 100-char packer, coverage projection.references/output.schema.json — output contract.Not using the CLI? Copy the SKILL.md and paste it straight into ChatGPT, Claude, or any agent.