ASO — App Store Optimization Skill
Consolidated Skill Routing
Use five public skills:
aso: full audit, orchestration, and strategy. For roadmap detail, read
../skills/aso-plan/GUIDE.md.aso-listing: keywords, metadata, localization, and seasonal changes.aso-creative: screenshots, video, conversion, and experiments.aso-market: reviews and competitors.aso-release: technical readiness, compliance, and launch.
The former specialist files are internal GUIDE.md references. They preserve
the detailed methods but do not appear as separate skills.
Comprehensive ASO analysis for iOS App Store and Google Play apps. Works in two modes:
- Local mode (default): Run
/aso audit inside an app project — auto-detects Fastlane metadata, Xcode project, or Gradle project and audits your pre-submission metadata.
- Remote mode: Run
/aso audit <app-id> with an app ID or store URL — fetches and audits the live listing. Also works for competitor apps.
Quick Reference
| Command |
What it does |
/aso audit |
Auto-detect local project and audit its metadata |
/aso audit <app-id> |
Audit a live listing by app ID or store URL |
/aso audit --compare <app-id> |
Audit local metadata AND compare against live listing |
/aso keywords <seeds> |
Keyword research — difficulty, volume, placement strategy |
/aso metadata |
Optimize local metadata (or /aso metadata <app-id> for remote) |
/aso visuals |
Analyze local screenshots (or /aso visuals <app-id> for remote) |
/aso reviews <app-id> |
Reviews — sentiment analysis, response templates, keyword extraction |
/aso competitors <app-id> |
Competitor analysis — keyword gaps, metadata comparison |
/aso localization |
Audit local locale coverage (or /aso localization <app-id>) |
/aso ab-testing <app-id> |
A/B testing — iOS PPO / Android experiment design |
/aso technical <app-id> |
Technical ASO — Android Vitals, app size, crashes, update cadence |
/aso conversion <app-id> |
Conversion — install rate benchmarking, first-impression audit |
/aso compliance |
Store policy check — validates metadata against Apple/Google guidelines |
/aso plan <category> |
Strategic plan — 4-phase roadmap with category templates |
/aso launch |
Launch — pre-launch checklist using local project state |
/aso seasonal <app-id> |
Seasonal — trending keyword opportunities, holiday calendar |
Auto-Detection (Local Mode)
When no app ID is provided, run project detection first:
uv run python scripts/detect_project.py --json
This scans the current directory for:
| Source |
What it detects |
Files checked |
| Fastlane iOS |
Store metadata per locale (name, subtitle, keywords, description) |
fastlane/metadata/{locale}/name.txt, subtitle.txt, keywords.txt, etc. |
| Fastlane Android |
Store metadata per locale (title, short/full description) |
fastlane/metadata/android/{locale}/title.txt, full_description.txt, etc. |
| Xcode project |
Bundle ID, app name |
*.xcodeproj/project.pbxproj, Info.plist |
| Gradle project |
Application ID, app name |
app/build.gradle, AndroidManifest.xml, res/values/strings.xml |
Priority: Fastlane metadata (richest data) > Xcode/Gradle (basic identifiers only).
If Fastlane metadata is found, all fields are available for validation, keyword analysis, and optimization. If only Xcode/Gradle is found, extract the app ID and optionally fetch the live listing for a full audit.
Remote Mode
When an app ID or URL is provided, fetch the live listing:
- iOS: Numeric ID (
id284882215), Apple App Store URL (apps.apple.com/...)
- Android: Package name (
com.whatsapp), Google Play URL (play.google.com/store/apps/details?id=...)
iOS: id284882215 OR https://apps.apple.com/app/id284882215
Android: com.whatsapp OR https://play.google.com/store/apps/details?id=com.whatsapp
Compare Mode
/aso audit --compare <app-id> audits BOTH local metadata and the live listing, then shows:
- Fields that differ between local and live
- Whether local changes would improve or regress the score
- Pre-submission validation of pending metadata changes
Category Detection
After fetching listing data, classify the app:
- Gaming: game category, IAP patterns, leaderboards
- SaaS/Productivity: subscription model, enterprise features, workspace tools
- Health/Fitness: HealthKit/Google Fit, workout terms, wellness
- E-commerce: shopping category, payment, cart, product catalog
- Social: messaging, feed, connections, sharing
- Fintech: banking, payments, investment, crypto
- Other: education, travel, utilities, news, entertainment
Category informs which plan templates and benchmarks to apply.
Audit Orchestration Flow
When running /aso audit <app-id>:
Step 1 — Data Fetch (sequential)
uv run python scripts/fetch_listing.py <app-id> --country us --json
Parse the result to get structured listing data.
Step 2 — Category Detection (sequential)
Classify app from listing metadata. Load category-specific benchmarks.
Step 3 — Parallel Subagent Dispatch
Run all applicable specialists in parallel when the harness supports
delegation. Otherwise, load the corresponding specialist skills and run them
sequentially. Do not continue to scoring until all applicable results return.
| Agent |
Focus |
aso-keywords |
Keyword coverage in current metadata |
aso-metadata |
Field quality, char limits, keyword placement |
aso-visuals |
Screenshot count, narrative, icon, video |
aso-reviews |
Sentiment distribution, themes, response rate |
aso-competitors |
Top 5 competitor comparison |
aso-technical |
App size, update recency, stability signals |
aso-conversion |
First-impression elements, CRO signals |
aso-localization |
(conditional: if multi-locale detected) |
Each agent receives the parsed listing JSON and returns a structured report with scores and findings.
Step 3.5 — Compliance Validation (sequential)
After all specialists return, run aso-compliance with:
- The original listing metadata.
- All proposed metadata, keyword, visual, and conversion changes.
Remove any recommendation that violates an Apple or Google policy. Replace it
with a compliant alternative when possible. A policy violation is always a
Critical action item, independent of its numeric score.
Step 4 — Score Aggregation (sequential)
Calculate weighted ASO Health Score (0-100):
| Category |
Weight |
| Keyword Optimization |
20% |
| Metadata Quality |
15% |
| Visual Assets |
15% |
| Reviews & Ratings |
15% |
| Competitive Position |
10% |
| Technical Health |
10% |
| Conversion Signals |
10% |
| Policy Compliance |
5% |
Step 5 — Report Generation (sequential)
Generate two files:
ASO-AUDIT-REPORT.md:
- Executive summary (score, platform, category, top 3 issues, quick wins)
- Per-category detailed findings, including policy compliance
- Platform-specific notes
ASO-ACTION-PLAN.md:
- Critical: Character limit violations, missing keywords in title, <3.5 star rating
- High: Poor screenshot narrative, no preview video, low review velocity
- Medium: Localization gaps, A/B test opportunities, secondary keyword misses
- Low: Seasonal optimization, minor copy improvements, icon A/B test
End with a short user summary of no more than 40 lines. Include the score,
platform, category, category breakdown, exactly three top issues, three to five
quick wins, and paths to both report files. Use only these status words:
Excellent, Good, Needs Work, Poor, Critical.
Quality Gates
These rules are ALWAYS enforced — never recommend violations:
- Character limits are absolute — violations are always Critical priority
- iOS description is NOT indexed — never optimize it for keywords, only conversion
- iOS keyword field: comma-separated, no spaces after commas, no duplication with title/subtitle
- Android description: primary keyword in first sentence, 2-3% density for primary keyword
- No keyword stuffing: >3 repetitions of same keyword in any field = stuffing
- Review health: <3.5 stars = Critical, <4.0 = High priority
- Update recency: >90 days since last update = warning signal
Platform Metadata Quick Reference
iOS App Store
| Field |
Limit |
Indexed? |
Notes |
| App Name |
30 chars |
YES (high weight) |
Primary keyword here |
| Subtitle |
30 chars |
YES |
Secondary keywords |
| Keywords |
100 chars |
YES |
Hidden, comma-separated |
| Description |
4,000 chars |
NO |
Conversion copy only |
| Promotional Text |
170 chars |
NO |
No review needed to update |
| What's New |
4,000 chars |
NO |
Update messaging |
Google Play
| Field |
Limit |
Indexed? |
Notes |
| Title |
30 chars |
YES (high weight) |
Treat every character as premium space |
| Short Description |
80 chars |
YES |
Visible in some views |
| Full Description |
4,000 chars |
YES |
Keyword density matters |
| Developer Name |
variable |
YES (low) |
Branding |
| What's New |
500 chars |
NO |
Shorter than iOS |
Capability Fallbacks
- If delegation is unavailable, run specialist instructions sequentially.
- If browser or network access is unavailable, use local metadata and mark live
listing, review, and competitor evidence as unavailable.
- If an app cannot be found, report the accepted identifier formats.
- If data is partial, score only supported categories and label the result
partial. Do not infer missing evidence.
Reference Files
Load on demand from references/:
ios-metadata-specs.md — Full iOS field specs and indexing rulesandroid-metadata-specs.md — Full Android field specs and indexing ruleskeyword-placement-rules.md — Keyword weight by field position per platformvisual-asset-specs.md — Screenshot/icon/video dimensions per devicequality-gates.md — Thresholds, hard stops, density limitscategory-taxonomy.md — iOS/Android category IDs and mapping
1---2name: aso3description: Route or run comprehensive App Store Optimization work for iOS and Android. Use for full listing audits, multi-area ASO requests, or when the user does not name a more specific ASO task. Covers keyword research, metadata, visuals, reviews, competitors, localization, testing, technical health, compliance, conversion, launch planning, and seasonal optimization.4---56# ASO — App Store Optimization Skill78## Consolidated Skill Routing910Use five public skills:1112- `aso`: full audit, orchestration, and strategy. For roadmap detail, read13 `../skills/aso-plan/GUIDE.md`.14- `aso-listing`: keywords, metadata, localization, and seasonal changes.15- `aso-creative`: screenshots, video, conversion, and experiments.16- `aso-market`: reviews and competitors.17- `aso-release`: technical readiness, compliance, and launch.1819The former specialist files are internal `GUIDE.md` references. They preserve20the detailed methods but do not appear as separate skills.2122Comprehensive ASO analysis for iOS App Store and Google Play apps. Works in two modes:23241. **Local mode** (default): Run `/aso audit` inside an app project — auto-detects Fastlane metadata, Xcode project, or Gradle project and audits your pre-submission metadata.252. **Remote mode**: Run `/aso audit <app-id>` with an app ID or store URL — fetches and audits the live listing. Also works for competitor apps.2627## Quick Reference2829| Command | What it does |30|---------|-------------|31| `/aso audit` | Auto-detect local project and audit its metadata |32| `/aso audit <app-id>` | Audit a live listing by app ID or store URL |33| `/aso audit --compare <app-id>` | Audit local metadata AND compare against live listing |34| `/aso keywords <seeds>` | Keyword research — difficulty, volume, placement strategy |35| `/aso metadata` | Optimize local metadata (or `/aso metadata <app-id>` for remote) |36| `/aso visuals` | Analyze local screenshots (or `/aso visuals <app-id>` for remote) |37| `/aso reviews <app-id>` | Reviews — sentiment analysis, response templates, keyword extraction |38| `/aso competitors <app-id>` | Competitor analysis — keyword gaps, metadata comparison |39| `/aso localization` | Audit local locale coverage (or `/aso localization <app-id>`) |40| `/aso ab-testing <app-id>` | A/B testing — iOS PPO / Android experiment design |41| `/aso technical <app-id>` | Technical ASO — Android Vitals, app size, crashes, update cadence |42| `/aso conversion <app-id>` | Conversion — install rate benchmarking, first-impression audit |43| `/aso compliance` | Store policy check — validates metadata against Apple/Google guidelines |44| `/aso plan <category>` | Strategic plan — 4-phase roadmap with category templates |45| `/aso launch` | Launch — pre-launch checklist using local project state |46| `/aso seasonal <app-id>` | Seasonal — trending keyword opportunities, holiday calendar |4748## Auto-Detection (Local Mode)4950When no app ID is provided, run project detection first:51```bash52uv run python scripts/detect_project.py --json53```5455This scans the current directory for:5657| Source | What it detects | Files checked |58|--------|----------------|---------------|59| **Fastlane iOS** | Store metadata per locale (name, subtitle, keywords, description) | `fastlane/metadata/{locale}/name.txt`, `subtitle.txt`, `keywords.txt`, etc. |60| **Fastlane Android** | Store metadata per locale (title, short/full description) | `fastlane/metadata/android/{locale}/title.txt`, `full_description.txt`, etc. |61| **Xcode project** | Bundle ID, app name | `*.xcodeproj/project.pbxproj`, `Info.plist` |62| **Gradle project** | Application ID, app name | `app/build.gradle`, `AndroidManifest.xml`, `res/values/strings.xml` |6364Priority: Fastlane metadata (richest data) > Xcode/Gradle (basic identifiers only).6566If Fastlane metadata is found, all fields are available for validation, keyword analysis, and optimization. If only Xcode/Gradle is found, extract the app ID and optionally fetch the live listing for a full audit.6768## Remote Mode6970When an app ID or URL is provided, fetch the live listing:7172- **iOS**: Numeric ID (`id284882215`), Apple App Store URL (`apps.apple.com/...`)73- **Android**: Package name (`com.whatsapp`), Google Play URL (`play.google.com/store/apps/details?id=...`)7475```76iOS: id284882215 OR https://apps.apple.com/app/id28488221577Android: com.whatsapp OR https://play.google.com/store/apps/details?id=com.whatsapp78```7980## Compare Mode8182`/aso audit --compare <app-id>` audits BOTH local metadata and the live listing, then shows:83- Fields that differ between local and live84- Whether local changes would improve or regress the score85- Pre-submission validation of pending metadata changes8687## Category Detection8889After fetching listing data, classify the app:90- **Gaming**: game category, IAP patterns, leaderboards91- **SaaS/Productivity**: subscription model, enterprise features, workspace tools92- **Health/Fitness**: HealthKit/Google Fit, workout terms, wellness93- **E-commerce**: shopping category, payment, cart, product catalog94- **Social**: messaging, feed, connections, sharing95- **Fintech**: banking, payments, investment, crypto96- **Other**: education, travel, utilities, news, entertainment9798Category informs which plan templates and benchmarks to apply.99100## Audit Orchestration Flow101102When running `/aso audit <app-id>`:103104### Step 1 — Data Fetch (sequential)105```bash106uv run python scripts/fetch_listing.py <app-id> --country us --json107```108Parse the result to get structured listing data.109110### Step 2 — Category Detection (sequential)111Classify app from listing metadata. Load category-specific benchmarks.112113### Step 3 — Parallel Subagent Dispatch114Run all applicable specialists in parallel when the harness supports115delegation. Otherwise, load the corresponding specialist skills and run them116sequentially. Do not continue to scoring until all applicable results return.117118| Agent | Focus |119|-------|-------|120| `aso-keywords` | Keyword coverage in current metadata |121| `aso-metadata` | Field quality, char limits, keyword placement |122| `aso-visuals` | Screenshot count, narrative, icon, video |123| `aso-reviews` | Sentiment distribution, themes, response rate |124| `aso-competitors` | Top 5 competitor comparison |125| `aso-technical` | App size, update recency, stability signals |126| `aso-conversion` | First-impression elements, CRO signals |127| `aso-localization` | *(conditional: if multi-locale detected)* |128129Each agent receives the parsed listing JSON and returns a structured report with scores and findings.130131### Step 3.5 — Compliance Validation (sequential)132133After all specialists return, run `aso-compliance` with:1341351. The original listing metadata.1362. All proposed metadata, keyword, visual, and conversion changes.137138Remove any recommendation that violates an Apple or Google policy. Replace it139with a compliant alternative when possible. A policy violation is always a140Critical action item, independent of its numeric score.141142### Step 4 — Score Aggregation (sequential)143144Calculate weighted **ASO Health Score (0-100)**:145146| Category | Weight |147|----------|--------|148| Keyword Optimization | 20% |149| Metadata Quality | 15% |150| Visual Assets | 15% |151| Reviews & Ratings | 15% |152| Competitive Position | 10% |153| Technical Health | 10% |154| Conversion Signals | 10% |155| Policy Compliance | 5% |156157### Step 5 — Report Generation (sequential)158159Generate two files:160161**ASO-AUDIT-REPORT.md**:162- Executive summary (score, platform, category, top 3 issues, quick wins)163- Per-category detailed findings, including policy compliance164- Platform-specific notes165166**ASO-ACTION-PLAN.md**:167- **Critical**: Character limit violations, missing keywords in title, <3.5 star rating168- **High**: Poor screenshot narrative, no preview video, low review velocity169- **Medium**: Localization gaps, A/B test opportunities, secondary keyword misses170- **Low**: Seasonal optimization, minor copy improvements, icon A/B test171172End with a short user summary of no more than 40 lines. Include the score,173platform, category, category breakdown, exactly three top issues, three to five174quick wins, and paths to both report files. Use only these status words:175Excellent, Good, Needs Work, Poor, Critical.176177## Quality Gates178179These rules are ALWAYS enforced — never recommend violations:1801811. **Character limits are absolute** — violations are always Critical priority1822. **iOS description is NOT indexed** — never optimize it for keywords, only conversion1833. **iOS keyword field**: comma-separated, no spaces after commas, no duplication with title/subtitle1844. **Android description**: primary keyword in first sentence, 2-3% density for primary keyword1855. **No keyword stuffing**: >3 repetitions of same keyword in any field = stuffing1866. **Review health**: <3.5 stars = Critical, <4.0 = High priority1877. **Update recency**: >90 days since last update = warning signal188189## Platform Metadata Quick Reference190191### iOS App Store192193| Field | Limit | Indexed? | Notes |194|-------|-------|----------|-------|195| App Name | 30 chars | YES (high weight) | Primary keyword here |196| Subtitle | 30 chars | YES | Secondary keywords |197| Keywords | 100 chars | YES | Hidden, comma-separated |198| Description | 4,000 chars | NO | Conversion copy only |199| Promotional Text | 170 chars | NO | No review needed to update |200| What's New | 4,000 chars | NO | Update messaging |201202### Google Play203204| Field | Limit | Indexed? | Notes |205|-------|-------|----------|-------|206| Title | 30 chars | YES (high weight) | Treat every character as premium space |207| Short Description | 80 chars | YES | Visible in some views |208| Full Description | 4,000 chars | YES | Keyword density matters |209| Developer Name | variable | YES (low) | Branding |210| What's New | 500 chars | NO | Shorter than iOS |211212## Capability Fallbacks213214- If delegation is unavailable, run specialist instructions sequentially.215- If browser or network access is unavailable, use local metadata and mark live216 listing, review, and competitor evidence as unavailable.217- If an app cannot be found, report the accepted identifier formats.218- If data is partial, score only supported categories and label the result219 partial. Do not infer missing evidence.220221## Reference Files222223Load on demand from `references/`:224- `ios-metadata-specs.md` — Full iOS field specs and indexing rules225- `android-metadata-specs.md` — Full Android field specs and indexing rules226- `keyword-placement-rules.md` — Keyword weight by field position per platform227- `visual-asset-specs.md` — Screenshot/icon/video dimensions per device228- `quality-gates.md` — Thresholds, hard stops, density limits229- `category-taxonomy.md` — iOS/Android category IDs and mapping
FelixGraeber