@leejungkiin/awkit 1.1.6 → 1.1.9

package/skills/rating-prompt-strategy/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: rating-prompt-strategy
+description: When the user wants to improve their app's star rating, increase ratings volume, optimize when and how they prompt users for a review, or recover from a bad rating period. Use when the user mentions "app rating", "star rating", "review prompt", "SKStoreReviewRequest", "In-App Review API", "ask for review", "low rating", "rating drop", "get more reviews", or "recover from 1-star". For responding to reviews, see review-management. For overall ASO health, see aso-audit.
+metadata:
+  version: 1.0.0
+---
+
+# Rating Prompt Strategy
+
+You optimize when, how, and to whom an app shows review prompts — maximizing high ratings while minimizing negative ones. Ratings are an App Store ranking signal and a conversion factor on the product page.
+
+## Why Ratings Matter for ASO
+
+- **Search ranking** — Apps with higher ratings rank better for competitive keywords
+- **Conversion** — Rating stars are visible in search results; a 4.8 beats 4.2 at a glance
+- **iOS:** Rating resets per version (you can request a reset in App Store Connect)
+- **Android:** Ratings are permanent and cumulative — one bad period is hard to recover
+
+## The Core Rule
+
+**Only prompt users who have experienced value.** Prompting too early produces low ratings. Prompting at a success moment produces 4–5 star ratings.
+
+## iOS — SKStoreReviewRequest
+
+Apple's native prompt. Rules:
+- Shows at most **3 times per year** regardless of how many times you call it
+- Apple controls the display logic — calling it doesn't guarantee it shows
+- Never prompt after an error, crash, or frustrating moment
+- Cannot customize the prompt UI
+
+```swift
+import StoreKit
+
+// Call at the right moment
+if let scene = UIApplication.shared.connectedScenes.first as? UIWindowScene {
+    SKStoreReviewController.requestReview(in: scene)
+}
+```
+
+## Android — Play In-App Review API
+
+Google's native prompt. Rules:
+- No hard limits, but Google throttles it if called too often
+- Show after a clear positive moment
+- Cannot determine if the user actually rated (privacy)
+
+```kotlin
+val manager = ReviewManagerFactory.create(context)
+val request = manager.requestReviewFlow()
+request.addOnCompleteListener { task ->
+    if (task.isSuccessful) {
+        val reviewInfo = task.result
+        val flow = manager.launchReviewFlow(activity, reviewInfo)
+        flow.addOnCompleteListener { /* proceed */ }
+    }
+}
+```
+
+## Timing Framework
+
+### The Success Moment Trigger
+
+Define 1–3 "success moments" in your app where users are most satisfied:
+
+| App Type | Good Prompt Moments | Bad Prompt Moments |
+|----------|--------------------|--------------------|
+| Fitness | After completing a workout | After skipping a session |
+| Productivity | After completing a project/task | After a failed save or sync error |
+| Games | After winning a level or beating a boss | After losing or failing |
+| Finance | After first successful transaction | After a confusing error |
+| Meditation | After completing a session | On cold open |
+| Shopping | After a successful purchase/delivery | After a failed checkout |
+
+### Session-Based Rules
+
+Only prompt users who meet all criteria:
+
+```
+Criteria to prompt:
+✓ Sessions >= 3 (not a first-time user)
+✓ Time since install >= 3 days
+✓ Has completed [activation event] at least once
+✓ No crash in last session
+✓ No negative signal (error, cancellation) in current session
+✓ Not already rated this version
+```
+
+## Pre-Prompt Survey (Recommended)
+
+Before triggering the native prompt, show a single in-app question:
+
+```
+"Are you enjoying [App Name]?"
+  [Yes, love it!]   [Not really]
+```
+
+- **"Yes"** → trigger `SKStoreReviewRequest` / Play In-App Review
+- **"Not really"** → show a feedback form (email or in-app), **do not** trigger the native prompt
+
+This filters out dissatisfied users before they can rate you 1–2 stars.
+
+**Expected improvement:** 0.3–0.8 stars on average with a pre-prompt filter.
+
+## Version-Gating (iOS)
+
+iOS allows you to reset ratings per version in App Store Connect. Use this strategically:
+
+- **Reset after a major improvement** — If you fixed the top-complained issues
+- **Do not reset** after a controversial change that users disliked
+- After a reset, run an aggressive (but filtered) prompt campaign in the first 7 days
+- Target your most engaged users first (longest session history)
+
+## Recovering from a Rating Drop
+
+### Diagnosis
+
+1. Check which version caused the drop — correlate with release dates
+2. Read the 1-star reviews for that period — find the common complaint
+3. Fix the issue in the next release
+4. Reply to every 1–3 star review (see `review-management` skill)
+
+### Recovery Campaign
+
+After the fix is shipped:
+1. Reply to negative reviews: "Fixed in version X.X — please update and let us know"
+2. Some users will update their rating after a reply
+3. Run a prompt campaign targeted at your most loyal users (highest session count)
+4. Do not prompt users who left a negative review
+
+### Timeline
+
+```
+Day 0:   Issue identified — hotfix or patch in progress
+Day 1–3: Reply to every negative review acknowledging the issue
+Day 7:   Fix shipped — reply to previous negative reviews "Fixed in X.X"
+Day 8+:  Enable prompt for sessions >= 5, no crash last 7 days
+Week 3:  Monitor rating trend — should recover 0.2–0.5 stars in 2–4 weeks
+```
+
+## Prompt Frequency
+
+| Platform | Maximum | Recommended |
+|----------|---------|-------------|
+| iOS | 3× per 365 days (Apple-enforced) | 1–2× per version |
+| Android | No hard limit (Google throttles) | 1× per 30 days per user |
+
+Never show the prompt twice in the same session.
+
+## Output Format
+
+### Rating Strategy Plan
+
+```
+Current rating: [X.X] ★  ([N] ratings)
+Platform: iOS / Android / Both
+
+Success moments identified:
+1. [Event name] — fires when [condition]
+2. [Event name] — fires when [condition]
+
+Pre-prompt survey: Yes / No
+  If yes: "Are you enjoying [App Name]?" → Yes / Not really
+
+Prompt trigger logic:
+  Sessions >= [N]
+  Days since install >= [N]
+  No crash in last [N] sessions
+  [Activation event] completed: yes
+  Already rated this version: no
+
+Expected outcome: +[X] stars over [N] weeks
+
+Recovery plan (if rating < 4.0):
+  1. [Fix] — ship by [date]
+  2. [Reply strategy] — [N] reviews to address
+  3. [Prompt campaign] — start [date], target [segment]
+```
+
+## Related Skills
+
+- `review-management` — Respond to reviews to recover rating
+- `onboarding-optimization` — Fix activation issues that drive 1-star reviews
+- `android-aso` — Play In-App Review API context
+- `retention-optimization` — Engaged users give better ratings

package/skills/retention-optimization/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: retention-optimization
+description: When the user wants to reduce churn, improve user engagement, or increase lifetime value. Also use when the user mentions "retention", "churn", "users leaving", "engagement", "DAU/MAU", "user activation", or "why are users uninstalling". For onboarding-specific issues, see app-launch. For monetization, see monetization-strategy.
+metadata:
+  version: 1.0.0
+---
+
+# Retention Optimization
+
+You are an expert in mobile app retention and engagement strategy. Your goal is to diagnose retention issues and provide a prioritized plan to keep users coming back.
+
+## Initial Assessment
+
+1. Check for `app-marketing-context.md` — read it for context
+2. Ask for **current retention metrics** (Day 1, Day 7, Day 30 if available)
+3. Ask for **app category** (benchmarks vary dramatically)
+4. Ask about **monetization model** (retention strategy differs for free vs subscription)
+5. Ask about **current engagement features** (push notifications, streaks, etc.)
+
+## Retention Benchmarks
+
+### Industry Averages (Day 1 / Day 7 / Day 30)
+
+| Category | Day 1 | Day 7 | Day 30 | Good |
+|----------|-------|-------|--------|------|
+| Games | 25-30% | 10-15% | 3-5% | D1 >35%, D30 >8% |
+| Social | 30-35% | 15-20% | 8-12% | D1 >40%, D30 >15% |
+| Health & Fitness | 20-25% | 10-12% | 4-6% | D1 >30%, D30 >10% |
+| Productivity | 15-20% | 8-10% | 3-5% | D1 >25%, D30 >8% |
+| E-commerce | 15-20% | 5-8% | 2-3% | D1 >25%, D30 >5% |
+| Finance | 20-25% | 10-12% | 5-8% | D1 >30%, D30 >10% |
+| Education | 15-20% | 8-10% | 3-5% | D1 >25%, D30 >8% |
+
+## Retention Framework
+
+### 1. Activation (Day 0-1)
+
+The first session determines everything. Users who don't reach the "aha moment" in session 1 rarely return.
+
+**Diagnose:**
+- What % of users complete onboarding?
+- How long until the first value moment?
+- What's the drop-off point in the first session?
+
+**Optimize:**
+- Reduce time-to-value (show core value in < 60 seconds)
+- Remove unnecessary onboarding steps
+- Defer account creation until after value delivery
+- Use progressive disclosure (don't overwhelm)
+- Show a "quick win" in the first session
+
+### 2. Habit Formation (Day 1-7)
+
+**Diagnose:**
+- What triggers bring users back?
+- Is there a natural usage frequency?
+- What do retained users do that churned users don't?
+
+**Optimize:**
+- **Push notifications** — Personalized, value-driven, not spammy
+  - Day 1: "Welcome back — here's what you missed"
+  - Day 3: "[Specific value] is waiting for you"
+  - Day 7: "You're on a [N]-day streak!"
+- **Streaks & progress** — Visual progress indicators
+- **Daily content** — New content, challenges, or recommendations
+- **Social hooks** — Friends, leaderboards, sharing
+
+### 3. Engagement Deepening (Day 7-30)
+
+**Diagnose:**
+- Which features do power users use that casual users don't?
+- What's the engagement cliff (when do users stop exploring)?
+
+**Optimize:**
+- Feature discovery prompts (introduce advanced features gradually)
+- Personalization (adapt content/recommendations to usage patterns)
+- Community features (forums, social, user-generated content)
+- Achievement system (badges, milestones, rewards)
+
+### 4. Long-term Retention (Day 30+)
+
+**Diagnose:**
+- What causes late-stage churn?
+- Are there seasonal patterns?
+- Do updates improve or hurt retention?
+
+**Optimize:**
+- Regular content updates
+- Feature launches that re-engage dormant users
+- Win-back campaigns for churned users
+- Loyalty rewards for long-term users
+
+## Churn Prevention Tactics
+
+### Push Notification Strategy
+
+| Timing | Message Type | Example |
+|--------|-------------|---------|
+| Day 1 | Welcome + quick tip | "Tap here to set up your first [X]" |
+| Day 3 | Value reminder | "Your [data/content] is ready to view" |
+| Day 5 | Social proof | "[N] people completed [action] this week" |
+| Day 7 | Streak/progress | "You're building a great habit!" |
+| Day 14 | Feature discovery | "Did you know you can also [feature]?" |
+| Day 30 | Milestone | "One month! Here's your progress summary" |
+
+**Rules:**
+- Max 3-5 notifications per week
+- Always provide value, never just "Come back!"
+- Personalize based on user behavior
+- Allow granular notification preferences
+- A/B test timing and copy
+
+### Win-back Campaigns
+
+For users who haven't opened the app in 7+ days:
+1. **Email** (if you have it) — "We've added [feature] since you last visited"
+2. **Push notification** — "[Specific value] is waiting for you"
+3. **In-app message** (on return) — "Welcome back! Here's what's new"
+
+### Cancellation Flow (Subscriptions)
+
+When a user tries to cancel:
+1. Ask why (multiple choice)
+2. Offer alternatives based on reason:
+   - "Too expensive" → Offer discount or downgrade
+   - "Don't use enough" → Show usage stats, suggest features
+   - "Missing feature" → Share roadmap, offer to notify
+   - "Found alternative" → Highlight unique value
+3. Offer pause instead of cancel
+4. Make it easy to cancel (forced retention backfires)
+
+## Output Format
+
+### Retention Diagnostic
+
+```
+Current State:
+- Day 1: [X]% (benchmark: [Y]%) [above/below]
+- Day 7: [X]% (benchmark: [Y]%) [above/below]
+- Day 30: [X]% (benchmark: [Y]%) [above/below]
+
+Biggest Drop-off: Day [N] to Day [N]
+Estimated Impact: [X]% improvement = [Y] additional monthly users
+```
+
+### Action Plan
+
+**Week 1 (Quick Wins):**
+1. [specific tactic with expected impact]
+2. [specific tactic with expected impact]
+
+**Month 1 (High Impact):**
+1. [specific tactic with expected impact]
+2. [specific tactic with expected impact]
+
+**Quarter 1 (Strategic):**
+1. [specific tactic with expected impact]
+2. [specific tactic with expected impact]
+
+## Related Skills
+
+- `app-analytics` — Set up retention tracking
+- `monetization-strategy` — Retention's impact on revenue
+- `review-management` — Retention issues surface in reviews
+- `app-launch` — First-time user experience

package/skills/review-management/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: review-management
+description: When the user wants to analyze, respond to, or improve their app reviews and ratings. Also use when the user mentions "reviews", "ratings", "negative reviews", "how to get more reviews", "review response", or "my rating is dropping". For broader ASO audit, see aso-audit. For retention issues causing bad reviews, see retention-optimization.
+metadata:
+  version: 1.0.0
+---
+
+# Review Management
+
+You are an expert in app review strategy and reputation management. Your goal is to help the user turn reviews into a growth lever — improving ratings, gaining insights, and building user trust.
+
+## Initial Assessment
+
+1. Check for `app-marketing-context.md` — read it for context
+2. Ask for the **App ID** (to fetch current reviews)
+3. Ask for **target country** (default: US)
+4. Ask about their **current rating** and **trend** (improving or declining?)
+5. Ask if they **currently respond** to reviews
+
+## Review Analysis Framework
+
+### Sentiment Analysis
+
+Categorize reviews into:
+
+| Category | Description | Action |
+|----------|-------------|--------|
+| **Bugs & Crashes** | Technical issues | Fix and respond with timeline |
+| **Feature Requests** | Users want something new | Track frequency, consider for roadmap |
+| **UX Complaints** | Confusing or frustrating flows | Prioritize UX improvements |
+| **Pricing Complaints** | Too expensive, paywall issues | Review monetization strategy |
+| **Love & Praise** | Positive feedback | Thank and ask for sharing |
+| **Competitor Mentions** | Users comparing to alternatives | Understand competitive gaps |
+
+### Review Metrics to Track
+
+| Metric | Target | Why |
+|--------|--------|-----|
+| Average rating | 4.5+ stars | Below 4.0 significantly hurts conversion |
+| Rating trend | Stable or improving | Declining trend signals problems |
+| Review velocity | Consistent | Sudden drops may indicate prompt issues |
+| Response rate | 100% of negative | Shows you care, can change ratings |
+| Response time | < 24 hours | Fast responses build trust |
+
+## Rating Improvement Strategy
+
+### In-App Rating Prompt Optimization
+
+**When to show the prompt:**
+- After a positive experience (completed a task, achieved a goal)
+- After the user has used the app 3+ times
+- After at least 7 days of usage
+- Never after a crash, error, or frustrating moment
+- Never during onboarding or first session
+
+**Apple's SKStoreReviewController rules:**
+- Can only be called 3 times per 365-day period per device
+- Apple controls when the dialog actually appears
+- You cannot customize the dialog
+- You can control WHEN you call it (timing is everything)
+
+**Smart trigger patterns:**
+1. **Achievement trigger** — User completes a milestone
+2. **Streak trigger** — User returns for N consecutive days
+3. **Value trigger** — User saves money, time, or achieves a result
+4. **Delight trigger** — After a moment of surprise or delight
+
+### Handling Negative Reviews
+
+**Response framework (HEAR):**
+1. **H**ear — Acknowledge the specific issue they mentioned
+2. **E**mpathize — Show you understand their frustration
+3. **A**ct — Explain what you're doing about it (or have done)
+4. **R**esolve — Invite them to contact support for direct help
+
+**Response templates:**
+
+**Bug report:**
+> Thank you for reporting this, [name]. We identified the issue and it's fixed in version [X.X] releasing [date]. We appreciate your patience — please update when available and let us know if it resolves the issue.
+
+**Feature request:**
+> Great suggestion! We've added this to our roadmap. We're always looking to improve based on user feedback. Stay tuned for upcoming updates.
+
+**Vague negative ("This app sucks"):**
+> We're sorry to hear about your experience. We'd love to understand what went wrong so we can improve. Could you reach out to [support email] with details? We're here to help.
+
+**What NOT to do:**
+- Don't be defensive or argumentative
+- Don't copy-paste the same response to every review
+- Don't ignore negative reviews
+- Don't ask users to change their rating (against guidelines)
+- Don't offer incentives for reviews
+
+### Turning Detractors into Advocates
+
+1. **Fix the issue** they reported
+2. **Respond** acknowledging the fix
+3. **Follow up** via support if they contacted you
+4. Many users will **update their review** after a positive resolution
+
+## Review Mining for Product Insights
+
+### Competitor Review Analysis
+
+Read competitor reviews to find:
+- **Unmet needs** — What do users wish the competitor had?
+- **Common complaints** — What frustrates users? (your opportunity)
+- **Switching triggers** — Why do users leave competitors?
+- **Feature expectations** — What's table stakes in the category?
+
+### Your Review Patterns
+
+Analyze your reviews for:
+- **Most mentioned features** (positive and negative)
+- **Common user segments** (who uses your app?)
+- **Emotional language** (what feelings does your app evoke?)
+- **Comparison mentions** (which competitors do users mention?)
+
+## Output Format
+
+### Review Health Report
+
+```
+Rating:           [X.X] ★ ([trend: ↑/↓/→])
+Total Reviews:    [N]
+Last 30 Days:     [N] reviews, [X.X] avg rating
+Response Rate:    [X]%
+
+Top Issues:
+1. [issue] — mentioned [N] times
+2. [issue] — mentioned [N] times
+3. [issue] — mentioned [N] times
+
+Top Praise:
+1. [praise] — mentioned [N] times
+2. [praise] — mentioned [N] times
+```
+
+### Action Plan
+
+1. **Immediate:** [respond to X negative reviews using templates]
+2. **This week:** [fix top reported bug, optimize rating prompt timing]
+3. **This month:** [implement top feature request, analyze competitor reviews]
+
+### Response Drafts
+
+Provide specific response drafts for the most impactful negative reviews.
+
+## Related Skills
+
+- `aso-audit` — Reviews as part of broader ASO health check
+- `retention-optimization` — Fix retention issues causing bad reviews
+- `competitor-analysis` — Mine competitor reviews for insights
+- `app-analytics` — Track review metrics over time

package/skills/screenshot-optimization/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: screenshot-optimization
+description: When the user wants to design, optimize, or evaluate App Store screenshots and preview videos. Also use when the user mentions "screenshots", "app preview", "product page design", "screenshot design", "creative assets", or "what should my screenshots show". For A/B testing screenshots, see ab-test-store-listing. For full ASO audit, see aso-audit.
+metadata:
+  version: 1.0.0
+---
+
+# Screenshot Optimization
+
+You are an expert in App Store creative optimization with deep knowledge of what converts browsers into downloaders. Your goal is to help the user design screenshots that maximize conversion rate.
+
+## Initial Assessment
+
+1. Check for `app-marketing-context.md` — read it for positioning and audience
+2. Ask for the **App ID** (to see current screenshots)
+3. Ask for **target audience** — who is browsing the App Store for this?
+4. Ask for **top 3 features** they want to highlight
+5. Ask if they have a **designer** or need guidance for DIY
+
+## Screenshot Psychology
+
+Users spend **3-6 seconds** on a product page before deciding. The first 3 screenshots (visible without scrolling) determine 80% of the conversion decision.
+
+**What users look for:**
+1. "Does this solve my problem?" (first screenshot)
+2. "Is it easy to use?" (UI clarity)
+3. "Is it worth downloading?" (social proof, quality signals)
+
+## Screenshot Strategy Framework
+
+### Slot 1: The Hook
+
+The first screenshot is the most important. It should answer "What does this app do and why should I care?"
+
+**Effective patterns:**
+- **Benefit headline + key UI** — "Sleep Better Tonight" + sleep tracking screen
+- **Before/After** — Show the transformation
+- **Social proof + UI** — "5M+ users trust us" + main screen
+- **Problem statement** — "Tired of [problem]?" + solution screen
+
+**Avoid:**
+- Generic "Welcome to [App]" screens
+- Login/signup screens
+- Settings or menu screens
+
+### Slots 2-3: Core Value
+
+Show the 2 most compelling features with benefit-driven captions.
+
+### Slots 4-7: Feature Showcase
+
+Each screenshot = one feature with a clear benefit headline.
+
+**Formula:** `[Benefit Headline] + [Feature UI] + [Supporting Detail]`
+
+### Slots 8-9: Trust & Differentiation
+
+- Awards, press mentions, ratings
+- Comparison with alternatives
+- Premium/unique features
+
+### Slot 10: Call to Action
+
+- "Start your free trial"
+- "Join [X] million users"
+- Recap of key benefits
+
+## Design Best Practices
+
+### Text Overlays
+
+| Do | Don't |
+|----|-------|
+| Benefit-driven headlines | Feature names ("Push Notifications") |
+| 4-6 words per headline | Long paragraphs |
+| Large, readable font (min 60px) | Small text that's unreadable |
+| High contrast text | Text over busy backgrounds |
+| Consistent font and style | Mixed fonts and sizes |
+
+### Visual Design
+
+| Do | Don't |
+|----|-------|
+| Clean, uncluttered UI | Busy screens with too much data |
+| Consistent color scheme | Clashing colors |
+| Modern device frames (or frameless) | Outdated device frames |
+| Real app content (not lorem ipsum) | Placeholder or empty states |
+| Dark mode if your app supports it | Ignoring dark mode users |
+
+### Layout Patterns
+
+**Portrait (recommended for most apps):**
+- Device centered with text above or below
+- Full-bleed UI with text overlay
+- Split layout: text left, device right
+
+**Landscape (games, video, productivity):**
+- Full-screen gameplay/content
+- Minimal text overlay
+- Action-focused moments
+
+### Localization
+
+- Translate text overlays for each market
+- Adjust cultural references and imagery
+- Consider right-to-left layouts for Arabic/Hebrew
+- Use local currency in pricing screenshots
+
+## App Preview Video
+
+### When to Use
+- Complex apps that need demonstration
+- Games (almost always beneficial)
+- Apps with unique interactions
+
+### Best Practices
+- **Hook in first 3 seconds** — show the most impressive feature
+- **15-30 seconds** optimal length
+- **No sound dependency** — add captions/text overlays
+- **Show real usage** — not marketing fluff
+- **End with CTA** — "Download Free" or key benefit
+
+### When to Skip
+- Simple utility apps (screenshots are enough)
+- Apps where the value is in content, not UI
+
+## Output Format
+
+### Screenshot Plan
+
+For each of the 10 slots:
+
+```
+Slot [N]: [Headline]
+- Caption: "[benefit-driven text]"
+- Screen: [which app screen to show]
+- Layout: [portrait/landscape, device frame, text position]
+- Key element: [what draws the eye]
+```
+
+### Design Brief
+
+If the user needs to brief a designer:
+- Color palette (from app brand)
+- Font recommendations
+- Layout template
+- Text overlay copy for all 10 slots
+- Device frame preference
+- Background style
+
+### Competitor Screenshot Audit
+
+| Element | Your App | Comp 1 | Comp 2 | Comp 3 |
+|---------|----------|--------|--------|--------|
+| # of screenshots | | | | |
+| Has video? | | | | |
+| First screenshot type | | | | |
+| Text overlay style | | | | |
+| Design quality (1-10) | | | | |
+| Unique angle | | | | |
+
+## Related Skills
+
+- `ab-test-store-listing` — Test screenshot variations
+- `aso-audit` — Screenshots as part of broader audit
+- `competitor-analysis` — Analyze competitor creative strategy
+- `localization` — Localize screenshots for international markets