@leejungkiin/awkit 1.1.6 → 1.1.7

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

package/skills/seasonal-aso/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: seasonal-aso
+description: When the user wants to optimize their App Store listing for seasonal events, holidays, or trending moments — including keyword opportunities, metadata updates, screenshot theming, and timing strategy. Use when the user mentions "seasonal", "holiday", "Christmas", "New Year", "Valentine's Day", "summer", "back to school", "seasonal keywords", "trending now", "limited time", or wants to capitalize on a calendar event. For general keyword research, see keyword-research. For full metadata rewrites, see metadata-optimization.
+metadata:
+  version: 1.0.0
+---
+
+# Seasonal ASO
+
+You help the user identify and act on seasonal keyword opportunities and listing optimizations tied to calendar events, holidays, and trending moments.
+
+## Key Principle
+
+**Seasonal rankings are competitive and time-sensitive.** Metadata takes 1–3 days to index. Plan changes 2 weeks before the event; revert 3–5 days after peak.
+
+## Seasonal Calendar (iOS — US)
+
+| Event | Peak Window | Keywords to target |
+|-------|-------------|-------------------|
+| New Year | Dec 26 – Jan 7 | "new year", "resolution", "goals", "habit", "fresh start" |
+| Valentine's Day | Feb 1–14 | "valentine", "love", "couples", "romantic", "gift" |
+| Spring / Easter | Mar–Apr | "spring", "easter", "refresh", "clean", "declutter" |
+| Mother's Day | May 1–12 | "mom", "mother", "family", "gift for mom" |
+| Summer | Jun–Aug | "summer", "vacation", "travel", "outdoor", "beach" |
+| Back to School | Jul 15 – Sep 10 | "school", "study", "student", "homework", "planner" |
+| Halloween | Oct 1–31 | "halloween", "scary", "spooky", "costume", "trick" |
+| Black Friday | Nov 20–30 | "deal", "sale", "discount", "shopping", "gift" |
+| Christmas | Dec 1–26 | "christmas", "gift", "holiday", "santa", "family" |
+| End of Year | Dec 27–31 | "year review", "recap", "goals 2026", "new year" |
+
+## Workflow
+
+### Step 1 — Identify Relevant Event
+
+1. Check for `app-marketing-context.md`
+2. Ask: **Which event or season are you targeting?**
+3. Ask: **What does your app do?** (to assess keyword relevance)
+4. Determine if the event is a good fit — not every seasonal moment applies
+
+### Step 2 — Research Seasonal Keywords
+
+Use Appeeky to find volume on seasonal terms:
+
+```bash
+GET /v1/keywords/metrics?keywords=christmas+planner,holiday+tracker
+GET /v1/keywords/suggestions?term=christmas&country=us
+GET /v1/keywords/trending?country=us&days=7
+```
+
+**Filter by:**
+- Volume spike (compare to baseline 30 days prior)
+- Difficulty < 60 preferred (seasonal keywords are crowded)
+- Relevance to your app's core function
+
+### Step 3 — Plan Metadata Changes
+
+**Keyword field (100 chars, iOS):**
+- Swap out low-performing keywords for seasonal terms
+- Add 2–4 seasonal keywords while preserving your best evergreen terms
+- Remove seasonal terms that are irrelevant to your core use case
+
+**Subtitle (30 chars):**
+- Consider a seasonal hook if it fits: "Your Holiday Planner" or "New Year Goal Tracker"
+- Only change if the original subtitle is not keyword-critical
+
+**Promotional text (170 chars — no review required):**
+- Always update for seasonal events — instant, no review
+- Use for: seasonal call-to-action, limited-time feature highlights, event tie-ins
+
+**Screenshots:**
+- Add a seasonal frame or theme to the first 2 screenshots
+- Use `screenshot-optimization` skill for creative guidance
+
+### Step 4 — Timing Checklist
+
+```
+Timeline (count back from event date):
+- [ ] T-14 days: Research keywords, brief creative
+- [ ] T-10 days: Write new metadata + promotional text
+- [ ] T-7 days: Submit screenshot updates (no review needed)
+- [ ] T-5 days: Submit keyword/subtitle update (review time buffer)
+- [ ] T-0: Event peak — monitor rankings daily
+- [ ] T+3 days: Revert metadata to evergreen version
+- [ ] T+5 days: Revert promotional text
+```
+
+## Output Format
+
+### Seasonal Opportunity Brief
+
+```
+🎄 Seasonal Opportunity: [Event Name]
+   Peak window: [dates]
+   Lead time needed: [X days]
+
+Keyword Opportunities:
+  High priority (volume spike, <60 difficulty):
+  - "[keyword]" — vol [N], diff [N]
+  - "[keyword]" — vol [N], diff [N]
+
+  Secondary (relevant but competitive):
+  - "[keyword]" — vol [N], diff [N]
+
+Metadata Recommendations:
+  Keyword field: [current] → [proposed — 100 chars]
+  Subtitle: [keep / change to: "..."]
+  Promo text: "[seasonal copy — 170 chars]"
+
+Screenshots: [suggest seasonal theme or keep as-is]
+
+Timeline:
+  - Submit metadata by: [date]
+  - Submit promo text by: [date]
+  - Revert by: [date]
+```
+
+## Seasonal vs Evergreen Trade-offs
+
+| Factor | Seasonal | Evergreen |
+|--------|----------|-----------|
+| Volume | Temporarily very high | Stable |
+| Competition | Very high at peak | Moderate |
+| Risk | Rankings drop after peak | Consistent |
+| Reward | Spike in installs | Sustained growth |
+
+**Rule:** Only swap evergreen keywords that are already underperforming. Never sacrifice a high-ranking keyword for seasonal speculation.
+
+## Trending Moments (Non-Calendar)
+
+For viral/trending moments (news events, viral content, app store trends):
+1. Use `GET /v1/keywords/trending?country=us&days=3` to spot emerging terms
+2. Act within 24–48 hours (trending windows are short)
+3. Only update promotional text (instant, no review)
+4. Revert after the trend fades (typically 3–7 days)
+
+## Related Skills
+
+- `keyword-research` — Deep keyword analysis for seasonal candidates
+- `metadata-optimization` — Rewrite full metadata with seasonal terms
+- `screenshot-optimization` — Design seasonal screenshot themes
+- `market-pulse` — Spot trending keywords and market movements in real time