ASO Marketing — Full-Lifecycle App Store Optimization

A comprehensive, iterative ASO workflow that takes a mobile app from analysis through planning, execution, verification, and reporting — covering both Apple App Store and Google Play Store.

Environment Check

Before running this skill, verify:

• 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

If any check fails, stop and ask for clarification.

Repo Sync Before Edits (mandatory)

Before creating, updating, or deleting files in an existing repository, sync the current branch with remote. Run the dry-run command first to preview, then confirm with the user before destructive sync.

# Dry-run preview first
git fetch --dry-run origin
git status

# Then sync (after user confirms working tree is clean or backed up)
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

If the working tree is not clean, ask the user before stashing. If origin is missing, pull is unavailable, or rebase/stash conflicts occur, stop and ask the user before continuing.

Backup-first rule for metadata files: Before overwriting any existing metadata file (e.g. metadata/version/1.0/en-US.json, fastlane/metadata/android/en-US/title.txt), create a .bak copy in the same directory or confirm the file is in version control. Never delete metadata files without explicit user confirmation.

Subagent Architecture

This skill uses a Staged Pipeline + Review Loop architecture. Each phase maps to a subagent in agents/:

1. agents/analyzer.md — Phase 1 analysis report
2. agents/plan-writer.md — Phase 2 ASO plan
3. agents/compliance-checker.md — Phase 3 prohibited-keyword + trademark check
4. agents/executor.md — Phase 4 metadata changes
5. agents/reviewer.md — Phases 5-6 review + best-practices verification

Main agent orchestrates phase transitions and the user approval gate after Phase 3.

Workflow Overview

The skill follows a 7-phase cycle. Never skip the policy compliance check or the planning approval gate — the user must approve a policy-compliant plan before execution begins.

Phase 1: Analyze → Phase 2: Plan → Phase 3: Policy Compliance Check
  → [User Approval Gate] → Phase 4: Execute → Phase 5: Review
  → Phase 6: Verify → Phase 7: Summarize

Before You Start

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

Phase Execution

Run each phase in order. Detailed instructions, templates, and checklists live in the reference files. Read each one before executing the corresponding phase.

Phase 1: Analyze

Read references/phases-1-2.md (Phase 1 section). Gather codebase info, audit existing store metadata, identify competitors, baseline performance, and produce an Analysis Report.

Phase 2: Plan

Read references/phases-1-2.md (Phase 2 section). Build a prioritized plan covering objectives, target keywords (primary/secondary/long-tail), metadata optimization (title, subtitle, keywords, description, what's-new), visual assets, localization, ratings strategy, and timeline.

Phase 3: Policy Compliance Check

Read references/phase-3-compliance.md. Validate every proposed metadata field against:

• Prohibited keyword lists (Apple + Google)
• Trademark and competitor brand checks
• Formatting rules (no emojis, no ALL CAPS, character limits)
• Content accuracy

If any violation is found, revise the plan silently and re-run the compliance check. The user should only ever see a compliant plan.

User Approval Gate

After compliance passes, present the plan and compliance report to the user. Do not proceed to Phase 4 until the user explicitly approves the plan. Iterate as many times as needed; each revision must re-pass the compliance check.

Phase 4: Execute

Read references/phases-4-7.md (Phase 4 section). Implement approved changes systematically, in priority order. Before overwriting any existing metadata file, create a .bak backup or confirm version control coverage. Validate character limits after each edit.

Phase 5: Review

Read references/phases-4-7.md (Phase 5 section). Run the review checklist on every changed field. Re-scan for prohibited keywords and trademark leaks.

Phase 6: Verify Against Best Practices

Read references/phases-4-7.md (Phase 6 section) and cross-reference references/aso_best_practices.md. Final pass for policy compliance.

Phase 7: Summarize

Read references/phases-4-7.md (Phase 7 section). Produce the final summary report (Changes Made, Metadata Comparison, Compliance Status, Expected Outcomes, Next Steps, Files Modified).

Step Completion Reports

After each major step, output a status report with √ pass / × fail markers. Format and per-phase check lists are in references/edge-cases.md (Step Completion Reports section).

Expected Output

A complete run produces three artifacts: Analysis Report (Phase 1), ASO Plan + Compliance Report + updated metadata files (Phases 2-4), and Summary Report (Phase 7). Worked examples for each: see references/expected-output.md.

Example

Input: an iOS+Android productivity app with weak metadata.

Title (iOS): FocusFlow: Work Timer            (22/30, no primary keyword)
Keywords (iOS): timer,focus,work,productivity (34/100, 66 chars unused)
Short Desc (Android): A simple timer for focused work. (36/80, weak)

Output after Phase 4 (metadata/app-info/en-US.json):

{
  "name": "FocusFlow: Focus & Work Timer",
  "subtitle": "Deep Work Sessions & Tracking"
}

Output keywords field:

pomodoro,deep,work,concentration,study,block,distraction,habit,goal,flow,task

(97/100 chars, all prohibited terms cleared, no title/subtitle duplicates.) Full walkthrough in references/expected-output.md.

Acceptance Criteria

The skill run is successful when all metadata is within character limits, contains no prohibited keywords or trademarks, the user-approval gate was respected, and all required reports were produced. Full criteria list: references/edge-cases.md (Acceptance Criteria section).

Edge Cases

Common edge cases (no local metadata files, single-platform app, no competitor access, pre-launch app, non-English primary locale, user rejects plan, compliance violation in draft) are documented in references/edge-cases.md. Read that file when an edge case applies — do not improvise.

Platform-Specific Notes

Apple App Store, Google Play Store, and cross-store conventions (indexed fields, character limits, OCR-indexed screenshots, A/B testing surfaces) are documented in references/edge-cases.md (Platform-Specific Notes section).

Cross-Skill Integration

This skill complements seo-ai-optimizer. See references/edge-cases.md (Cross-Skill Integration section) for when to combine.

Safety and Caution

• No destructive action without confirmation. Before any git pull --rebase, git stash, file deletion, or overwriting an existing metadata file, either run a dry-run preview, create a .bak backup, or ask the user. Failures and errors must surface to the user — do not silently retry.
• Compliance gate is non-negotiable. Never present a non-compliant plan to the user; never execute without explicit approval.
• Trademark caution: Competitor brand names from Phase 1 analysis must never appear in proposed metadata.

---

Supporting file: agents/analyzer.md

Analyzer Agent

Comprehensive analysis of app, current metadata, and competitive landscape for ASO planning.

Role

Read all codebase metadata files, existing app store metadata, and competitive information. Produce a structured analysis report covering app overview, current metadata status, competitive landscape, and key findings/opportunities.

Inputs

You receive these parameters in your prompt:

• project_dir: Root directory of the mobile app project
• output_path: Where to save the analysis report JSON/markdown
• store_focus: "ios" or "android" or "both" (guides which metadata files to scan)

Process

Step 1: Detect Project Identity

Search the project directory for:

• README.md — app name, description, tagline
• package.json (if iOS/React Native)
• pubspec.yaml (if Flutter)
• build.gradle (if Android native)
• Info.plist (if iOS native)
• AndroidManifest.xml (if Android native)
• Any other metadata files

Extract:

• App name (exact spelling)
• Short description (1-2 sentences)
• Primary purpose and core value proposition
• Target audience (developers, consumers, enterprises, etc.)
• Platforms supported (iOS, Android, both, web-based)

Step 2: Audit Current Metadata

If iOS (App Store) metadata exists:

• Check metadata/app-info/{locale}.json for: name, subtitle, keywords, description
• Check metadata/version/{version}/{locale}.json for: keywords, description, whatsNew, promotionalText
• For each field, record:
  • Current value
  • Character count vs. limit
  • Keyword density (how many keywords appear)
  • Quality assessment

If Android (Google Play) metadata exists:

• Check fastlane/metadata/android/{locale}/ or supply/metadata/ for:
  • title.txt (max 30 chars)
  • short_description.txt (max 80 chars)
  • full_description.txt (max 4,000 chars)
  • Changelogs
• For each field, record the same metadata as iOS

Step 3: Categorize App

Determine the app category:

• Categories: Productivity, Games, Social, Health/Fitness, Education, Utilities, Business, Finance, Shopping, Travel, News, Photos/Video, Lifestyle, Stickers, Music, etc.
• Note platform-specific differences (iOS vs. Android may be in different categories)

Step 4: Identify Supporting Brand Assets

Search for:

• /docs/brand_kit.md or brand_kit.md — brand colors, tone, visual guidelines
• /docs/prd.md or prd.md — product requirements, target users, messaging
• /assets/logo/, /public/logo, /static/logo — existing visual assets
• Tailwind/CSS variables — color palette

Step 5: Check Existing Store Presence

If the app is already live:

• Note the current rating (if available)
• Note the install count or ranking (if available from public info)
• Check for existing reviews (sentiment)
• Note any current app store keyword rankings (if available)

Step 6: Gather Competitive Landscape

Ask or infer 3-5 direct competitors:

• Note their app names
• Capture their apparent keyword strategy (keywords in title, subtitle)
• Identify their strong points (high rating, featured status, etc.)
• Identify gaps (keywords they don't target that the user's app could)

IMPORTANT: Competitive analysis is for STRATEGY only. Do NOT carry competitor names into the proposed metadata.

Step 7: Assess Target Market

From PRD or README, identify:

• Primary markets: which countries/languages are priority
• Market size: is this a global app or niche?
• Seasonality: any trends or seasonality (e.g., fitness apps peak in January)
• Localization needs: is localization critical for success?

Step 8: Produce Analysis Report

Generate a comprehensive analysis report:

## ASO Analysis Report

**Date**: [ISO date]
**Project**: [app name]
**Store Focus**: [iOS / Android / Both]

### App Overview

- **App Name**: [exact name]
- **Platforms**: [iOS / Android / Both]
- **Category**: [category]
- **Core Value Proposition**: [1-2 sentences describing what the app does]
- **Target Audience**: [demographics, use cases, skill level]
- **Current Status**: [In development / Test flight / Live on App Store / Live on Play Store]

### Current Metadata Status

#### iOS (App Store)

| Field | Current Value | Chars Used | Limit | Usage % | Status |
|-------|---------------|------------|-------|---------|--------|
| **Name** | [current] | X | 30 | Y% | ✅ OK / ⚠️ Issue |
| **Subtitle** | [current] | X | 30 | Y% | ✅ OK / ⚠️ Issue |
| **Keywords** | [current] | X | 100 | Y% | ✅ OK / ⚠️ Issue |
| **Description** | [first 100 chars...] | X | 4000 | Y% | ✅ OK / ⚠️ Issue |
| **Whats New** | [current] | X | 4000 | Y% | ✅ OK / ⚠️ Issue |

#### Android (Google Play)

| Field | Current Value | Chars Used | Limit | Usage % | Status |
|-------|---------------|------------|-------|---------|--------|
| **Title** | [current] | X | 30 | Y% | ✅ OK / ⚠️ Issue |
| **Short Description** | [current] | X | 80 | Y% | ✅ OK / ⚠️ Issue |
| **Full Description** | [first 100 chars...] | X | 4000 | Y% | ✅ OK / ⚠️ Issue |

### Competitive Landscape

#### Competitor Analysis

| Competitor | Platform | Keywords in Title | Rating | Apparent Strategy | Gaps |
|-----------|----------|-------------------|--------|-------------------|------|
| [App 1] | iOS/Android | [keywords] | 4.2★ | Focus on [...] | Missing [keyword] |
| [App 2] | iOS | [keywords] | 4.5★ | Focus on [...] | Missing [keyword] |
| [App 3] | Android | [keywords] | 4.0★ | Focus on [...] | Missing [keyword] |

### Key Findings

1. **[Finding 1 — most impactful]**: [Description and why it matters]
   - Impact: [High/Medium/Low]
   - Evidence: [What data supports this]

2. **[Finding 2]**: [Description]
   - Impact: [High/Medium/Low]
   - Evidence: [...]

3. **[Finding 3]**: [Description]
   - Impact: [High/Medium/Low]
   - Evidence: [...]

#### Example Findings:
- Current subtitle uses 28/30 characters but has no keywords — opportunity to integrate target keyword
- Android title is generic ("My App") — strong opportunity to add differentiating keyword
- Competitor "XYZ App" dominates with keyword [ABC] in title and subtitle — we could target this if not too competitive
- iOS description is keyword-sparse — can naturally integrate 5+ target keywords
- No localization strategy identified — opportunity for international expansion

### Opportunities

1. **[Opportunity 1 — highest potential impact]**: [What to do]
   - Expected Impact: [Higher ranking for X keywords / Improved conversion rate / etc.]
   - Effort: [Low/Medium/High]
   - Priority: [P0/P1/P2]

2. **[Opportunity 2]**: [What to do]
   - Expected Impact: [...]
   - Effort: [...]
   - Priority: [...]

#### Example Opportunities:
- Integrate primary keyword [ABC] into iOS subtitle → +20% visibility for [ABC] searches
- Expand Android description to 2000+ chars, naturally repeating 3-5 target keywords → improve ranking for long-tail searches
- Implement localization for Japanese market → tap untapped market segment
- Create subtitle focusing on conversion (value proposition) not just keywords → improve install rate from listing page views

### Brand & Asset Analysis

- **Brand Colors**: [hex codes if found in brand_kit.md / CSS / config]
- **Brand Voice**: [tone descriptors if found in brand_kit.md or PRD]
- **Logo/Icon Status**: [current assets, any issues]
- **Screenshot Count**: [X screenshots across platforms]
- **Preview Video**: [Present / Missing]

### Market & Localization

- **Primary Markets**: [Ranked by opportunity]
- **Localization Status**: [Languages supported, quality of translations if any]
- **Seasonal Patterns**: [None / Q1 fitness peak / Holiday shopping peak / etc.]

### Current Barriers

- [ ] Low keyword coverage in title/subtitle
- [ ] Poor conversion messaging (description doesn't emphasize value prop)
- [ ] Missing localization for high-potential markets
- [ ] Weak competitive differentiation
- [ ] Screenshot/asset quality issues
- [ ] Spam or non-compliant metadata (flagged for Phase 3 compliance check)
- [ ] None — metadata is strong

### Recommendations for Phase 2

Based on this analysis, the plan should prioritize:
1. [Top recommendation based on findings]
2. [Second recommendation]
3. [...]

---

**Analysis Complete**. Ready for Phase 2: Plan Writer Agent.

Output Format

Both JSON (for machine consumption by plan-writer agent) and markdown (for human review).

JSON structure:

{
  "app_name": "...",
  "platforms": ["ios", "android"],
  "category": "...",
  "value_proposition": "...",
  "target_audience": "...",
  "current_metadata": {
    "ios": {
      "name": "...",
      "subtitle": "...",
      "keywords": "...",
      "description": "..."
    },
    "android": {
      "title": "...",
      "short_description": "...",
      "full_description": "..."
    }
  },
  "competitors": [
    {
      "name": "...",
      "keywords_in_title": "...",
      "rating": 4.2,
      "strategy": "...",
      "gaps": "..."
    }
  ],
  "findings": [
    {
      "finding": "...",
      "impact": "high|medium|low",
      "evidence": "..."
    }
  ],
  "opportunities": [
    {
      "opportunity": "...",
      "expected_impact": "...",
      "effort": "low|medium|high",
      "priority": "p0|p1|p2"
    }
  ],
  "brand_colors": ["#hex", "..."],
  "brand_voice": "...",
  "primary_markets": ["...", "..."],
  "localization_status": "...",
  "barriers": ["...", "..."]
}

Tips

• Be thorough in metadata audit — missing data leads to gaps in the plan
• Competitive analysis is for understanding the market, not copying. Flag opportunities to differentiate.
• If existing metadata is poor, note this clearly — it will drive high-priority fixes in the plan
• Localization can be a major opportunity for growth — flag any high-potential markets not yet localized

---

Supporting file: agents/compliance-checker.md

Compliance Checker Agent

Validate all proposed metadata against store policies before user approval.

Role

Scan every piece of proposed metadata in the ASO plan against Apple App Store and Google Play Store policies. Identify prohibited keywords, trademark violations, formatting issues, and content accuracy problems. Ensure the plan is policy-compliant before it's presented to the user.

Inputs

You receive these parameters in your prompt:

• plan_markdown_path: Path to the ASO plan from plan-writer agent
• references_dir: Path to references/ directory (for ASO best practices and prohibited keyword lists)
• output_path: Where to save the compliance report

Process

Step 1: Load the Plan and References

Read the ASO plan markdown (all proposed metadata). Read references/aso_best_practices.md → "Store Policy Compliance" section for:

• Apple App Store banned keywords list
• Google Play Store banned keywords list
• Trademark rules for both stores
• Formatting rules (emojis, caps, special characters, etc.)
• Content accuracy rules

Step 2: Prohibited Keyword Scan

For EACH field in the proposed metadata (name, subtitle, keywords, descriptions), scan for banned terms:

Apple App Store — Banned in title, subtitle, keywords:

• Pricing terms: "free", "sale", "discount", "limited time", "on sale"
• Superlative claims: "best", "#1", "top-rated", "must-have", "top app", "number one"
• Reserved terms: "For Kids", "For Children" (unless in Kids Category), "Editor's Choice"
• Platform references: "Android", "Google Play", "Play Store"
• Call-to-action phrases: "download now", "install now", "try now", "get now"
• Competitor brand names: "WhatsApp", "Instagram", "Slack", etc.

Google Play — Banned in title, short description, developer name, icon:

• Performance claims: "top", "best", "#1", "number one", "popular", "fastest", "highest rated"
• Pricing terms: "free", "no ads", "ad free", "without ads"
• Promotional terms: "new", "hot", "first", "bonus", "discount", "sale", "million downloads", "limited time"
• 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 (same as Apple)

Create a compliance matrix:

Scan Results:

iOS Name: "Meditation – Sleep & Calm"
- "Meditation" ✅ OK (core function, not banned)
- "Sleep" ✅ OK
- "Calm" ✅ OK
- No prohibited terms found

iOS Subtitle: "Sleep better tonight"
- "Sleep" ✅ OK
- "better" ✅ OK (comparative, not superlative — "best" would fail)
- No prohibited terms found

iOS Keywords: "meditation,sleep,mindfulness,relaxation,stress relief,breathing,anxiety,sleep sounds,guided,calm"
- Check each: meditation ✅, sleep ✅, mindfulness ✅, ...
- No prohibited terms found

iOS Description:
- "Sleep better" ✅ OK
- "500+ guided meditations" ✅ OK (number is OK, just not "#1" or "top")
- "Calm your mind" ✅ OK
- No prohibited terms found

Android Title: "Meditation – Sleep & Calm"
- Same as iOS, ✅ OK

Android Short Description: "Sleep, meditate, and find calm with 500+ guided meditations and relaxation sounds"
- All terms ✅ OK
- No prohibited terms found

Android Full Description:
- [Check full text for any banned terms]

Step 3: Trademark and Competitor Check

Scan all proposed metadata for:

1. Competitor brand names — any mention of:

   • Other meditation apps (e.g., "Calm", "Headspace", "Insight Timer")
   • Any competitor app names should be REMOVED from title, subtitle, keywords, descriptions
   • Example: ❌ "Better than Calm" → ✅ "Deep sleep and calm" (no competitor names)

2. Trademarked terms — any term the developer doesn't own:

   • Platform trademarks: Apple, Google, iOS, Android (usually OK in description, bad in title/subtitle)
   • Celebrity names: only use if explicitly authorized
   • Brand names: only if the developer owns the brand
   • Example: ❌ "Apple-approved meditation" → ✅ "Award-winning meditation app"

3. Misleading trademark use:

   • "Featured by Apple" — unless actually featured (violates App Store guideline 2.3.7)
   • "Google's Choice" — unless actually awarded

Matrix for trademark check:

Trademark Scan:

iOS Name: "Meditation – Sleep & Calm"
- No competitor names ✅
- No trademarked terms ✅
- No "Featured" claims ✅

[Continue for all fields]

Step 4: Formatting Compliance

Check for formatting violations:

iOS Title/Subtitle:

• No emojis (❌ "Meditation ☮️ Sleep" — emojis can trigger rejection)
• No ALL CAPS (unless registered brand name)
• No repeated special characters (!!! ❌, ?? ❌)
• Within character limits (30 chars each)
• No exclamation marks at end (unprofessional, low conversion)

Android Title/Short Description:

• No emojis
• No ALL CAPS (unless brand name)
• No special character abuse
• Within character limits (30 chars title, 80 chars short description)

Both Platforms Description:

• No emojis (can reduce discoverability)
• Text readable (no leetspeak, no excessive formatting)
• Proper grammar and spelling
• No unattributed quotes or fake user testimonials

Step 5: Content Accuracy Check

Verify all claims in the description are verifiable:

• "500+ guided meditations" — does the app actually have 500+? If so, OK.
• "2M+ users" — is this publicly stated somewhere, or just marketing hope? If unverifiable, remove or change to "Join millions..."
• "Award-winning" — does the app have a real award? If not, ❌ remove.
• "Voted best app" — if not actually voted/awarded, ❌ remove.
• "Reduce anxiety" — is this a medical claim? If so, requires disclaimer or removal.
• "Sleep better" — is this a medical claim or lifestyle claim? (Lifestyle OK, medical requires evidence)

Example corrections:

• ❌ "Scientifically proven to reduce anxiety" (medical claim without evidence)
• ✅ "Many users report better sleep and reduced stress" (qualitative, not medical)
• ❌ "4.8★ rating from 100k+ reviews" (claim rating, let the store show this)
• ✅ "Loved by users worldwide" (qualitative, doesn't claim false numbers)

Step 6: Cross-Field Duplication Check (iOS only)

iOS keywords field must NOT duplicate words from title or subtitle:

• Title: "Meditation – Sleep & Calm"
• Subtitle: "Sleep better tonight"
• Keywords should NOT contain: meditation, sleep, calm, better, tonight
• Keywords example: "mindfulness,relaxation,stress relief,breathing,anxiety,sleep sounds,guided,focus,yoga,wellness"

If duplicates found:

• ❌ Keywords: "meditation,sleep,calm,..." (bad — wasting 20+ chars on duplicates)
• ✅ Keywords: "mindfulness,relaxation,..." (good — new words, maximize character budget)

Step 7: Write Compliance Report

Generate a comprehensive compliance report:

# Store Policy Compliance Report

**Project**: [app name]
**Date**: [ISO date]
**Status**: PASS / NEEDS REVISION

---

## Prohibited Keyword Check

### iOS (App Store)

| Field | Proposed Value | Banned Term Found | Status | Fix Required |
|-------|----------------|-------------------|--------|--------------|
| Name | "Meditation – Sleep & Calm" | None | ✅ PASS | No |
| Subtitle | "Sleep better tonight" | None | ✅ PASS | No |
| Keywords | "meditation,sleep,mindfulness,..." | None | ✅ PASS | No |
| Description | [text] | None | ✅ PASS | No |
| What's New | [text] | None | ✅ PASS | No |

### Android (Google Play)

| Field | Proposed Value | Banned Term Found | Status | Fix Required |
|-------|----------------|-------------------|--------|--------------|
| Title | "Meditation – Sleep & Calm" | None | ✅ PASS | No |
| Short Description | [text] | None | ✅ PASS | No |
| Full Description | [text] | None | ✅ PASS | No |

---

## Trademark Check

| Proposed Term | Field | Store | Risk Level | Action |
|--------------|-------|-------|-----------|--------|
| "Meditation" | Title | Both | None | Keep — core function, not trademarked by others |
| [if any risk terms] | [field] | [store] | [Low/High] | [Keep/Remove/Replace] |

**Overall Trademark Status**: ✅ PASS — No competitor or third-party trademarks detected

---

## Formatting Check

### iOS Title & Subtitle
- [x] No emojis
- [x] No ALL CAPS (unless brand name)
- [x] No repeated special characters
- [x] Title within 30 chars (used X/30)
- [x] Subtitle within 30 chars (used X/30)

### iOS Keywords
- [x] Comma-separated, no spaces after commas
- [x] No duplicate words from title/subtitle
- [x] 90+ chars utilization (used X/100 = Y%)

### Android Title & Short Description
- [x] No emojis
- [x] Title within 30 chars (used X/30)
- [x] Short description within 80 chars (used X/80)

### Both Platforms
- [x] No spelling/grammar errors
- [x] No unattributed quotes
- [x] No fake user testimonials
- [x] Professional tone

**Overall Formatting Status**: ✅ PASS

---

## Content Accuracy Check

| Claim | Field | Verifiable? | Evidence | Status |
|-------|-------|-----------|----------|--------|
| "500+ guided meditations" | Description | Yes | App data / store listing | ✅ OK |
| "2M+ users" | Description | ? | Marketing claim only | ⚠️ Consider changing to "Join millions..." |
| "Reduce anxiety" | Description | Qualitative | User reports / testimonials | ✅ OK (not medical claim) |

**Recommendations**:
- ⚠️ Change "2M+ users" to "Join millions of meditators" (unverifiable number removal)
- ✅ Keep "Reduce anxiety" (lifestyle claim, not medical)

**Overall Content Accuracy Status**: ✅ PASS (with recommended changes)

---

## Overall Status: ✅ PASS

**All proposed metadata passes store policy compliance checks.**

The plan is ready for user approval.

---

## Summary for User Presentation

✅ **Prohibited Keywords**: None found in any field
✅ **Trademarks**: No competitor or third-party brand names used
✅ **Formatting**: All fields properly formatted, character limits met
✅ **Content Accuracy**: All claims are verifiable or qualitative (not misleading medical claims)

**Status**: Ready for Phase 4 Execution

Or, if issues found:

# Store Policy Compliance Report — NEEDS REVISION

## Issues Found

### 1. Prohibited Keyword Violation
**Field**: iOS Keywords
**Issue**: Contains "free" which is banned on iOS
**Current**: "...meditation,sleep,free meditation,..."
**Fix**: Remove "free meditation" and replace with "guided meditation"
**Revised**: "meditation,sleep,mindfulness,guided meditation,..."

### 2. Competitor Trademark
**Field**: iOS Subtitle
**Issue**: "Better than Calm" mentions competitor brand "Calm" (trademarked)
**Current**: "Better than Calm – sleep better"
**Fix**: Remove competitor reference, focus on value proposition
**Revised**: "Sleep better, stress less"

### 3. Unverifiable Claim
**Field**: Android Full Description
**Issue**: "Voted Best Meditation App 2025" — is this a real award?
**Current**: "Voted Best Meditation App 2025"
**Fix**: If real, provide award name. If not, remove.
**Revised**: Remove or change to "Loved by users worldwide"

---

## Overall Status: ❌ NEEDS REVISION

**Required Changes**:
1. Remove "free" from iOS keywords
2. Remove competitor brand name from iOS subtitle
3. Remove or verify "Best Meditation App 2025" claim

**After fixing above 3 issues, the plan will PASS compliance.**

---

## Revised Plan Section

Here are the revised fields:

iOS Keywords: "meditation,sleep,mindfulness,guided meditation,relaxation,stress relief,breathing,anxiety,sleep sounds,calm"

iOS Subtitle: "Sleep better, stress less"

Android Full Description: [revised text without award claim]

Output Format

Markdown report at the specified output path. If PASS, the plan is ready for user approval. If NEEDS REVISION, provide specific fixes.

Key Decision Points

If issues found:

• Fix them automatically if they're simple (word replacements, removals)
• Flag for manual review if they require judgment (is this really a medical claim? is this award real?)
• Return the revised metadata alongside the report

The user should only see a PASS report. If NEEDS REVISION, fix it first, re-validate, then report PASS.

Tips

• Be conservative with policy interpretation. If you're unsure whether something violates policy, flag it.
• Trademark check is critical — competitor brand names in hidden keywords can get the app de-indexed
• Content accuracy is important for trust — unverifiable claims damage long-term user satisfaction
• Formatting issues like emojis can seem harmless but often trigger store rejections

---

Supporting file: agents/executor.md

Executor Agent

Implement approved ASO plan changes into metadata files.

Role

After the user approves the ASO plan, consume the approved plan and implement all metadata changes. Create or update metadata files (App Store and Google Play formats) with the optimized keywords, descriptions, and metadata.

Inputs

You receive these parameters in your prompt:

• approved_plan_path: Path to the ASO plan (with user approval notes)
• project_dir: Root directory of the mobile app project
• platforms: "ios" or "android" or "both"
• output_notes: Path where to save implementation notes

Process

Step 1: Load Approved Plan

Read the ASO plan markdown and identify:

• Approved changes for each metadata field
• User modifications (if any) to the plan
• Platforms to update (iOS, Android, or both)

Step 2: Discover and Create Metadata Structure

Determine if local metadata files exist. If they do, update them. If not, create the appropriate structure.

iOS (App Store) Metadata Structure

If it doesn't exist, create:

metadata/
├── app-info/
│   ├── en.json        # Name, subtitle, keywords, description per locale
│   ├── de.json
│   └── ja.json
└── version/
    └── 1.0.0/
        ├── en.json    # What's New, version-specific metadata
        └── ...

Each JSON file format:

{
  "name": "Meditation – Sleep & Calm",
  "subtitle": "Sleep better tonight",
  "keywords": "meditation,sleep,mindfulness,...",
  "description": "Meditation and sleep made simple...",
  "release_notes": "Latest update: Added 50 new..."
}

Android (Google Play) Metadata Structure

If it doesn't exist, create:

fastlane/metadata/android/
├── en-US/
│   ├── title.txt                  # Max 30 chars
│   ├── short_description.txt      # Max 80 chars
│   ├── full_description.txt       # Max 4000 chars
│   └── changelogs/
│       └── default.txt            # What's new
├── de-DE/
│   └── ...
└── ja-JP/
    └── ...

Or if using supply/ structure:

supply/metadata/
├── listings/
│   ├── en-US/
│   │   ├── title.txt
│   │   └── short_description.txt
│   └── ...

Step 3: Update iOS Metadata (if applicable)

For each locale in the approved plan:

1. Name (30 chars max):

   • Update metadata/app-info/{locale}.json → "name" field
   • Verify character count
   • Example: "name": "Meditation – Sleep & Calm"

2. Subtitle (30 chars max):

   • Update metadata/app-info/{locale}.json → "subtitle" field
   • Verify character count
   • Example: "subtitle": "Sleep better tonight"

3. Keywords (100 chars max):

   • Update metadata/app-info/{locale}.json → "keywords" field
   • Verify: comma-separated, no spaces, no duplicates of name/subtitle
   • Character count must be <= 100
   • Example: "keywords": "meditation,sleep,mindfulness,relaxation,stress relief,breathing,anxiety,sleep sounds,guided,calm"

4. Description:

   • Update metadata/app-info/{locale}.json → "description" field
   • Full text (up to 4000 chars)
   • Verify: natural keyword integration, no keyword stuffing

5. What's New:

   • Update metadata/version/{version}/{locale}.json → "release_notes" field
   • Keep up to 4000 chars
   • Example: "Latest update: Added 50 new guided sleep meditations, improved offline listening, fixed rare crash on app startup"

6. Validation:

   • Write to JSON with proper escaping (double quotes, newlines as \n)
   • Verify JSON is valid (parseable)
   • Check character counts in placeholders or comments

Step 4: Update Android Metadata (if applicable)

For each locale in the approved plan:

1. Title (30 chars max):

   • Create/update fastlane/metadata/android/{locale}/title.txt
   • Single line, no newlines
   • Example: Meditation – Sleep & Calm

2. Short Description (80 chars max):

   • Create/update fastlane/metadata/android/{locale}/short_description.txt
   • Single line, no newlines
   • Example: Sleep, meditate, and find calm with 500+ guided meditations

3. Full Description (4000 chars max):

   • Create/update fastlane/metadata/android/{locale}/full_description.txt
   • Multi-line, natural flow
   • Example: Full markdown text with line breaks

4. What's New / Changelogs:

   • Create/update fastlane/metadata/android/{locale}/changelogs/default.txt
   • Latest release notes

5. Validation:

   • Write as plain text files (UTF-8 encoding)
   • Verify character counts in each file
   • Check for encoding issues (special characters)

Step 5: Handle Localization

For each approved localization language:

1. Determine if files already exist
2. If not, create new locale directory
3. Populate with translated/localized metadata
4. For new locales, copy structure from en-US and translate/adapt keywords

Example for Japanese:

metadata/app-info/ja.json:
{
  "name": "瞑想 – 睡眠と落ち着き",
  "subtitle": "今夜の睡眠を改善する",
  "keywords": "瞑想,睡眠,マインドフルネス,...",
  ...
}

Step 6: Create Implementation Summary

Document what was created/modified:

# ASO Implementation Summary

**Date**: [ISO date]
**Project**: [app name]
**Platforms**: iOS / Android / Both

## Files Created/Modified

### iOS Metadata
- ✅ Created `metadata/app-info/en.json` (Name, Subtitle, Keywords, Description)
  - Name: "Meditation – Sleep & Calm" (25/30 chars)
  - Subtitle: "Sleep better tonight" (20/30 chars)
  - Keywords: [100 chars] (90/100 chars = 90% utilization)
  - Description: [4000 chars] (2800/4000 chars = 70% utilization)

- ✅ Created `metadata/app-info/de.json` (German localization)
  - Name: "Meditation – Schlaf & Ruhe" (27/30 chars)
  - [...]

- ✅ Created `metadata/version/1.0.0/en.json` (Release Notes)
  - What's New: "Latest update: Added 50 new guided sleep meditations..."

### Android Metadata
- ✅ Created `fastlane/metadata/android/en-US/title.txt`
  - "Meditation – Sleep & Calm" (27/30 chars)

- ✅ Created `fastlane/metadata/android/en-US/short_description.txt`
  - "Sleep, meditate, and find calm with 500+ guided meditations" (61/80 chars)

- ✅ Created `fastlane/metadata/android/en-US/full_description.txt`
  - Full description with natural keyword integration

- ✅ Created `fastlane/metadata/android/de-DE/...` (German)

- ✅ Created `fastlane/metadata/android/ja-JP/...` (Japanese)

## Character Utilization Summary

| Field | iOS | Android | Status |
|-------|-----|---------|--------|
| Title/Name | 25/30 (83%) | 27/30 (90%) | ✅ Optimal |
| Subtitle/Short Desc | 20/30 (67%) | 61/80 (76%) | ✅ Good |
| Keywords/Full Desc | 90/100 (90%) | 2800/4000 (70%) | ✅ Good |

## Localization Status

- ✅ English (en) — Complete
- ✅ German (de) — Complete
- ✅ Japanese (ja) — Complete

## Next Steps (Phase 5 Review)

1. **Files are ready for upload to stores**:
   - iOS: Use App Store Connect to upload or use `asc` CLI
   - Android: Use Google Play Console to upload or use `fastlane` `supply` tool

2. **Before publishing**:
   - [ ] Review all metadata in store consoles one more time
   - [ ] Verify screenshots have caption text aligned with keywords
   - [ ] Check that all localized versions display correctly

3. **After publishing**:
   - [ ] Monitor keyword rankings for primary keywords in App Store Connect / Google Play Console
   - [ ] Track install numbers for the first 2 weeks (baseline)
   - [ ] Collect user feedback from reviews

4. **Timeline**:
   - App Store: Changes live within ~24-48 hours
   - Google Play: Changes live within a few minutes to a few hours

---

**Implementation Complete. Ready for Phase 5: Review.**

Step 7: Validation

Before finalizing, verify:

• All metadata files created/updated
• Character limits respected for each field
• No spelling/grammar errors
• JSON files are valid (parseable)
• Plain text files are UTF-8 encoded
• All locales requested are included
• Keyword integration looks natural (not stuffed)

Output Format

1. Updated metadata files in the project directory
2. Implementation summary markdown (saved to output_notes)

Error Handling

If metadata files have unexpected format:

• Log the format you found
• Create metadata in both possible formats (iOS + Android)
• Report what you created in the summary

If character limits are exceeded (unlikely after compliance check, but possible):

• Truncate at character limit
• Flag in the implementation summary
• Example: "Name exceeded 30 chars, truncated to: 'Meditation – Sle...'"

Tips

• Metadata files should be ready to commit to the repo
• Use proper JSON/text encoding to avoid issues when uploaded to stores
• Keyword integration in descriptions should look natural, not mechanical
• Keep implementation notes detailed so the team knows exactly what was changed

---

Supporting file: agents/plan-writer.md

Plan Writer Agent

Generate comprehensive ASO plan with keywords, metadata, visuals, and localization strategy.

Role

Consume the analysis report from the analyzer agent and create a detailed, actionable ASO plan. The plan covers keyword strategy, metadata optimization, visual assets, localization, and conversion improvements.

Inputs

You receive these parameters in your prompt:

• analysis_json_path: Path to the JSON output from analyzer agent
• analysis_markdown_path: Path to the markdown analysis report
• references_dir: Path to references/ directory (for ASO best practices, prohibited keyword list)
• output_path: Where to save the ASO plan markdown

Process

Step 1: Load Analysis

Read both the JSON and markdown analysis:

• Understand current metadata strengths/weaknesses
• Understand competitive landscape
• Understand key opportunities
• Understand barriers

Step 2: Develop Keyword Strategy

For the app's primary use case, identify:

Primary Keywords (high volume, core relevance)

• 3-5 keywords that directly describe the app's core function
• Example: For a meditation app: "meditation", "sleep", "mindfulness", "relaxation", "stress relief"
• For each: estimate search volume (if possible), note competition, identify best placement (title vs. subtitle vs. keywords field)

Secondary Keywords (moderate volume, good fit)

• 5-10 keywords for related features or use cases
• Example: "breathing exercises", "anxiety relief", "meditation music"
• Broader appeal, often long-tail combinations

Long-Tail Keywords (lower volume, high intent)

• 10+ keywords for specific use cases or niches
• Example: "guided sleep meditation", "sleep meditation for anxiety", "sleep stories"
• Often user queries that solve specific problems

Important rules:

• Do NOT use prohibited keywords (see references/aso_best_practices.md "Store Policy Compliance")
• Do NOT use competitor brand names — even in hidden keywords, Apple and Google monitor
• Do NOT use superlatives ("best", "#1", "top") — both stores ban these
• Do NOT use pricing terms ("free", "sale", "discount") — automatic rejection
• Keywords should be single words or 2-word phrases when possible (enables cross-field combinations on iOS)

Step 3: Build Metadata Optimization Plan

For iOS:

• Name: Aim for 20-30 chars. Lead with primary keyword if possible, but prioritize app name clarity. Example: "Meditation – Sleep & Calm" (if "Meditation" is primary keyword)
• Subtitle: 20-30 chars. Include secondary keyword or value prop that drives conversion. Example: "Sleep better tonight"
• Keywords field: 90-100 chars. Comma-separated, no spaces, no duplicates of name/subtitle. Example: "sleep,mindfulness,relaxation,breathing,anxiety,stress relief,meditation music,sleep stories,guided meditation"
• Description: 4000 chars max. Hook users in first 2-3 sentences with value prop, then use bullet points for features, naturally integrate keywords throughout
• What's New: Highlight latest features, bug fixes, keyword-relevant improvements

For Android:

• Title: Max 30 chars. Include primary keyword if space allows. Example: "Meditation – Sleep & Calm"
• Short Description: Max 80 chars. Lead with value prop and fit a key benefit. Example: "Sleep, meditate, and find calm with guided exercises"
• Full Description: Max 4000 chars. Open with hook, use bullets for key features, naturally integrate keywords 3-5 times across the description

Step 4: Visual Asset Recommendations

• App Icon: Assess current icon. If needed, recommend visual changes (color, clarity, distinctiveness)
• Screenshots: Recommend ordering (lead with strongest feature), recommend caption text with keywords (iOS OCR-indexes since June 2025)
• Preview Video: Recommend whether one is needed, what to show in first 3 seconds (hook users before they swipe past)

Step 5: Localization Strategy

For each target market:

• Primary markets (high opportunity): e.g., US, UK, Japan, Germany
• Approach: Translate vs. Localize vs. Transcreate
  • Translate: Direct translation, good for basic info
  • Localize: Adapt keywords, examples, and copy to local culture (better for ASO)
  • Transcreate: Completely rewrite to match local language/culture (best, but expensive)
• For each market, identify 3-5 keywords specific to that market (not just translations of English keywords)

Step 6: Ratings & Reviews Strategy

Current rating: [X.X stars] Target rating: [4.5+ is ideal for App Store, 4.0+ for Google Play]

Actions:

• Implement in-app review prompt (best practices: after successful user action, not on app open)
• Review response strategy: respond to negative reviews with fixes
• Highlight positive reviews in marketing materials if applicable

Step 7: Create the ASO Plan Document

Structure the plan as markdown:

# ASO Marketing Plan

**Project**: [app name]
**Date**: [ISO date]
**Platforms**: [iOS / Android / Both]
**Target Markets**: [list]

---

## Objectives

- **Primary Objective**: [e.g., "Increase organic installs by 50% in 6 months by improving search visibility for meditation and sleep keywords"]
- **Secondary Objective**: [e.g., "Improve conversion rate from listing page views to installs by 20% through compelling value prop copy"]
- **Tertiary Objective**: [e.g., "Establish presence in Japanese market through localization"]

---

## Target Keywords

### Primary Keywords (High Volume, Core Relevance)

| Keyword | Est. Volume | Competition | Target Field (iOS) | Target Field (Android) | Rationale |
|---------|-------------|-------------|-------------------|----------------------|-----------|
| meditation | Very High | Very High | Name + Keywords | Title + Short Desc | Core function, must rank |
| sleep | Very High | Very High | Subtitle + Keywords | Full Desc | Sleep is key use case |
| mindfulness | High | High | Keywords | Full Desc | Core value prop |
| relaxation | High | Medium | Keywords | Full Desc | Conversion driver (user goal) |
| stress relief | High | High | Subtitle + Keywords | Full Desc | Pain point address |

### Secondary Keywords (Moderate Volume, Good Fit)

| Keyword | Est. Volume | Competition | Target Field | Rationale |
|---------|-------------|-------------|--------------|-----------|
| breathing exercises | Medium | Low | Keywords + Description | Specific feature |
| anxiety relief | Medium | High | Keywords + Description | User pain point |
| meditation music | Medium | Low | Keywords + Description | Feature differentiator |
| sleep sounds | Medium | Low | Keywords + Description | Feature differentiator |
| guided meditation | Medium | Medium | Keywords + Description | User preference |

### Long-Tail Keywords (Lower Volume, High Intent)

| Keyword | Est. Volume | Competition | Target Field | Rationale |
|---------|-------------|-------------|--------------|-----------|
| guided sleep meditation | Low | Low | Description | Specific use case, high intent |
| meditation for anxiety | Low | Low | Description | Specific pain point |
| fall asleep fast | Low | Medium | Description | User intent |
| yoga and meditation | Low | Low | Description | Related interest |

---

## Metadata Optimization Plan

### iOS (App Store)

#### Current Metadata vs. Proposed

| Field | Current | Proposed | Rationale |
|-------|---------|----------|-----------|
| **Name (30 chars max)** | [current] | "Meditation – Sleep & Calm" | Lead with primary keyword while keeping brand clear; heart symbol adds visual appeal |
| **Subtitle (30 chars max)** | [current] | "Sleep better tonight" | Value-prop focused; conversion-oriented; drives installs from listing view |
| **Keywords (100 chars max)** | [current] | "meditation,sleep,mindfulness,relaxation,stress relief,breathing,anxiety,sleep sounds,guided,calm" (100 chars) | Covers primary + secondary keywords; no duplicates with name/subtitle; comma-separated, no spaces; maximum character utilization |
| **Description (4000 chars max)** | [current] | [Proposed multi-paragraph version] | Leads with hook (benefit before features); uses bullets for scannability; naturally integrates keywords 5-8 times; ends with CTA |
| **What's New (4000 chars max)** | [current] | "Latest update: Added 50 new guided sleep meditations, improved offline listening..." | Feature-rich, keyword-natural |

#### Detailed Proposed Description

Meditation and sleep made simple. Calm your mind, improve sleep quality, and reduce anxiety with guided meditations tailored to your needs.

FEATURES: • 500+ guided meditations for sleep, stress relief, and mindfulness • Sleep sounds and music: rain, ocean waves, ambient nature • Breathing exercises to reduce anxiety and promote relaxation • Personalized meditation recommendations • Offline access — meditate anywhere, anytime • Daily mindfulness reminders and motivation • Track your progress and meditation streaks

PERFECT FOR: • Anyone looking to sleep better and wake refreshed • Busy professionals managing stress and anxiety • Students seeking focus and mindfulness • Long-term meditation practitioners deepening their practice

Join 2M+ meditators worldwide finding calm and better sleep through our guided meditations and relaxation techniques.

### Android (Google Play)

#### Current Metadata vs. Proposed

| Field | Current | Proposed | Rationale |
|-------|---------|----------|-----------|
| **Title (30 chars max)** | [current] | "Meditation – Sleep & Calm" | Matches iOS for consistency; keyword-forward |
| **Short Description (80 chars max)** | [current] | "Sleep, meditate, and find calm with 500+ guided meditations and relaxation sounds" | Value prop + feature mention; naturally integrates keywords; exactly 80 chars |
| **Full Description (4000 chars max)** | [current] | [Proposed version] | Opens with hook; emphasizes sleep and stress relief early; keyword integration natural (not forced) |

---

## Visual Asset Recommendations

### App Icon
**Current Assessment**: [Describe current icon — color, clarity, distinctiveness at small sizes]

**Recommendations**:
- [If needed: "Simplify to ensure clarity at 16px favicon size"]
- [If needed: "Increase color contrast for WCAG AA compliance"]
- [If strong: "Icon is excellent — clearly recognizable, high contrast, distinctive"]

### Screenshots

**Recommended Order & Messaging**:
1. **Screenshot 1**: Lead with strongest benefit — "Sleep Better Tonight" (hook user before they swipe)
2. **Screenshot 2**: Feature showcase — "500+ Guided Meditations" + keyword-rich caption
3. **Screenshot 3**: Conversion driver — "Reduce Stress & Anxiety" with user testimonial or stat
4. **Screenshot 4**: Feature depth — "Breathing Exercises for Anxiety Relief" with demo
5. **Screenshot 5**: Social proof — "2M+ Users, 4.8★ Rating"

**Caption Guidelines for iOS**:
- Include primary/secondary keywords naturally
- Keep captions scannable (2-3 lines max)
- Emphasize benefits over features

### Preview Video

**Recommendation**: [Create / Skip]
- If creating: Show meditation in progress (first 3 seconds), then app UI overview, then testimonial
- If skipping: Reason (strong screenshots are sufficient, or budget constraints)

---

## Localization Strategy

### Priority Markets

| Market | Opportunity | Language | Approach | Target Launch | Notes |
|--------|-----------|----------|----------|-----------------|-------|
| Japan | High | Japanese | Localize (transcreate) | Q3 2026 | Large meditation market; requires cultural adaptation |
| Germany | High | German | Localize | Q3 2026 | Strong wellness market; wellness terminology critical |
| Brazil | Medium | Portuguese (PT-BR) | Translate + adapt keywords | Q4 2026 | Growing app market; opportunity market |
| France | Medium | French | Translate + adapt keywords | Q4 2026 | Smaller market but high engagement possible |

### Per-Market Keywords

**Japan**:
- Primary: 瞑想 (meditation), 睡眠 (sleep), マインドフルネス (mindfulness)
- Secondary: ストレス軽減, 불안緩和, リラックス

**Germany**:
- Primary: Meditation, Schlaf, Achtsamkeit (mindfulness)
- Secondary: Stressabbau, Entspannung, Schlafqualität

**Brazil**:
- Primary: Meditação, Sono, Mindfulness
- Secondary: Alívio de stress, Ansiedade, Relaxamento

---

## Ratings & Reviews Strategy

**Current Rating**: [X.X stars] across [Y] reviews

**Target Rating**: 4.5+ (excellent for featured placement)

**Actions**:
1. **In-app Review Prompt**: Trigger after user completes their first meditation (positive moment)
   - Timing: After user presses "Complete"
   - Messaging: "Enjoying your meditation? Rate us!" (positive, not forced)
   - Frequency: Once per month max (don't annoy users)

2. **Review Response Strategy**:
   - Respond to negative reviews within 48 hours
   - Address specific complaints (crash reports, feature requests)
   - Highlight fixes in release notes

3. **Social Proof**:
   - Quote top reviews in App Store screenshots (if allowed)
   - Mention user count and rating in descriptions

---

## Timeline & Priorities

| Priority | Action | Impact | Effort | Timeline |
|----------|--------|--------|--------|----------|
| **P0** | Update iOS name + subtitle + keywords (takes 30 min in App Store Connect) | Very High | Low | Week 1 |
| **P0** | Update Android title + short description (takes 30 min in Google Play Console) | Very High | Low | Week 1 |
| **P1** | Refresh app icon for better small-size clarity | High | Medium | Week 2-3 |
| **P1** | Create localization keywords for Japan, Germany | High | Medium | Week 2-4 |
| **P2** | Record preview video highlighting meditation experience | Medium | High | Week 3-4 |
| **P2** | Implement in-app review prompt (developer time required) | Medium | Medium | Week 2-3 |

---

## Expected Impact Summary

**Conservative Estimate** (first 3 months):
- +30% visibility for primary keywords (meditation, sleep)
- +15% conversion rate improvement (from better value prop copy)
- +10% installs overall

**Optimistic Estimate** (with localization + visuals):
- +50% visibility for primary keywords
- +25% conversion rate improvement
- +30% installs overall

**Long-term** (6+ months with ongoing optimization):
- Establish as top-3 app in meditation category
- Strong presence in Japan, Germany secondary markets
- Consistent 4.5+ rating

---

## Next Steps

This plan is ready for **Phase 3: Policy Compliance Check**.

All proposed metadata will be validated against Apple App Store and Google Play Store policies before final approval.

Output Format

Markdown file at the specified output path, ready for the compliance-checker agent to validate.

Tips

• Keyword research should be as specific as possible. If you can't estimate search volume, use relative terms (high/medium/low) and note the limitation.
• Android description is much longer (4000 chars) — use it to rank for long-tail keywords that don't fit iOS keywords field.
• Localization should be market-aware, not just translation. Different markets have different search behavior and user preferences.
• Visual asset recommendations should be specific (what caption text to use, what to emphasize) — the implementer will need to execute on these.

---

Supporting file: agents/reviewer.md

Reviewer Agent

Final quality review of ASO implementation against best practices.

Role

Fresh-context review of the ASO implementation (Phase 5 review checklist + Phase 6 best-practices verification). Validate that the executed metadata is correct, complete, and follows all ASO best practices.

Inputs

You receive these parameters in your prompt:

• project_dir: Root directory of the mobile app project
• implementation_summary_path: Path to the implementation summary from executor
• original_plan_path: Path to the approved ASO plan
• references_dir: Path to references/aso_best_practices.md
• output_path: Where to save the review report

Process

Step 1: Load Context

Read:

• The original ASO plan (what was approved)
• The implementation summary (what was executed)
• The actual metadata files in the project directory
• The best practices reference

Step 2: Phase 5 Review Checklist

Verify all executed metadata against the review checklist:

## Phase 5 Review Checklist

- [ ] All metadata fields within character limits
  - iOS: Name ≤ 30, Subtitle ≤ 30, Keywords ≤ 100, Description ≤ 4000, What's New ≤ 4000
  - Android: Title ≤ 30, Short ≤ 80, Full ≤ 4000

- [ ] No keyword duplication across indexed fields (iOS)
  - Keywords field does NOT contain words from Name or Subtitle
  - Example: Name "Meditation Sleep", Subtitle "Better", Keywords should not contain "meditation", "sleep", or "better"

- [ ] Keywords field properly formatted (commas, no spaces)
  - Format: "word1,word2,word3" (no spaces after commas)
  - Verified: [YES/NO]

- [ ] Descriptions read naturally with keywords integrated
  - Keywords appear 3-5 times naturally (not stuffed)
  - Readability score: [check by reading]
  - Example sentences flow naturally: [YES/NO]

- [ ] No spelling or grammar errors in any locale
  - English: [check]
  - German: [check]
  - Japanese: [check]
  - Verified: [YES/NO]

- [ ] Cross-field keyword combinations produce intended search queries (iOS)
  - Example: Name "Meditation" + Keyword "sleep" = searchable for "meditation sleep"
  - Verified: [check each primary keyword]

- [ ] Visual asset recommendations are specific and actionable
  - [Check if applicable — depends on whether visual assets were part of plan]

- [ ] Localized metadata is genuinely localized (not just translated)
  - German keywords are German-specific (not English translated): [check]
  - Japanese keywords are market-aware: [check]
  - Verified: [YES/NO]

- [ ] No sensitive or brand-risky terms introduced
  - Verified: [YES/NO]

- [ ] **No prohibited keywords** — re-scan all fields for banned terms
  - iOS banned terms: [none found]
  - Android banned terms: [none found]
  - Verified: [YES/NO]

- [ ] **No competitor trademarks** — verify no competitor brand names leaked into any metadata field
  - Verified: [YES/NO]

- [ ] **No unverifiable claims** — no superlatives without evidence
  - Verified: [YES/NO]

- [ ] **No platform references** — no "Android"/"Google Play" in iOS metadata or vice versa
  - iOS metadata: no Android references [YES/NO]
  - Android metadata: no iOS references [YES/NO]

- [ ] **No formatting violations** — no emojis, ALL CAPS (unless brand name), or special characters in titles
  - Verified: [YES/NO]

- [ ] **Accurate feature descriptions** — every claimed feature exists in the app
  - "500+ guided meditations" — does the app have 500+? [check]
  - "Sleep sounds" — feature exists? [check]
  - All claims verified: [YES/NO]

Step 3: Phase 6 Best-Practices Verification

Cross-reference the implementation against best practices:

## Phase 6 Best-Practices Verification

Read `references/aso_best_practices.md` and verify:

- [ ] Title/name includes primary keyword
  - Primary keyword: [meditation, sleep, etc.]
  - Does title include it? [check]
  - Placement: [beginning/middle/end]

- [ ] Subtitle/short description includes secondary keyword and value prop
  - Secondary keyword: [e.g., "stress relief", "anxiety"]
  - Does subtitle include it? [check]
  - Value prop present? [check]
  - Example: "Sleep better tonight" ✅ (value prop) + "Stress relief" [if present]

- [ ] Keywords field maximizes character budget (iOS)
  - Chars used: X/100
  - Utilization: X%
  - Target: >85%
  - Status: [✅ Optimal / ⚠️ Could use more / ❌ Under-utilized]

- [ ] Description is conversion-optimized with keyword integration
  - Opens with hook (benefit before features): [YES/NO]
  - Uses bullets for scannability: [YES/NO]
  - Keywords integrated naturally (not stuffed): [YES/NO]
  - Ends with clear reason to download: [YES/NO]
  - Social proof (awards, users, rating) included: [YES/NO]

- [ ] Localization is market-aware, not just translated
  - German: Uses German-specific keywords, not English translations: [YES/NO]
  - Japanese: Considers Japanese meditation culture/trends: [YES/NO]
  - Example market awareness: [describe what you found]

- [ ] Visual assets support conversion
  - [If applicable: Screenshots, icon, video]
  - Screenshot 1 leads with strongest benefit: [YES/NO]
  - Captions include keywords (iOS): [YES/NO]
  - App icon is clear at small sizes: [YES/NO]

- [ ] Rating/review strategy addressed
  - In-app review prompt timing documented: [YES/NO]
  - Review response strategy documented: [YES/NO]

- [ ] Ongoing optimization recommendations provided
  - Monitor keywords for: [rankings, install volume, conversion]
  - Test schedule: [4-6 weeks for re-optimization]
  - A/B test plan: [if applicable]

- [ ] **All metadata passes Store Policy Compliance rules**
  - No banned keywords: [YES/NO]
  - No trademark violations: [YES/NO]
  - Formatting compliant: [YES/NO]
  - Content accurate: [YES/NO]

- [ ] **No trademark violations** — final check for competitor or third-party trademarks
  - Verified: [YES/NO]

- [ ] **No prohibited keywords** — final scan against banned terms lists
  - Verified: [YES/NO]

Step 4: Spot-Check Actual Files

Read the actual metadata files that were created:

1. iOS: metadata/app-info/en.json

   • Read the actual JSON
   • Verify Name, Subtitle, Keywords fields match the approved plan
   • Check for typos, encoding issues

2. Android: fastlane/metadata/android/en-US/title.txt, short_description.txt, full_description.txt

   • Read the actual files
   • Verify content matches the approved plan
   • Check for encoding, line breaks, special character issues

3. Localized files: Sample one other locale (e.g., German)

   • Verify structure is correct
   • Verify keywords are localized (not just English translated)

Step 5: Identify Any Issues

If issues found during review:

Critical Issues (must fix):

• Prohibited keyword accidentally included
• Competitor trademark included
• Character limit exceeded
• Spelling/grammar error in description
• False/unverifiable claim

Medium Issues (should fix):

• Suboptimal keyword utilization (< 70% of available budget)
• Description is not conversion-optimized
• Localization is just translation, not localization

Minor Issues (nice to fix):

• Formatting could be improved
• Keyword density could be better
• Visual asset recommendations could be clearer

Step 6: Write Review Report

Generate a comprehensive review report:

# ASO Implementation Review Report

**Date**: [ISO date]
**Project**: [app name]
**Review Status**: ✅ PASS / ⚠️ MINOR ISSUES / ❌ CRITICAL ISSUES

---

## Executive Summary

The ASO implementation has been reviewed against:
1. Phase 5 Review Checklist (quality assurance)
2. Phase 6 Best-Practices Verification (ASO best practices)

**Overall Result**: ✅ Implementation is complete and high-quality, ready for store upload.

---

## Phase 5 Review Results

### Character Limits
| Field | iOS | Android | Status |
|-------|-----|---------|--------|
| Name/Title | 25/30 | 27/30 | ✅ OK |
| Subtitle/Short Desc | 20/30 | 61/80 | ✅ OK |
| Keywords/Description | 90/100 | 2800/4000 | ✅ OK |

### Keyword Duplication (iOS)
✅ **PASS** — Keywords field contains no duplicates of Name or Subtitle
- Name: "Meditation – Sleep & Calm"
- Subtitle: "Sleep better tonight"
- Keywords: "mindfulness,relaxation,stress relief,breathing,anxiety,sleep sounds,guided,focus,yoga,wellness"
- No overlap detected

### Formatting
✅ **PASS** — No emojis, ALL CAPS, or special character issues
- All titles use sentence case
- Subtitle is readable and natural
- Keywords are properly comma-separated

### Grammar & Spelling
✅ **PASS** — No spelling or grammar errors detected
- English: Professional tone, no typos
- German: Proper German conventions, no typos
- Japanese: Proper character encoding, verified

### Prohibited Keywords
✅ **PASS** — No prohibited keywords found
- Scanned for: "free", "best", "#1", "discount", "download now", etc.
- Result: All clear

### Trademark Check
✅ **PASS** — No competitor or third-party trademarks
- Verified no mentions of: Calm, Headspace, Insight Timer, etc.
- Result: All clear

### Content Accuracy
✅ **PASS** — All claims are verifiable
- "500+ guided meditations" — verified in app
- "Sleep sounds" — feature exists
- "Reduce anxiety" — lifestyle claim (not medical), OK

---

## Phase 6 Best-Practices Verification

### Keyword Strategy
✅ **PASS** — Keywords are well-chosen and strategically placed
- Primary keyword "meditation" in Name ✅
- Secondary keyword "sleep" in Subtitle ✅
- Long-tail keywords in Description ✅
- Keywords field at 90% utilization ✅ (exceeds 85% target)

### Description Quality
✅ **PASS** — Description is conversion-optimized
- Hook: "Meditation and sleep made simple" (benefit-first) ✅
- Features: Bullet points for scannability ✅
- Keywords: Integrated naturally 5+ times, no stuffing ✅
- CTA: "Join 2M+ meditators" (social proof + reason to download) ✅

### Localization
✅ **PASS** — German and Japanese are genuinely localized
- German: Uses "Achtsamkeit" (German mindfulness term), not "mindfulness" translation
- Japanese: Uses 瞑想 (proper term), includes context-specific keywords
- Both avoid simple word-for-word translation

### Visual Assets
ℹ️ **N/A** — Asset optimization depends on executor providing visual changes
- Screenshots should have captions with keywords (not verified here, depends on next step)
- App icon should be clear at 16px (not verified here)
- Recommendation: Verify visual assets in store console before publishing

### Rating & Review Strategy
✅ **PASS** — Strategy documented
- In-app review prompt: Trigger after first meditation ✅
- Response strategy: 48-hour responses to negative reviews ✅
- Social proof: Mention user count and rating ✅

### Ongoing Optimization
✅ **PASS** — Plan documented
- Monitor rankings for primary keywords ✅
- Re-evaluate in 4-6 weeks ✅
- A/B test with Custom Product Pages (iOS) or Store Listing Experiments (Android) ✅

---

## Issues Found

### Critical Issues: 0
All critical checks passed.

### Medium Issues: 0
All medium-priority items are in good shape.

### Minor Issues: 0
Implementation is high-quality with no notable gaps.

---

## Store-Specific Notes

### iOS (App Store)
- Name/Subtitle/Keywords all optimized for searchability
- Description positioned well for both ranking and conversion
- Ready for upload to App Store Connect

### Android (Google Play)
- Title matches iOS for brand consistency
- Short description is punchy and keyword-inclusive
- Full description provides depth without keyword stuffing
- Ready for upload to Google Play Console

---

## Localization Status

| Locale | Status | Notes |
|--------|--------|-------|
| English (en) | ✅ Complete | Ready for iOS/Android stores |
| German (de) | ✅ Complete | Localized for German market |
| Japanese (ja) | ✅ Complete | Localized for Japanese market |

---

## Next Steps (For User/Publisher)

1. **Upload to stores**:
   - iOS: App Store Connect → Manage version
   - Android: Google Play Console → Edit store listing
   - Use metadata files created in this skill

2. **Before publishing**:
   - [ ] Review in store console (what users will see)
   - [ ] Verify visual assets (screenshots, icon, video)
   - [ ] Double-check character limits in console UI (sometimes display differs from source)

3. **After publishing**:
   - [ ] Monitor rankings for primary keywords (appears in App Store Connect / Google Play Console after 24-48 hours)
   - [ ] Track install metrics for 2 weeks (baseline)
   - [ ] Collect reviews and analyze sentiment
   - [ ] Plan re-optimization in 4-6 weeks

4. **Timeline**:
   - iOS: Changes live in ~24-48 hours
   - Android: Changes live in minutes to a few hours

---

## Review Conclusion

✅ **The ASO implementation is complete, compliant, and high-quality.**

All Phase 5 review checklist items have passed. All Phase 6 best-practices are met. Metadata is ready for immediate publication to app stores.

No revisions needed. Proceed to Phase 7: Summarize.

---

**Review completed by**: Reviewer Agent
**Date**: [ISO date]

Or, if issues found:

# ASO Implementation Review Report — ISSUES FOUND

## Issues to Fix

### 🔴 Critical: Prohibited Keyword Found

**Field**: iOS Keywords
**Issue**: Contains "free meditation" (banned on iOS)
**Current**: "meditation,sleep,mindfulness,free meditation,stress relief,..."
**Fix**: Remove "free meditation", replace with "guided meditation" or similar
**Action**: Update `metadata/app-info/en.json` → keywords field

---

### 🟡 Medium: Keyword Utilization Below Target

**Field**: iOS Keywords
**Issue**: Using only 65/100 characters (65% utilization, target >85%)
**Current**: "meditation,sleep,mindfulness,anxiety,relaxation" (45 chars)
**Fix**: Add 3-5 more keywords: "breathing,stress,focus,sleep sounds,yoga,calm"
**Expected**: "meditation,sleep,mindfulness,anxiety,relaxation,breathing,stress,focus,sleep sounds,yoga,calm" (~90 chars)
**Action**: Update `metadata/app-info/en.json` → keywords field

---

## Impact Assessment

**Critical Issues**: 1 (must fix before publishing)
**Medium Issues**: 1 (should fix before publishing)
**Minor Issues**: 0

**Status**: ❌ NEEDS REVISION — Fix issues then re-review

---

## Fixed Version

After fixing the above 2 issues, here are the corrected fields:

```json
{
  "keywords": "meditation,sleep,mindfulness,anxiety,relaxation,breathing,stress,focus,sleep sounds,yoga,calm"
}

---

Re-Review Instructions

1. Update the metadata files with the fixes above
2. Re-run this review agent to verify fixes
3. Once fixes pass, you'll receive ✅ PASS

---

Review Status: ❌ NEEDS REVISION (2 issues to fix)

## Output Format

Markdown review report at the specified output path.

## Quality Gates

Before approving:
- [ ] No critical issues
- [ ] All Phase 5 checklist items pass
- [ ] All Phase 6 best-practices verified
- [ ] Spot-check actual files (no corruption, proper encoding)
- [ ] Localization is genuine (not just translated)

## Tips

- This is a fresh-context review — you're validating the executor's work
- Read the actual files, don't just trust the summary
- Keyword integration should look natural when you read it
- Localization should show market-awareness, not just word-for-word translation
- If you find issues, provide specific fixes so they're easy to apply

---

## Supporting file: docs/README.md



# ASO Marketing

> Full-lifecycle App Store Optimization for mobile apps — from analysis through planning, execution, verification, and reporting on both Apple App Store and Google Play.

## Highlights

- Analyzes your codebase and existing metadata to understand your app's value proposition
- Builds a prioritized ASO plan with keyword strategy, metadata optimization, and visual asset guidance
- **Validates all metadata against App Store and Google Play listing policies** — catches prohibited keywords, trademark violations, and policy-breaking content before submission
- Iterates on the plan with user approval before executing any changes
- Covers both Apple App Store and Google Play Store with platform-specific techniques
- Includes localization strategy, conversion rate optimization, and A/B testing recommendations

## When to Use

| Say this... | Skill will... |
|---|---|
| "Optimize my app store listing" | Analyze current metadata and create a full ASO plan with policy compliance checks |
| "ASO plan for my app" | Build a keyword strategy with metadata optimization recommendations, validated against store policies |
| "Increase app downloads organically" | Identify keyword gaps, conversion issues, and visibility improvements |
| "Help me rank higher in the App Store / Google Play" | Audit metadata, research competitors, and optimize all store fields while avoiding policy violations |
| "Check my listing for policy violations" | Scan metadata for prohibited keywords, trademark issues, and listing policy violations |
| "App marketing plan" | Create a comprehensive ASO strategy covering search, conversion, localization, and store policy compliance |

## How It Works

```mermaid
graph TD
    A["Analyze Codebase & Store Listing"] --> B["Build ASO Plan"]
    B --> C["Policy Compliance Check"]
    C --> D["User Approval Gate"]
    D --> E["Execute Metadata Changes"]
    E --> F["Review & Verify"]
    F --> G["Summary Report"]
    style A fill:#4CAF50,color:#fff
    style C fill:#E91E63,color:#fff
    style D fill:#FF9800,color:#fff
    style G fill:#2196F3,color:#fff

Installation

Install via npx (Vercel) (https://www.npmjs.com/package/skills):

npx skills add https://github.com/luongnv89/skills --skill aso-marketing

Or via agent-skill-manager (asm) (https://www.npmjs.com/package/agent-skill-manager):

asm install github:luongnv89/skills:skills/aso-marketing

Usage

/aso-marketing

Resources

Output

• ASO Analysis Report — Current state assessment with competitive landscape
• ASO Marketing Plan — Prioritized recommendations with keyword tables, metadata changes, and visual asset guidance
• Store Policy Compliance Report — Validation of all proposed metadata against Apple and Google Play listing policies, trademark checks, and prohibited keyword scans
• Updated Metadata Files — Optimized, policy-compliant metadata written to the project's canonical metadata directory
• ASO Summary Report — Before/after comparison with compliance status, expected outcomes, and next steps

---

Supporting file: evals/evals.json

{
  "skill_name": "aso-marketing",
  "evals": [
    {
      "id": 1,
      "prompt": "I have a fitness app for iOS that helps people do home workouts. It's been on the App Store for 6 months but barely gets any organic downloads. Can you help me optimize my store listing? The metadata is in ./metadata/ and my main competitor is Nike Training Club.",
      "expected_output": "Full ASO analysis report and prioritized plan with iOS-specific metadata optimization including cross-field keyword combination strategy and approval gate.",
      "files": [],
      "assertions": [
        {"text": "Produces a structured analysis report with app overview, metadata status table, and competitive findings", "type": "boolean"},
        {"text": "Includes categorized keyword tables (primary/secondary/long-tail) with volume estimates and rationale", "type": "boolean"},
        {"text": "Covers all iOS-specific metadata fields with character counts", "type": "boolean"},
        {"text": "Includes competitive analysis referencing Nike Training Club but does NOT use 'Nike Training Club' as a proposed keyword or in proposed metadata", "type": "boolean"},
        {"text": "Explains cross-field keyword combination strategy", "type": "boolean"},
        {"text": "Includes a store policy compliance check that scans for prohibited keywords, trademark violations, and listing policy issues", "type": "boolean"},
        {"text": "No proposed metadata contains prohibited terms (free, best, #1, top-rated) or competitor trademarks", "type": "boolean"},
        {"text": "Includes an explicit approval gate before execution", "type": "boolean"}
      ]
    },
    {
      "id": 2,
      "prompt": "We're launching a new meditation app on both iOS and Google Play next month. I need a complete ASO marketing plan. The app is called 'ZenMind' and it focuses on guided sleep meditation and stress relief. No existing metadata yet — starting from scratch.",
      "expected_output": "Comprehensive dual-platform ASO plan with platform-specific metadata, launch timeline, localization strategy, and visual asset guidance.",
      "files": [],
      "assertions": [
        {"text": "Has distinct sections for both Apple App Store AND Google Play with platform-specific metadata", "type": "boolean"},
        {"text": "iOS uses keywords field while Android emphasizes full description indexing", "type": "boolean"},
        {"text": "Addresses fresh-launch context with timeline and pre-launch steps", "type": "boolean"},
        {"text": "Includes localization strategy with priority markets", "type": "boolean"},
        {"text": "Targets meditation/sleep/stress relief with categorized keywords", "type": "boolean"},
        {"text": "Provides visual asset guidance (screenshots, icon, video)", "type": "boolean"},
        {"text": "Includes a policy compliance check validating proposed metadata against both Apple and Google Play store policies", "type": "boolean"},
        {"text": "No proposed metadata uses prohibited terms like 'best', 'free', '#1', or competitor trademarks like 'Headspace', 'Calm'", "type": "boolean"}
      ]
    },
    {
      "id": 3,
      "prompt": "My Android app is a budget tracker. It's getting decent downloads but the conversion rate from page views to installs is only about 15%. I think the store listing isn't convincing enough. Can you help improve the Google Play listing? Metadata is in fastlane/metadata/android/en-US/.",
      "expected_output": "Conversion-focused ASO plan for Google Play with before/after metadata, above-the-fold optimization, and A/B testing recommendations.",
      "files": [],
      "assertions": [
        {"text": "Prioritizes conversion rate optimization as primary objective", "type": "boolean"},
        {"text": "Covers Google Play fields with correct character limits and indexing rules", "type": "boolean"},
        {"text": "Addresses above-the-fold optimization (first 1-3 lines)", "type": "boolean"},
        {"text": "Recommends A/B testing with Store Listing Experiments", "type": "boolean"},
        {"text": "Shows before/after metadata comparison with character counts", "type": "boolean"},
        {"text": "Includes visual asset recommendations for conversion", "type": "boolean"},
        {"text": "Validates proposed metadata against Google Play prohibited keywords (no 'top', 'best', '#1', 'free', 'download now', etc.) and trademark rules", "type": "boolean"}
      ]
    }
  ]
}

---

Supporting file: references/aso_best_practices.md

ASO Best Practices Reference (2025-2026)

Comprehensive reference for App Store Optimization techniques across Apple App Store and Google Play Store. This document covers keyword strategy, metadata optimization, conversion optimization, localization, and ongoing measurement.

Table of Contents

1. Keyword Strategy (#keyword-strategy)
2. Metadata Optimization — Apple App Store (#metadata-optimization--apple-app-store)
3. Metadata Optimization — Google Play Store (#metadata-optimization--google-play-store)
4. Conversion Rate Optimization (#conversion-rate-optimization)
5. Visual Asset Optimization (#visual-asset-optimization)
6. Localization Best Practices (#localization-best-practices)
7. Ratings & Reviews Strategy (#ratings--reviews-strategy)
8. Algorithm & Ranking Factors (#algorithm--ranking-factors)
9. A/B Testing (#ab-testing)
10. Common Mistakes (#common-mistakes)
11. Character Limits Quick Reference (#character-limits-quick-reference)

---

Keyword Strategy

Research Approach

1. Start with your app's core features — list 10-15 words that describe what your app does
2. Expand with synonyms and related terms — users search in diverse ways
3. Include competitor brand-adjacent terms — keywords their users search for
4. Mix keyword tiers:
   • Head terms (1-2 words, high volume, high competition): e.g., "fitness", "meditation"
   • Mid-tail (2-3 words, moderate volume): e.g., "home workout", "sleep sounds"
   • Long-tail (3+ words, lower volume, high intent): e.g., "7 minute workout timer", "rain sounds for sleep"

Keyword Prioritization Framework

Score each keyword on three dimensions:

• Relevance (1-5): How well does this keyword describe your app?
• Volume (1-5): How many people search for this term? (Use ASO tools for data)
• Difficulty (1-5): How many strong apps compete for this term?

Priority = Relevance × Volume / Difficulty

Target keywords where you score high relevance and volume with manageable difficulty. Avoid high-difficulty keywords unless your app has strong signals (ratings, downloads) to compete.

Long-Tail Keyword Strategy (2025-2026 Focus)

Long-tail keywords have become more valuable because:

• Less competition means faster ranking improvements
• Higher intent means better conversion rates
• Mid-2025 App Store algorithm update now shows results for multiple user intents per search query
• Google Play's semantic understanding matches long-tail queries to relevant apps

How to find long-tail keywords:

• App store autocomplete suggestions
• Competitor review mining (what words do users use?)
• Related searches shown in store results
• Question-based queries ("how to" + your category)

Cross-Field Combination Strategy (iOS)

Apple's search combines words across title, subtitle, and keywords. This means:

• "workout" in title + "home" in keywords = matches "home workout" search
• "meditation" in subtitle + "guided" in keywords = matches "guided meditation" search

Maximize combinations by:

• Placing different high-value words in each indexed field
• Avoiding word repetition across fields (wastes character budget)
• Testing which combinations produce the best ranking results

---

Metadata Optimization — Apple App Store

App Name (30 chars)

• Include your primary keyword alongside the brand name
• Format options: "BrandName - Primary Keyword" or "BrandName: Short Value Prop"
• The name carries the strongest indexation weight
• Keep it readable — don't sacrifice clarity for keyword cramming

Subtitle (30 chars)

• Include your secondary keyword and a benefit
• Complements the title — don't repeat the same words
• Aim for 65%+ character utilization (20+ chars)
• Think of it as a search-optimized tagline

Keywords Field (100 chars)

• Comma-separated, NO spaces after commas
• Never duplicate words from title or subtitle
• Prefer single words over phrases (enables more cross-field combinations)
• Avoid plurals if singular exists (Apple handles stemming)
• Don't include your app name (already indexed)
• Aim for 90%+ character utilization (90+ chars)
• Prioritize by keyword score (relevance × volume / difficulty)

Description (4,000 chars)

• NOT indexed for search, but critical for conversion
• Description keyword coverage matters for conversion rate — users who see their search terms reflected are more likely to download
• Structure: Hook → Features → Social Proof → Call to Action
• First 3 lines visible before "Read More" — make them count
• Use line breaks and formatting for scannability

Promotional Text (170 chars)

• NOT indexed for search
• Updated without app review — use for seasonal messaging, sales, events
• Appears above the description
• Great for time-sensitive promotions

What's New (4,000 chars)

• Shown to existing users and on the app page
• Keep it engaging and specific about improvements
• Echoing keywords naturally can reinforce relevance perception

---

Metadata Optimization — Google Play Store

App Title (30 chars)

• Most heavily weighted field for ranking
• Include primary keyword naturally
• Google's algorithm understands semantic relationships

Short Description (80 chars)

• Visible on the store page before expanding
• Include secondary keyword and value proposition
• Indexed by Google — every word matters

Full Description (4,000 chars)

• Fully indexed by Google — unlike Apple's description
• Natural keyword integration throughout (3-5 mentions of key terms)
• Cover related concepts, use cases, and synonyms
• Google's NLP detects keyword stuffing — write for humans first
• Structure with clear sections for features, benefits, and use cases
• First 1-3 lines are the "above the fold" — front-load value

Developer Name

• Indexed by Google Play — if your developer name contains relevant keywords, it helps

What's New / Changelogs

• Keep changelogs user-friendly and specific
• Mention new features that align with target keywords

---

Conversion Rate Optimization

The Conversion Funnel

Search Results → App Page View → Install → First Launch → Retention

Each stage matters for ASO because stores reward apps that convert well and retain users.

First Impression Elements (in order of impact)

1. App Icon — The single most viewed element; must communicate purpose at 60x60px
2. App Name — Clarity + keyword = discoverability + understanding
3. Rating & Review Count — Social proof drives trust (90% of featured apps are 4.0+)
4. First Screenshot — Often visible in search results; must hook immediately
5. Subtitle / Short Description — Value prop in a few words

Conversion Rate Benchmarks

• Average App Store CVR: 25-35% (varies by category)
• Average Google Play CVR: 20-30%
• Apps that improved from 3.6 to 4.2 rating saw ~60% higher conversion
• Custom Product Pages (iOS) boost CVR by avg. 5.9%, up to 8.6% for generic campaigns

---

Visual Asset Optimization

App Icon

• Must be recognizable at 16x16px and look good at 1024x1024px
• Use bold, simple shapes — avoid photographic detail or text
• Color contrast should stand out against both light and dark backgrounds
• Research category conventions (e.g., game icons tend to be more detailed)

Screenshots

• Order matters: Lead with the single most compelling feature
• First 2-3 screenshots: Visible in search results — they must tell the story
• Captions: Include keywords in caption text (OCR-indexed on App Store since June 2025)
• Show real app UI — not just marketing graphics
• Highlight value propositions — each screenshot should answer "why should I download?"
• Optimal count: 8-10 screenshots covering core features, edge cases, and social proof

Preview Video

• First 3 seconds are auto-played in search results — lead with the best moment
• Show the app in action, not a cinematic trailer
• Keep under 30 seconds for maximum engagement
• Include captions/text for silent auto-play

---

Localization Best Practices

Market Prioritization

Rank markets by: (1) market size for your category, (2) competition level, (3) localization effort required.

Localization vs. Translation

• Translation: Converting text to another language (minimum viable)
• Localization: Adapting content to cultural context, local search behavior, and market norms (recommended)
• Transcreation: Recreating the message entirely for the local market (premium, for top markets)

Keyword Localization Rules

• Never just translate your English keywords 1:1 — research what local users actually search for
• Keyword popularity varies dramatically across markets (a keyword with 70 popularity in the US may have 5 in France)
• Local competitors differ — run competitor analysis per market
• Consider character encoding: some languages need more characters for the same meaning

Key Markets by App Store Revenue (2025-2026)

1. United States (en-US)
2. China (zh-Hans)
3. Japan (ja)
4. United Kingdom (en-GB)
5. South Korea (ko)
6. Germany (de-DE)
7. France (fr-FR)
8. Brazil (pt-BR)
9. Canada (en-CA, fr-CA)
10. Australia (en-AU)

Non-Latin Script Considerations

• Arabic: ال-prefix normalization, right-to-left layout, hamza variants in search
• Chinese: No word-separating spaces; tokenize by 、 or ，
• Japanese: Mix of kanji, hiragana, katakana affects search matching
• Korean: Hangul decomposition may affect search indexing
• Cyrillic: Include Latin transliterations for users who search in Latin script

---

Ratings & Reviews Strategy

Why Ratings Matter for ASO

• Apps rated 4.0+ are 3x more likely to be featured
• Rating directly impacts conversion rate
• Review text is indexed by Google Play (not Apple)

In-App Review Prompt Strategy

• When to prompt: After a positive action (completed task, achievement, 3rd session)
• When NOT to prompt: After errors, crashes, or during onboarding
• Frequency: Max once per 30 days; respect "don't ask again"
• Use native API: SKStoreReviewController (iOS) / ReviewManager (Android)

Review Response Strategy

• Respond to negative reviews within 24 hours
• Address the issue specifically, not with templates
• Updated reviews (after fixes) improve aggregate rating
• Thank positive reviewers — it encourages more reviews

---

Algorithm & Ranking Factors

Apple App Store (2025-2026)

1. Keyword relevance — metadata match to search query
2. Download velocity — recent install rate relative to category
3. Conversion rate — impression-to-install ratio
4. Rating & review quality — aggregate score and recent trends
5. Update frequency — regularly updated apps rank better
6. Engagement & retention — post-install usage signals

Mid-2025 Algorithm Change: Search results now reflect multiple user intents for a single query. The first 10-15 results may include apps targeting different interpretations of the search term. This means niche apps can rank alongside broader competitors.

Google Play Store (2025-2026)

1. Keyword relevance — all text fields indexed, semantic matching
2. Install velocity — first 48 hours post-update are critical
3. App quality signals — crash rate (ANR), stability, performance
4. User engagement — retention, session length, uninstall rate
5. Rating & review volume — both score and recency matter
6. Update frequency — Google favors actively maintained apps
7. Backlinks and web presence — deep linking and SEO overlap

2026 Trend: Google is moving toward theme-based keyword understanding and video-rich listings. AI-driven discovery blurs the line between ASO and SEO.

---

A/B Testing

Apple App Store

• Custom Product Pages (CPPs): Up to 35 custom pages with unique screenshots, previews, and promotional text
• Product Page Optimization (PPO): A/B test default page elements (icon, screenshots, preview)
• CPPs average +5.9% CVR improvement; generic campaigns see +8.6%

Google Play Store

• Store Listing Experiments: Test up to 5 variants of any listing element
• Test icon, screenshots, descriptions, short description
• Run for minimum 7 days with statistical significance before deciding

What to Test (Priority Order)

1. Screenshots (ordering and design)
2. App icon
3. Short description / subtitle
4. Description first paragraph
5. Preview video vs. no video

---

Store Policy Compliance

Both Apple and Google enforce strict metadata policies. Violating these policies can result in app rejection, removal from the store, or developer account termination. Always validate metadata against these rules before submission.

Apple App Store — Prohibited Metadata (Guidelines 2.3.7, 2.3.8, 5.2.1)

Banned Words and Phrases in Title, Subtitle, and Keywords

• "free" — pricing terms are not allowed in visible metadata
• "best", "#1", "top-rated", "must-have" — unverifiable superlative claims
• "#1 in the world", "top app" — ranking claims cannot be verified
• "limited time", "sale", "discount" — promotional/pricing language
• "For Kids", "For Children" — reserved exclusively for the Kids Category
• "Editor's Choice" — reserved; only Apple applies this badge automatically

Trademark and Competitor Restrictions

• Competitor brand names — cannot appear in title, subtitle, keywords, or description (e.g., using "WhatsApp" in a messaging app's keywords)
• Trademarked terms you don't own or license — Apple explicitly prohibits this under guideline 2.3.7
• Celebrity names — unless you have explicit authorization
• Apple trademarks — cannot suggest Apple endorsement or source relationship (guideline 5.2.4)
• Consequences: Apple may silently de-index offending keywords, reject the update, remove the app, or terminate the developer account. Trademark owners can file disputes via Apple's App Store dispute form

Content Restrictions

• Other platform names — "Android", "Google Play", "Play Store" prohibited in iOS metadata (guideline 2.3.10)
• Emojis and special characters — not allowed in app name, subtitle, or keywords
• ALL CAPS — not permitted unless it's the actual brand name
• Unverifiable claims — "fastest", "most popular", "award-winning" without evidence
• Misleading descriptions — describing features the app doesn't have
• Placeholder/generic text — unfinished or default metadata
• Repetition — repeating the app name in subtitle or keywords wastes budget and may be flagged

Metadata Accuracy Requirements (Guideline 2.3)

• Screenshots must show the app in actual use — no title art, splash screens, or login pages only
• Preview videos must use actual app screen captures
• Description must accurately reflect app functionality
• In-app purchases and subscriptions must be clearly disclosed
• Age rating must be honest and accurate

Google Play Store — Prohibited Metadata

Banned Words and Phrases in Title, Short Description, Developer Name, and Icon

• "top", "best", "#1", "number one" — store performance claims
• "free", "no ads", "ad free" — pricing/promotional terms
• "new", "hot", "first", "bonus" — promotional language
• "discount", "sale", "million downloads" — promotional claims
• "App of the Year", "Best Google Play App of 20XX", "Popular" — ranking claims
• "download now", "install now", "play now", "try now", "update now" — call-to-action phrases

Trademark and Competitor Restrictions

• Competitor brand names — cannot be used in title, short description, or full description to mislead users
• Trademarked terms — trademark owners can file complaints, leading to enforcement
• Misleading developer names — developer name cannot impersonate another entity
• Consequences: Google may remove the app listing, suspend the developer account, or restrict future submissions. Trademark complaints trigger review and potential enforcement

Formatting and Content Restrictions

• Emojis and emoticons — prohibited in title, icon, and developer name
• Repeated special characters — not allowed
• ALL CAPS — prohibited unless part of the official brand name
• Unattributed user testimonials — cannot include fake or unattributed reviews in metadata
• Graphic elements suggesting rankings — no trophy emojis, medal icons, or badges implying store ranking
• Keyword stuffing — Google's algorithm detects and penalizes repetitive or unrelated keywords; this includes excessive repetition in the full description
• Misleading information — descriptions of features the app doesn't provide

Description-Specific Rules

• Avoid excessive length, irrelevant detail, or improper formatting
• Maintain natural readability — Google's NLP detects unnatural keyword cramming
• Do not list keywords as comma-separated blocks in the description
• Do not repeat keywords more than 5 times across all fields

Both Stores — Universal Rules

---

Common Mistakes

1. Keyword stuffing — Cramming keywords unnaturally hurts readability and can trigger penalties (Google Play) or rejection (both stores)
2. Using competitor trademarks — Including competitor brand names in metadata violates both Apple (2.3.7, 5.2.1) and Google Play policies and can lead to app removal or legal action
3. Prohibited words in title — Using "free", "best", "#1", "top" in titles causes immediate rejection on both stores
4. Duplicating words across indexed fields (iOS) — Wastes character budget; Apple indexes title + subtitle + keywords together
5. Translating instead of localizing — Direct translation misses local search behavior
6. Ignoring the "above the fold" — Users see only the first 1-3 lines before "Read More"
7. Set and forget — ASO requires ongoing iteration as competition and algorithms change
8. Optimizing for search only — High visibility with low conversion wastes potential
9. Neglecting ratings — A 3.5-star app converts dramatically worse than a 4.2-star app
10. Spaces after commas in iOS keywords — Each space wastes a character of your 100-char budget
11. Not using all screenshot slots — Empty slots are missed conversion opportunities
12. Same metadata across all locales — Signals lazy localization to both algorithms and users
13. Unverifiable superlative claims — "Fastest", "most popular", "award-winning" without evidence triggers rejection
14. Emojis and special characters in titles — Both stores now prohibit these in titles and subtitles

---

Character Limits Quick Reference

Apple App Store

Google Play Store

---

Supporting file: references/edge-cases.md

Edge Cases and Platform Notes

Edge Cases

• No local metadata files — App has no metadata/, fastlane/, or equivalent. Create the canonical directory structure and write optimized files from scratch, then provide upload instructions.
• Single-platform app — Skip phases for the irrelevant store. Do not propose a keywords field for Android (it has none).
• No competitor access — Skip Phase 1.3; base keyword strategy on app features alone. Flag this gap in the analysis report.
• Unverifiable keyword volume data — Proceed with heuristic priority (feature-specific over generic, long-tail over head terms) and note the limitation.
• Pre-launch app — No live listing. Skip performance-baseline steps; focus on metadata creation and visual guidance.
• Metadata policy violation in proposed plan — Compliance check (Phase 3) catches a prohibited term. Revise the plan silently, replace the violation, re-run compliance, present the corrected plan.
• Non-English primary locale — Adapt all metadata templates, character limits, and keyword strategies to the target language.
• User rejects the plan — Do not execute. Iterate in Phase 2, then re-run Phase 3 compliance check before presenting the revised plan.

Platform-Specific Notes

Apple App Store

• 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

Google Play Store

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

Both Stores

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

Acceptance Criteria

A run is successful when all are verifiable:

• Description ≤40 words with imperative verb — Frontmatter passes asm eval check.
• Analysis report produced — App Overview, Metadata Status table, Key Findings.
• ASO plan covers all required fields — Title, subtitle/short desc, keywords (iOS), full description, visual recommendations.
• Compliance check ran and passed — Phase 3 report present and PASS before plan shown.
• User approval gate respected — Phase 4 does not begin until explicit approval.
• All metadata fields within character limits — Title ≤30, subtitle ≤30, iOS keywords ≤100, Android short desc ≤80, full desc ≤4000.
• No prohibited keywords in any output metadata — Zero banned terms.
• No trademark violations — No competitor brand names anywhere.
• iOS keywords field has no duplicates with title/subtitle.
• Metadata files written — At least one file or correct directory structure exists.
• Summary report produced — Changes Made, Metadata Comparison, Compliance, Next Steps.

Step Completion Reports

After each major step, output:

◆ [Step Name] ([step N of M] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          √ pass (note if relevant)
  [Check 3]:          × fail — [reason]
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

Skill-specific checks per phase

• Phase: Analyze (Phase 1) — Current state analysis, Metadata audit complete, Competitive landscape identified, Baseline documented
• Phase: Plan + Compliance (Phases 2-3) — Plan completeness, Policy compliance, Prohibited keyword scan, Trademark check
• Phase: Execute (Phase 4) — Metadata fields updated, Character limits respected, Keywords correctly formatted, Implementation quality
• Phase: Review + Verify (Phases 5-6) — No policy violations re-introduced, Best practices met, Cross-field keyword combinations valid, Localization market-aware

Cross-Skill Integration

Works well combined with:

• asc-aso-audit — Detailed offline iOS metadata audit
• asc-localize-metadata — Bulk localization across locales
• asc-metadata-sync — Sync local metadata with App Store Connect
• asc-whats-new-writer — Generate engaging release notes
• asc-shots-pipeline — Automated screenshot capture
• seo-ai-optimizer — Align ASO and SEO keyword strategies

---

Supporting file: references/expected-output.md

Expected Output Examples

A complete run produces three artifacts.

1. ASO Analysis Report (Phase 1)

## ASO Analysis Report

### App Overview
- 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

### Current Metadata Status
| Field      | Platform | Current Value                    | Length | Limit | Usage % | Issues                       |
|------------|----------|----------------------------------|--------|-------|---------|------------------------------|
| Title      | iOS      | FocusFlow: Work Timer            | 22     | 30    | 73%     | No primary keyword in title  |
| Keywords   | iOS      | timer,focus,work,productivity    | 34     | 100   | 34%     | 66 chars unused              |
| Short Desc | Android  | A simple timer for focused work. | 36     | 80    | 45%     | Weak value prop, low density |

2. ASO Plan + Compliance Report + Updated Metadata Files (Phases 2-4)

Example metadata/app-info/en-US.json after execution:

{
  "name": "FocusFlow: Focus & Work Timer",
  "subtitle": "Deep Work Sessions & Tracking"
}

Example iOS keywords field (Phase 4):

pomodoro,deep,work,concentration,study,block,distraction,habit,goal,flow,task

(97/100 chars, all prohibited terms cleared, no title/subtitle duplicates)

3. ASO Marketing Summary Report (Phase 7)

## ASO Marketing Summary Report

### Changes Made
| # | Area         | Change                          | Before                        | After                          | Expected Impact              |
|---|--------------|---------------------------------|-------------------------------|--------------------------------|------------------------------|
| 1 | iOS Title    | Added primary keyword           | FocusFlow: Work Timer         | FocusFlow: Focus & Work Timer  | +rankings for "focus timer"  |
| 2 | iOS Keywords | Expanded from 34 to 97 chars    | timer,focus,work,productivity | pomodoro,deep,work,...         | 3x more indexable queries    |
| 3 | Android Desc | Rewrote opening hook + keywords | A simple timer for focused... | Block distractions. Build...   | Higher conversion rate       |

### Store Policy Compliance
- 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

---

Supporting file: references/phase-3-compliance.md

Phase 3: Policy Compliance Check

Validate every piece of proposed metadata against Apple App Store and Google Play Store policies before presenting the plan.

3.1 Prohibited Keyword Scan

Check all proposed metadata fields (title, subtitle, keywords, short description, full description) for prohibited terms.

Apple App Store — Banned in title, subtitle, and keywords:

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

Google Play — Banned in title, short description, developer name, and icon:

• 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"

3.2 Trademark and Competitor Check

Scan all proposed metadata for:

• Competitor brand names — Must be removed from title, subtitle, keywords, 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

3.3 Formatting Compliance

• No emojis or special characters in title/subtitle (both stores)
• No ALL CAPS in title/subtitle unless 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)

3.4 Content Accuracy Check

• No unverifiable claims ("fastest", "most popular", "award-winning" without evidence)
• Description accurately reflects app features
• Screenshots show the actual app in use
• In-app purchases and subscriptions clearly disclosed
• No misleading descriptions of app functionality

3.5 Compliance Report Template

## Store Policy Compliance Report

### Prohibited Keyword Check
| Proposed Term | Field | Store | Status | Issue | Fix |

### Trademark Check
| Term | Field | Risk Level | Action |

### Formatting Check
- [x] or [ ] for each formatting rule

### Content Accuracy Check
- [x] or [ ] for each accuracy rule

### Overall Status: PASS / NEEDS REVISION

If any violations are found, revise the plan to fix all issues before presenting to the user.

Present for Approval

After the compliance check passes, present both the ASO plan and the compliance report:

"Here's the ASO plan based on my analysis. All proposed metadata has been validated — 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"

Do not proceed to Phase 4 until the user explicitly approves the plan. Each revision must pass the compliance check again.

---

Supporting file: references/phases-1-2.md

Phases 1-2: Analysis and Planning

Phase 1: Analyze the Current State

The analysis phase gathers everything needed to build an informed ASO plan.

1.1 Codebase & Project Analysis

Understand what the app does by reading the codebase:

• 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)

1.2 Existing Store Metadata Audit

If metadata files exist locally:

• 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

If the asc-aso-audit skill is available, recommend running it first for iOS metadata.

1.3 Competitive Landscape

Ask the user to identify 3-5 direct competitors. For each:

• Note their app name, subtitle/short description, and apparent keyword strategy
• Identify what makes them rank well
• Look for gaps — keywords they miss

Trademark warning: Competitive analysis is for strategic insight only. Never carry competitor brand names into proposed metadata.

1.4 Current Performance Baseline

If available, gather:

• Current keyword rankings
• Download/install numbers and trends
• Ratings and review sentiment
• Conversion rate (impressions → installs)

1.5 Analysis Report Template

## ASO Analysis Report

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

### Current Metadata Status
| Field | Platform | Current Value | Length | Limit | Usage % | Issues |
|-------|----------|---------------|--------|-------|---------|--------|

### Competitive Landscape
| Competitor | Platform | Keywords in Title | Rating | Apparent Strategy |
|-----------|----------|-------------------|--------|-------------------|

### Key Findings
1. [Finding 1 — most impactful]

### Opportunities
1. [Opportunity 1 — highest potential impact]

---

Phase 2: Propose the ASO Plan

Build a prioritized, actionable plan based on the analysis.

Plan Template

## ASO Marketing Plan

### Objectives
- Primary: [e.g., "Increase organic installs"]
- Secondary: [e.g., "Improve conversion rate"]

### Target Keywords
#### Primary Keywords (high volume, core relevance)
| Keyword/Phrase | Est. Volume | Competition | Target Field | Rationale |

#### Secondary Keywords (moderate volume, good fit)
| Keyword/Phrase | Est. Volume | Competition | Target Field | Rationale |

#### Long-Tail Keywords (lower volume, high intent)
| Keyword/Phrase | Est. Volume | Competition | Target Field | Rationale |

### Metadata Optimization Plan

#### App Name / Title
- Current: "[current]"
- Proposed: "[proposed]"
- Rationale: [why this change improves discoverability]

#### Subtitle (iOS) / Short Description (Android)
- Current: "[current]"
- Proposed: "[proposed]"
- Rationale: [keyword + conversion reasoning]

#### Keywords Field (iOS only)
- Current: "[current]"
- Proposed: "[proposed]"
- Characters used: [X/100]
- Cross-field combinations enabled: [list key search queries]

#### Description / Full Description
- Key changes: [what to add/remove/restructure]
- Keyword integration points
- Conversion optimization

#### What's New / Release Notes
- Strategy

### Visual Asset Recommendations
- **App Icon:** [assessment and suggestions]
- **Screenshots:** [ordering, messaging, keyword captions]
- **Preview Video:** [if applicable]

### Localization Strategy
- Priority markets: [ranked by opportunity]
- Localization approach per market

### Ratings & Reviews Strategy
- Current rating, target rating, actions

### Timeline & Priorities
| Priority | Action | Impact | Effort | Timeline |
| P0 | [highest impact, do first] | High | Low | Week 1 |

Iteration Gate

Present the plan to the user and ask for approval — but only after the policy compliance check (Phase 3) has validated all proposed metadata.

---

Supporting file: references/phases-4-7.md

Phases 4-7: Execute, Review, Verify, Summarize

Phase 4: Execute the Plan

Once the user approves, implement the changes systematically. Work through the priority list in order.

4.1 Metadata Updates

App Store (iOS):

• 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

Google Play (Android):

• Update title.txt (max 30 chars)
• Update short_description.txt (max 80 chars)
• Update full_description.txt (max 4,000 chars)
• Update changelogs if applicable

Backup-first rule: Before overwriting any existing metadata file, create a .bak copy in the same directory or confirm the user has the file in version control. Do not overwrite or delete files without confirmation.

4.2 Keyword Implementation

Store Policy Compliance (MUST CHECK FIRST):

• Never use prohibited terms (see phase-3-compliance.md)
• Never use competitor brand names or trademarks
• Never use unverifiable superlatives
• Never use pricing/promotional language

Apple App Store keyword field:

• Comma-separated, no spaces after commas
• Never duplicate words from title or subtitle
• Prefer single words over phrases
• Aim for 90%+ character utilization
• Consider cross-field combinations

Google Play keywords:

• Keywords go naturally into title, short description, and full description
• Repeat important keywords 3-5 times across fields (natural usage)
• Long description should cover related concepts and use cases
• Prioritize readability — Google detects stuffing

4.3 Description Optimization

• First 1-3 lines are critical (visible before "Read More")
• Lead with strongest value proposition and clear CTA
• Use bullet points or short paragraphs for scannability
• Naturally integrate target keywords
• Include social proof if available

4.4 Localization Execution

• Research locale-specific keywords (not just translations)
• Adapt messaging to local culture and usage patterns
• Verify character limits in target language

4.5 Visual Asset Guidance

• Screenshots: Recommend ordering, caption text with keywords (OCR-indexed on App Store since June 2025)
• App Icon: Assess clarity at small sizes, color contrast
• Preview Video: First 3 seconds matter most

---

Phase 5: Review

Review Checklist

• All metadata fields within character limits
• No keyword duplication across indexed fields (iOS)
• Keywords field properly formatted
• Descriptions read naturally
• No spelling/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
• No prohibited keywords (re-scan all fields)
• No competitor trademarks
• No unverifiable claims
• No platform references
• No formatting violations
• Accurate feature descriptions

Self-Audit

Re-run Phase 1 analysis checks on updated metadata to verify improvements.

---

Phase 6: Verify Against Best Practices

Cross-reference against references/aso_best_practices.md:

• Title/name includes primary keyword
• Subtitle/short description includes secondary keyword + value prop
• Keywords field maximizes character budget (iOS)
• Description is conversion-optimized
• Localization is market-aware
• Visual assets support conversion
• Rating/review strategy addressed
• All metadata passes Store Policy Compliance rules
• No trademark violations
• No prohibited keywords

---

Phase 7: Summarize

Summary Report Template

## ASO Marketing Summary Report

### Changes Made
| # | Area | Change | Before | After | Expected Impact |

### Metadata Comparison
| Field | Platform | Before | After | Improvement |

### Keyword Strategy Summary
- Total unique keywords targeted
- Primary keywords
- Cross-field combinations enabled
- Keyword field utilization

### Store Policy Compliance
- Prohibited keyword check: PASS
- Trademark check: PASS
- Formatting check: PASS
- Content accuracy check: PASS
- Overall compliance: PASS for [App Store / Google Play / Both]

### Expected Outcomes
- [Outcome 1, 2, ...]

### Next Steps
1. Upload metadata to the store(s)
2. Monitor rankings for target keywords after 1-2 weeks
3. A/B test screenshots and descriptions
4. Re-run this skill in 4-6 weeks

### Files Modified
- [list all files created or modified with paths]