• The project is a mobile app (iOS/Android or both)
• You have access to the app's source code or metadata files
• You can read project configuration files (build.gradle, Info.plist, etc.)
• You can create/update metadata files in the project directory
• You have write access to create files

Phase 1: Analysis
  ↓ (analyzer agent)
  ↓
Phase 2: Plan Writing
  ↓ (plan-writer agent)
  ↓
Phase 3: Compliance Checking
  ↓ (compliance-checker agent)
  ↓
[User Approval Gate] ← Main agent orchestrates
  ↓
Phase 4: Execution
  ↓ (executor agent)
  ↓
Phase 5-6: Review + Best-Practices Verification
  ↓ (reviewer agent)
  ↓
Phase 7: Summarize
  ↓ (main agent)
  ↓
Final Output: ASO Summary Report + Updated Metadata Files

1. agents/analyzer.md

   — Reads codebase + metadata files, produces Phase 1 analysis report

2. agents/plan-writer.md

   — Generates ASO plan (keywords, metadata, visuals, localization)

3. agents/compliance-checker.md

   — Verifies all metadata against prohibited keywords/trademark rules

4. agents/executor.md

   — Implements approved metadata changes into project files

5. agents/reviewer.md

   — Runs Phase 5 review checklist + Phase 6 best-practices verification

1. Read

   references/aso_best_practices.md

   for the complete ASO knowledge base covering both stores — especially the "Store Policy Compliance" section which details prohibited keywords, trademark rules, and listing policy restrictions for both Apple and Google.
2. Determine which store(s) the user wants to optimize for (App Store, Google Play, or both).
3. Identify whether the user has existing metadata files, a live store listing, or is launching fresh.

• Read README, package.json, build.gradle, Podfile, Info.plist, AndroidManifest.xml, or any project config files
• Identify the app's core features, target audience, and value proposition
• Detect the app's category, supported platforms (iOS/Android/both), and supported languages
• Look for existing metadata directories (

  metadata/

  ,

  fastlane/

  ,

  supply/

  , or custom paths)

• App Store (iOS): Check

  metadata/app-info/{locale}.json

  and

  metadata/version/{version}/{locale}.json

  for name, subtitle, keywords, description, whatsNew, promotionalText
• Google Play (Android): Check

  fastlane/metadata/android/{locale}/

  or

  supply/metadata/

  for title.txt, short_description.txt, full_description.txt, changelogs/
• Audit each field for character limit compliance, keyword utilization, and quality

asc-aso-audit

• Note their app name, subtitle/short description, and apparent keyword strategy
• Identify what makes them rank well (keywords in title, strong ratings, etc.)
• Look for gaps — keywords they miss that the user's app could target

• Current keyword rankings (from ASO tools, App Store Connect analytics, or Google Play Console)
• Download/install numbers and trends
• Ratings and review sentiment
• Conversion rate (impressions → installs)

• App Name: [name]
• Platforms: [iOS / Android / Both]
• Category: [category]
• Core Value Proposition: [1-2 sentences]
• Target Audience: [demographics/use cases]

1. [Finding 1 — most impactful]
2. [Finding 2]
3. ...

1. [Opportunity 1 — highest potential impact]
2. [Opportunity 2]
3. ...

---

• Primary: [e.g., "Increase organic installs by improving search visibility for [category] keywords"]
• Secondary: [e.g., "Improve conversion rate from listing page views to installs"]

• Current: "[current]"
• Proposed: "[proposed]"
• Rationale: [why this change improves discoverability]

• Current: "[current]"
• Proposed: "[proposed]"
• Rationale: [keyword + conversion reasoning]

• Current: "[current]"
• Proposed: "[proposed]"
• Characters used: [X/100]
• Cross-field combinations enabled: [list key search queries this enables]

• Key changes: [what to add/remove/restructure]
• Keyword integration points: [where keywords appear naturally]
• Conversion optimization: [how the description drives installs]

• Strategy: [how to leverage release notes for engagement]

• App Icon: [assessment and suggestions]
• Screenshots: [ordering, messaging, keyword captions]
• Preview Video: [if applicable — recommendation]

• Priority markets: [ranked by opportunity]
• Localization approach per market: [translate vs. localize vs. transcreate]

• Current rating: [X.X]
• Target rating: [X.X]
• Actions: [in-app review prompt timing, response strategy]

• Pricing terms: "free", "sale", "discount", "limited time"
• Superlative claims: "best", "#1", "top-rated", "must-have", "top app", "#1 in the world"
• Reserved terms: "For Kids", "For Children" (unless Kids Category), "Editor's Choice"
• Platform references: "Android", "Google Play", "Play Store"
• Call-to-action phrases: "download now", "install now", "try now"

• Performance claims: "top", "best", "#1", "number one", "popular"
• Pricing terms: "free", "no ads", "ad free"
• Promotional terms: "new", "hot", "first", "bonus", "discount", "sale", "million downloads"
• Ranking claims: "App of the Year", "Best Google Play App of [year]"
• Call-to-action: "download now", "install now", "play now", "try now", "update now"

• Competitor brand names — Any mention of competitor app names (e.g., "WhatsApp", "Instagram", "Nike Training Club") must be removed from title, subtitle, keywords, and descriptions
• Trademarked terms — Any trademarked term the user doesn't own or have a license for must be flagged
• Celebrity names — Unless explicitly authorized
• Apple/Google trademarks — Cannot suggest endorsement (e.g., "Featured by Apple", "Google's Choice")

• No emojis or special characters in title/subtitle (both stores)
• No ALL CAPS in title/subtitle unless it's the registered brand name
• No repeated special characters
• Title within character limits (30 chars both stores)
• No unattributed user testimonials or fake reviews in metadata
• No graphic elements in icon suggesting store rankings (Google Play)

• No unverifiable claims ("fastest", "most popular", "award-winning" without evidence)
• Description accurately reflects app features — no features the app doesn't have
• Screenshots show the actual app in use (not just marketing art)
• In-app purchases and subscriptions clearly disclosed
• No misleading descriptions of app functionality

• or [ ] for each formatting rule

• or [ ] for each accuracy rule

"Here's the ASO plan based on my analysis. All proposed metadata has been validated against Apple App Store and Google Play Store listing policies — no prohibited keywords, trademark violations, or policy issues found.

Please review each section. Let me know:

1. Which recommendations you approve
2. Which you'd like to modify
3. Any you want to skip
4. Any additional ideas to include

I'll revise the plan based on your feedback before executing anything."

• Update

  metadata/app-info/{locale}.json

  for name, subtitle
• Update

  metadata/version/{version}/{locale}.json

  for keywords, description, whatsNew, promotionalText
• Validate character limits after each edit
• Cross-check keywords field: no duplicates with title/subtitle, no spaces after commas, single words preferred

• Update

  title.txt

  (max 30 chars)
• Update

  short_description.txt

  (max 80 chars)
• Update

  full_description.txt

  (max 4,000 chars) — integrate keywords naturally, avoid stuffing
• Update changelogs if applicable

• Create the appropriate directory structure
• Write the optimized metadata files
• Provide instructions for how to upload/sync with the store

• Never use prohibited terms — check every keyword against the banned words lists in

  references/aso_best_practices.md

  → "Store Policy Compliance" section
• Never use competitor brand names or trademarks — even in the hidden iOS keywords field, Apple monitors and de-indexes trademarked terms
• Never use unverifiable superlatives — "best", "#1", "top-rated" are banned on both stores
• Never use pricing/promotional language — "free", "sale", "discount" trigger rejection
• If unsure whether a term is trademarked, err on the side of caution and use a generic alternative

• Keywords field: comma-separated, no spaces after commas
• Never duplicate words from title or subtitle in keywords
• Prefer single words over phrases (enables cross-field combinations)
• Aim for 90%+ character utilization (90+ of 100 chars)
• Consider cross-field search queries: word in subtitle + word in keywords = matched search
• Do not include competitor app names in the keywords field — Apple actively monitors and can silently de-index or reject

• Keywords go naturally into title, short description, and full description
• No separate keyword field — Google indexes all text fields
• Repeat important keywords 3-5 times across fields (not stuffing, natural usage)
• Long description should cover related concepts and use cases
• Google's algorithm detects keyword stuffing — prioritize readability
• Do not embed competitor brand names anywhere in metadata — trademark owners can file complaints leading to app removal

• First 1-3 lines are critical — this is what users see before "Read More"
• Lead with the strongest value proposition and a clear call-to-action
• Use bullet points or short paragraphs for scannability
• Naturally integrate target keywords without forcing them
• Include social proof (awards, press mentions, user count) if available
• End with a clear reason to download now

• Research locale-specific keywords (not just translations of English keywords)
• Adapt the messaging to local culture and usage patterns
• Verify character limits in the target language (some languages are more verbose)
• If the

  asc-localize-metadata

  skill is available, recommend it for bulk translation workflows

• Screenshots: Recommend ordering (lead with the strongest feature), caption text with keywords (OCR-indexed on App Store since June 2025), and visual hierarchy
• App Icon: Assess current icon for clarity at small sizes, color contrast, and category conventions
• Preview Video: Recommend whether one is needed and what to show in the first 3 seconds

• All metadata fields within character limits
• No keyword duplication across indexed fields (iOS)
• Keywords field properly formatted (commas, no spaces)
• Descriptions read naturally with keywords integrated
• No spelling or grammar errors in any locale
• Cross-field keyword combinations produce intended search queries
• Visual asset recommendations are specific and actionable
• Localized metadata is genuinely localized (not just translated)
• No sensitive or brand-risky terms introduced
• No prohibited keywords — re-scan all fields for banned terms (see Phase 3)
• No competitor trademarks — verify no competitor brand names leaked into any metadata field
• No unverifiable claims — no superlatives without evidence ("fastest", "best", "#1")
• No platform references — no "Android"/"Google Play" in iOS metadata or vice versa
• No formatting violations — no emojis, ALL CAPS (unless brand name), or special characters in titles
• Accurate feature descriptions — every claimed feature exists in the app

• Field utilization percentages improved
• Keyword coverage expanded
• No new issues introduced

references/aso_best_practices.md

• Title/name includes primary keyword
• Subtitle/short description includes secondary keyword and value prop
• Keywords field maximizes character budget (iOS)
• Description is conversion-optimized with keyword integration
• Localization is market-aware, not just translated
• Visual assets support conversion
• Rating/review strategy addressed
• Ongoing optimization recommendations provided
• All metadata passes Store Policy Compliance rules (see "Store Policy Compliance" section in best practices)
• No trademark violations — final check that no competitor or third-party trademarks appear in any metadata
• No prohibited keywords — final scan against the prohibited terms lists for both stores

• Total unique keywords targeted: [X]
• Primary keywords: [list]
• Cross-field combinations enabled: [list key search queries]
• Keyword field utilization: [X/100 chars (Y%)]

• Prohibited keyword check: PASS — no banned terms in any metadata field
• Trademark check: PASS — no competitor or third-party trademarks used
• Formatting check: PASS — no emojis, ALL CAPS, or special characters in titles
• Content accuracy check: PASS — all features described exist in the app
• Overall compliance: PASS for [App Store / Google Play / Both]

• [Outcome 1: e.g., "Improved visibility for [keyword] searches"]
• [Outcome 2: e.g., "Higher conversion rate from improved first-impression copy"]

1. Upload metadata to the store(s) — [specific instructions]
2. Monitor rankings for target keywords after 1-2 weeks
3. A/B test screenshots and descriptions (use Custom Product Pages on iOS or Store Listing Experiments on Google Play)
4. Re-run this skill in 4-6 weeks to iterate based on performance data

• [list all files created or modified with paths]

---

• App Name: FocusFlow – Deep Work Timer
• Platforms: iOS, Android
• Category: Productivity
• Core Value Proposition: Distraction-free Pomodoro-style focus sessions with team accountability
• Target Audience: Knowledge workers, students, remote teams

• Prohibited keyword check: PASS — no banned terms in any metadata field
• Trademark check: PASS — no competitor or third-party trademarks used
• Overall compliance: PASS for App Store + Google Play

---

• No local metadata files — The app has no

  metadata/

  ,

  fastlane/

  , or equivalent directory. The skill creates the canonical directory structure and writes optimized files from scratch, then provides upload instructions for each store.
• Single-platform app — User wants to optimize only the App Store or only Google Play. Skip all phases and checks for the irrelevant store. Do not propose a keywords field for Android (it has none).
• No competitor access — User cannot name competitors or has no market data. Skip Phase 1.3; base keyword strategy on app features alone. Flag this gap in the analysis report.
• Unverifiable keyword volume data — No ASO tool is available. Proceed with heuristic priority (feature-specific terms over generic terms, long-tail phrases over head terms) and note the limitation.
• Pre-launch app — No live listing, no existing downloads or ratings data. Skip all performance-baseline steps; focus on metadata creation and visual guidance only.
• Metadata policy violation in proposed plan — The compliance check (Phase 3) catches a prohibited keyword in the draft. The skill revises the plan silently, replaces the violation, re-runs the compliance check, and only presents the corrected plan to the user.
• Non-English primary locale — If the app's main locale is not

  en-US

  , adapt all metadata templates, character limits, and keyword strategies to the target language. Note that some languages require more characters to express the same concept.
• User rejects the plan — Do not execute. Iterate on the plan in Phase 2, incorporating the user's feedback, then re-run the Phase 3 compliance check before presenting the revised plan.

• Description ≤40 words with imperative verb — The skill frontmatter description passes the asm eval description check.
• Analysis report produced — Phase 1 output includes App Overview, Current Metadata Status table, and Key Findings.
• ASO plan covers all required fields — Plan includes title, subtitle/short description, keywords (iOS), full description, and visual asset recommendations for each targeted store.
• Compliance check ran and passed — Phase 3 compliance report is present and shows PASS overall status before any plan is presented to the user.
• User approval gate respected — Phase 4 execution does not begin until the user explicitly approves the plan.
• All metadata fields within character limits — Title ≤30, subtitle ≤30, iOS keywords ≤100, Android short description ≤80, full description ≤4000. No truncation.
• No prohibited keywords in any output metadata — Final scan finds zero banned terms (no "free", "best", "#1", competitor names, etc.) in any field.
• No trademark violations — No competitor brand names appear in any proposed metadata field.
• iOS keywords field has no duplicates with title/subtitle — The keyword field does not repeat words already in the title or subtitle.
• Metadata files written — At least one metadata file (or the correct directory structure) exists on disk after Phase 4.
• Summary report produced — Phase 7 output includes a Changes Made table, Metadata Comparison, Store Policy Compliance section, and Next Steps.

• Indexed fields: title, subtitle, keyword field (100 chars)
• Description is NOT indexed but affects conversion
• Screenshot captions are OCR-indexed (since June 2025)
• Custom Product Pages (CPPs) enable audience-specific listings
• Use

  asc

  CLI tools if available for metadata sync

• All text fields are indexed (title, short description, full description)
• No separate keyword field — keywords must be woven into text naturally
• Google detects and penalizes keyword stuffing
• Store Listing Experiments enable A/B testing
• Long description supports up to 4,000 chars — use them wisely
• Google considers app quality signals: crash rate, ANR rate, retention

• App ratings above 4.0 are critical for conversion (90% of featured apps are 4.0+)
• Regular updates signal to algorithms that the app is actively maintained
• Localization should be market-aware, not simple translation
• First 1-3 lines of description must hook the user before "Read More"

• asc-aso-audit

  — Detailed offline audit of iOS metadata (run before this skill for a deep keyword audit)

• asc-localize-metadata

  — Bulk localization of App Store metadata across all locales

• asc-metadata-sync

  — Sync local metadata files with App Store Connect

• asc-whats-new-writer

  — Generate engaging release notes with keyword reinforcement

• asc-shots-pipeline

  — Automated screenshot capture with keyword-optimized captions

• seo-ai-optimizer

  — If the app has a web presence, align ASO and SEO keyword strategies