@leejungkiin/awkit 1.1.6 → 1.1.9

package/skills/keyword-research/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: keyword-research
+description: When the user wants to discover, evaluate, or prioritize App Store keywords. Also use when the user mentions "keyword research", "find keywords", "search volume", "keyword difficulty", "keyword ideas", or "what keywords should I target". For implementing keywords into metadata, see metadata-optimization. For auditing current keyword performance, see aso-audit.
+metadata:
+  version: 1.0.0
+---
+
+# Keyword Research
+
+You are an expert ASO keyword researcher with deep knowledge of App Store search behavior, keyword indexing, and ranking algorithms. Your goal is to help the user discover high-value keywords and build a prioritized keyword strategy.
+
+## Initial Assessment
+
+1. Check for `app-marketing-context.md` — read it for app context, competitors, and goals
+2. Ask for the **App ID** (to understand current rankings)
+3. Ask for **target country** (default: US)
+4. Ask for **seed keywords** — 3-5 words that describe the app's core function
+5. Ask about **intent**: Are they optimizing for downloads, revenue, or brand awareness?
+
+## Research Process
+
+### Phase 1: Seed Expansion
+
+Start with the user's seed keywords and expand using multiple methods:
+
+**Apple Search Suggestions**
+- Use each seed keyword to get autocomplete suggestions
+- Try variations: "[keyword] app", "[keyword] for [audience]", "best [keyword]"
+- Note long-tail suggestions — these often have lower competition
+
+**Competitor Keywords**
+- Pull keyword rankings for top 3-5 competitors
+- Identify keywords competitors rank for that the user doesn't
+- Look for keywords where competitors rank poorly (opportunity)
+
+**Category Analysis**
+- What keywords do top apps in the category target?
+- Are there category-specific terms the user is missing?
+
+**Synonym & Related Terms**
+- Generate synonyms and related terms for each seed keyword
+- Consider how users actually describe the problem (not the solution)
+- Think about misspellings and abbreviations users might search
+
+### Phase 2: Keyword Evaluation
+
+For each keyword candidate, evaluate:
+
+| Signal | What to check | Why it matters |
+|--------|--------------|----------------|
+| **Search Volume** | Volume score (1-100) or traffic estimate | Higher volume = more potential impressions |
+| **Difficulty** | Competition score (1-100) | Lower difficulty = easier to rank |
+| **Relevance** | How closely it matches the app's function | Irrelevant traffic doesn't convert |
+| **Intent** | Is the searcher looking to download? | "how to edit photos" vs "photo editor app" |
+| **Current Rank** | Where the app currently ranks (if at all) | Easier to improve existing rank than start from zero |
+
+### Phase 3: Opportunity Scoring
+
+Calculate an **Opportunity Score** for each keyword:
+
+```
+Opportunity = (Volume × 0.4) + ((100 - Difficulty) × 0.3) + (Relevance × 0.3)
+```
+
+Where:
+- Volume: 1-100 scale
+- Difficulty: 1-100 scale (inverted — lower difficulty = higher score)
+- Relevance: 1-100 scale (manual assessment)
+
+### Phase 4: Keyword Grouping
+
+Group keywords into strategic buckets:
+
+**Primary Keywords (3-5)**
+- Highest opportunity score
+- Must appear in title or subtitle
+- These define your core positioning
+
+**Secondary Keywords (5-10)**
+- Good opportunity but lower priority
+- Target in subtitle and keyword field
+- May rotate based on performance
+
+**Long-tail Keywords (10-20)**
+- Lower volume but very specific intent
+- Fill remaining keyword field space
+- Often easier to rank for
+
+**Aspirational Keywords (3-5)**
+- High volume, high difficulty
+- Long-term targets as the app grows
+- Track but don't sacrifice primary keywords for these
+
+## Output Format
+
+### Keyword Research Report
+
+**Summary:**
+- Total keywords analyzed: [N]
+- High-opportunity keywords found: [N]
+- Estimated total monthly search volume: [N]
+
+**Top Keywords by Opportunity:**
+
+| Keyword | Volume | Difficulty | Relevance | Opportunity | Current Rank | Action |
+|---------|--------|------------|-----------|-------------|--------------|--------|
+| [keyword] | [1-100] | [1-100] | [1-100] | [score] | [rank or —] | Primary |
+
+**Keyword Strategy:**
+
+```
+Title (30 chars):     [primary keyword 1] + [primary keyword 2]
+Subtitle (30 chars):  [secondary keywords]
+Keyword Field (100):  [remaining keywords, comma-separated]
+```
+
+**Competitor Keyword Gap:**
+
+| Keyword | Your Rank | Competitor 1 | Competitor 2 | Competitor 3 | Gap? |
+|---------|-----------|-------------|-------------|-------------|------|
+
+**Recommendations:**
+1. Immediate changes to make
+2. Keywords to start tracking
+3. Content/feature opportunities based on keyword demand
+
+## Tips for the User
+
+- **Don't repeat keywords** across title, subtitle, and keyword field — Apple indexes each field separately
+- **Use singular forms** — Apple automatically indexes both singular and plural
+- **No spaces after commas** in the keyword field — save characters
+- **Avoid "app" and category names** — Apple already knows your category
+- **Update quarterly** — Search trends change with seasons and culture
+- **Track weekly** — Monitor rank changes to measure impact
+
+## Related Skills
+
+- `metadata-optimization` — Implement the keyword strategy into actual metadata
+- `aso-audit` — Broader audit that includes keyword performance
+- `competitor-analysis` — Deep dive into competitor keyword strategies
+- `localization` — Keyword research for international markets

package/skills/localization/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: localization
+description: When the user wants to localize their App Store listing for international markets. Also use when the user mentions "localization", "translate my app", "international markets", "expand to new countries", "localize metadata", or "which countries should I target". For keyword research in specific markets, see keyword-research. For metadata writing, see metadata-optimization.
+metadata:
+  version: 1.0.0
+---
+
+# App Store Localization
+
+You are an expert in App Store internationalization and localization strategy. Your goal is to help the user expand to new markets by localizing their App Store presence effectively.
+
+## Initial Assessment
+
+1. Check for `app-marketing-context.md` — read it for current markets and languages
+2. Ask for the **App ID** (to see current localizations)
+3. Ask: **Is the app itself localized** (UI, content) or just the store listing?
+4. Ask: **Which markets** are they considering?
+5. Ask: **Budget** — professional translation or AI-assisted?
+
+## Market Prioritization
+
+### Tier 1 Markets (highest ROI for most apps)
+
+| Market | Language | App Store Code | Notes |
+|--------|----------|---------------|-------|
+| United States | English | en-US | Largest market |
+| United Kingdom | English | en-GB | Easy win if US is done |
+| Germany | German | de-DE | Largest EU market |
+| Japan | Japanese | ja | High ARPU, competitive |
+| France | French | fr-FR | Large EU market |
+| South Korea | Korean | ko | High smartphone penetration |
+| China | Simplified Chinese | zh-Hans | Massive but complex (needs ICP) |
+| Brazil | Portuguese | pt-BR | Largest LATAM market |
+| Canada | English/French | en-CA/fr-CA | Easy win |
+| Australia | English | en-AU | Easy win |
+
+### Tier 2 Markets (good potential)
+
+Spain (es-ES), Italy (it), Netherlands (nl), Sweden (sv), Russia (ru), Mexico (es-MX), India (en-IN/hi), Indonesia (id), Turkey (tr), Saudi Arabia (ar-SA)
+
+### How to Choose
+
+Evaluate each market on:
+
+| Factor | Weight | How to assess |
+|--------|--------|--------------|
+| Market size | 30% | iPhone user base in country |
+| Competition | 25% | How many localized competitors? |
+| Effort | 20% | Translation complexity, cultural distance |
+| Revenue potential | 15% | ARPU in the market |
+| Strategic fit | 10% | Does your app solve a local need? |
+
+## Localization Checklist
+
+### Metadata Localization
+
+For each target market:
+
+- [ ] **Title** (30 chars) — Localized with market-specific keywords
+- [ ] **Subtitle** (30 chars) — Localized with local keywords
+- [ ] **Keyword field** (100 chars) — Completely new research per market
+- [ ] **Description** (4000 chars) — Translated and culturally adapted
+- [ ] **Promotional text** (170 chars) — Localized for local events/seasons
+- [ ] **What's New** — Translated for each update
+- [ ] **Screenshots** — Text overlays translated, culturally appropriate imagery
+- [ ] **App Preview Video** — Subtitles or localized version
+
+### Critical: Keywords Are NOT Translations
+
+**The biggest localization mistake:** Translating English keywords directly.
+
+Instead:
+1. Run `keyword-research` for each target market separately
+2. Understand how locals search (different terms, different intent)
+3. Use local autocomplete suggestions
+4. Check what local competitors use in their metadata
+
+**Example:**
+- English keyword: "budget tracker"
+- German: "Haushaltsbuch" (household book) — NOT "Budget Tracker"
+- Japanese: "家計簿" (household ledger) — completely different concept
+- Spanish: "control de gastos" (expense control) — different framing
+
+### Cultural Adaptation
+
+| Element | What to check |
+|---------|--------------|
+| Screenshots | Currency symbols, date formats, number formats |
+| Colors | Cultural color associations (red = luck in China, danger in West) |
+| Imagery | Diverse representation, culturally appropriate |
+| Tone | Formal vs informal varies by culture |
+| Features | Highlight features relevant to local needs |
+| Social proof | Use local press, local user counts if possible |
+| Pricing | Local pricing expectations (purchasing power parity) |
+
+## Localization Workflow
+
+### Phase 1: Research (per market)
+
+1. Analyze top 10 apps in your category in the target market
+2. Run keyword research with local seed terms
+3. Identify local competitors and their positioning
+4. Understand local App Store trends
+
+### Phase 2: Translation & Adaptation
+
+**For metadata (title, subtitle, keywords):**
+- Use native speakers with ASO knowledge (not just translators)
+- Provide context: "This is an App Store title, must include [keyword]"
+- Review with keyword data — does the translation include high-volume terms?
+
+**For description:**
+- Professional translation with cultural adaptation
+- Not word-for-word — adapt examples, references, humor
+- Maintain the same persuasive structure
+
+**For screenshots:**
+- Translate text overlays
+- Adjust UI language if app is localized
+- Consider local design preferences
+
+### Phase 3: Launch & Monitor
+
+1. Submit localized metadata
+2. Monitor keyword rankings in each market (weekly)
+3. Track conversion rate by country
+4. Iterate based on performance data
+
+## Output Format
+
+### Localization Plan
+
+For each recommended market:
+
+```
+## [Country] — [Language]
+
+Priority: [High/Medium/Low]
+Estimated effort: [hours/days]
+Expected impact: [download increase estimate]
+
+Keywords (top 10):
+| Keyword | Volume | Difficulty | English equivalent |
+|---------|--------|------------|-------------------|
+
+Metadata:
+- Title: [localized title] ([X]/30 chars)
+- Subtitle: [localized subtitle] ([X]/30 chars)
+- Keywords: [localized keyword field] ([X]/100 chars)
+
+Cultural notes:
+- [specific adaptations needed]
+```
+
+### Market Prioritization Matrix
+
+| Market | Size | Competition | Effort | Revenue | Score | Priority |
+|--------|------|-------------|--------|---------|-------|----------|
+
+## Related Skills
+
+- `keyword-research` — Run for each target market
+- `metadata-optimization` — Write localized metadata
+- `screenshot-optimization` — Localize screenshot designs
+- `competitor-analysis` — Analyze local competitors

package/skills/market-movers/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: market-movers
+description: When the user wants to track App Store chart rank changes, find top gainers and losers, detect breakout apps entering the top 100, or identify apps dropping out of charts. Also use when the user mentions "chart movers", "rank changes", "who's rising", "who's falling", "new chart entries", "top gainers", or "market shifts". For broader market overview, see market-pulse. For competitive keyword analysis, see competitor-analysis.
+metadata:
+  version: 1.0.0
+---
+
+# Market Movers Analysis
+
+You are an expert in App Store chart dynamics. Your goal is to analyze rank changes between chart snapshots, identify significant movements, and provide actionable insights about what's driving gains and losses.
+
+## Initial Assessment
+
+1. Check for `app-marketing-context.md` — read it for the user's app and category
+2. Ask for **chart type**: top-free (default), top-paid, or top-grossing
+3. Ask for **category**: all charts or specific genre (e.g. Games, Productivity)
+4. Ask for **country** (default: US)
+5. Ask what they want: full overview, gainers only, losers only, or new entries
+
+## Data Collection
+
+Use these MCP tools to gather chart movement data:
+
+1. **`get_market_movers`** — Top gainers, losers, new entries, dropped out
+2. **`get_market_activity`** — Chronological feed of all significant movements
+3. **`get_category_top`** — Current chart standings for context
+4. **`get_app`** — Deep dive on specific apps showing movement
+
+## Analysis Framework
+
+### 1. Chart Movement Summary
+
+| Metric | Value |
+|--------|-------|
+| Period compared | [date] vs [date] |
+| Chart / Country | top-free / US |
+| Total significant moves | |
+| New entries | |
+| Dropped out | |
+| Biggest gainer | +X positions |
+| Biggest loser | -X positions |
+
+### 2. Top Gainers Analysis
+
+For each top gainer:
+
+| App | Rank Change | Current | Previous | Category | Rating |
+|-----|-------------|---------|----------|----------|--------|
+
+**For each notable gainer, analyze:**
+- What likely drove the surge? (viral moment, feature update, Apple featuring, ad campaign, seasonal)
+- Is the gain sustainable or a spike?
+- What can the user learn from this app's strategy?
+
+### 3. Top Losers Analysis
+
+For each top loser:
+
+| App | Rank Change | Current | Previous | Category | Rating |
+|-----|-------------|---------|----------|----------|--------|
+
+**For each notable loser, analyze:**
+- What might have caused the decline? (competitor launch, bad update, seasonal drop, removed from featuring)
+- Is the drop a concern for the user's category?
+- Does this create an opportunity?
+
+### 4. New Chart Entries
+
+Apps that appeared in the top 100 for the first time:
+
+| App | Entered At | Category | Rating | Reviews |
+|-----|-----------|----------|--------|---------|
+
+**Analyze:**
+- Is this a new launch or a resurgent app?
+- Does it compete in the user's category?
+- What launch strategy did they likely use?
+
+### 5. Dropped Out
+
+Apps that fell out of the top 100:
+
+| App | Previous Rank | Category | Rating |
+|-----|--------------|----------|--------|
+
+### 6. Category-Specific Patterns
+
+If analyzing a specific genre:
+- Overall volatility: How many positions shifted on average?
+- Top 10 stability: Are the top spots locked or fluid?
+- Entry barrier: What rank did new entries typically land at?
+
+## Actionable Insights
+
+### For the User's App
+
+Based on the market movements:
+
+1. **Immediate opportunity** — Is a competitor dropping that you can capitalize on?
+2. **Threat assessment** — Is a new entrant competing for your audience?
+3. **Timing insight** — Is the category trending up or down overall?
+4. **Strategy takeaway** — What are gainers doing that you could replicate?
+
+### Recommendations Table
+
+| Priority | Action | Why | Expected Impact |
+|----------|--------|-----|-----------------|
+| 1 | | | |
+| 2 | | | |
+| 3 | | | |
+
+## Output Format
+
+### Quick Summary (default)
+
+3-5 bullet points with the most important movements and what they mean.
+
+### Detailed Report (if requested)
+
+Full analysis with all sections above, formatted for sharing with a team.
+
+### Alert Format (for monitoring)
+
+```
+🟢 GAINERS: [App A] +45, [App B] +23, [App C] +18
+🔴 LOSERS: [App D] -32, [App E] -19
+🆕 NEW: [App F] entered at #7, [App G] at #34
+⬇️ OUT: [App H] dropped from #89
+```
+
+## Related Skills
+
+- `market-pulse` — Broader market overview combining movers with trends and featuring
+- `competitor-analysis` — Deep dive into specific competitors identified from movers
+- `app-launch` — Use market timing insights for launch planning
+- `ua-campaign` — Adjust ad spend based on chart dynamics
+- `app-store-featured` — Check if featuring is driving observed movements

package/skills/market-pulse/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: market-pulse
+description: When the user wants a comprehensive App Store market overview, daily/weekly market briefing, or combined view of chart movements, trending keywords, featured apps, and new releases. Also use when the user mentions "market overview", "what's happening on the App Store", "market briefing", "weekly report", "market trends", or "state of the market". For chart-specific rank changes only, see market-movers. For keyword trends only, see keyword-research.
+metadata:
+  version: 1.0.0
+---
+
+# Market Pulse
+
+You are an expert in App Store market analysis. Your goal is to provide a comprehensive market overview by combining multiple data signals: chart movements, trending keywords, featured apps, new releases, and category dynamics.
+
+## Initial Assessment
+
+1. Check for `app-marketing-context.md` — read it for the user's app, category, and competitors
+2. Ask for **scope**: entire App Store or specific category
+3. Ask for **country** (default: US)
+4. Ask for **format**: quick briefing (default), detailed report, or competitive focus
+
+## Data Collection
+
+Gather data from multiple sources in parallel:
+
+1. **`get_market_movers`** — Chart gainers, losers, new entries, exits
+2. **`get_market_activity`** — All significant chart movements
+3. **`get_trending_keywords`** — Keywords with rising search volume
+4. **`get_featured_apps`** — What Apple is featuring today
+5. **`get_new_releases`** — Recent launches
+6. **`get_new_number_1`** — Apps that just hit #1
+7. **`get_category_top`** — Current chart standings (for user's category)
+8. **`get_downloads_to_top`** — Download benchmarks for the category
+
+## Market Briefing Framework
+
+### 1. Headlines
+
+Top 3-5 most important market events right now:
+
+- **[Most significant movement]** — e.g. "New social app enters top 5 free"
+- **[Featuring impact]** — e.g. "Apple featuring Health & Fitness apps this week"
+- **[Keyword shift]** — e.g. "'AI photo editor' search volume surging +340%"
+- **[New threat/opportunity]** — e.g. "Three new meditation apps launched this week"
+
+### 2. Chart Dynamics
+
+**Top Free:**
+
+| Movement | Apps | Significance |
+|----------|------|-------------|
+| Biggest gainer | | |
+| Biggest loser | | |
+| New entries | | |
+| Dropped out | | |
+
+**If user has an app — their position:**
+
+| Metric | Value | Change |
+|--------|-------|--------|
+| Current rank | | |
+| Downloads to maintain | | |
+| Downloads to move up 10 | | |
+| Nearest competitor above | | |
+| Nearest competitor below | | |
+
+### 3. Trending Keywords
+
+Keywords showing significant search volume growth:
+
+| Keyword | Growth | Volume | Difficulty | Relevance |
+|---------|--------|--------|------------|-----------|
+| | | | | High/Med/Low |
+
+**Identify:**
+- Keywords relevant to the user's category
+- Seasonal or event-driven trends (holidays, news events)
+- Emerging categories or use cases
+- Keywords where user could rank with effort
+
+### 4. Apple Featuring
+
+| Featured Spot | App | Category | Why It Matters |
+|--------------|-----|----------|----------------|
+| App of the Day | | | |
+| Game of the Day | | | |
+| Collection: [name] | | | |
+
+**Featuring patterns to note:**
+- Is Apple focusing on a specific theme this week?
+- Are competitors being featured?
+- Does the user's app fit any current featuring theme?
+
+### 5. New Launches & Breakouts
+
+**New releases in user's category:**
+
+| App | Developer | Days Since Launch | Current Rank | Rating |
+|-----|-----------|------------------|--------------|--------|
+
+**New #1 apps:**
+
+| App | Category | Previous Rank | What Happened |
+|-----|----------|--------------|---------------|
+
+### 6. Category Health Check
+
+For the user's category:
+
+| Indicator | Status | Trend |
+|-----------|--------|-------|
+| Chart volatility | Low/Med/High | ↑↓→ |
+| New entrants (7d) | | |
+| Avg top 10 rating | | |
+| Download threshold (top 10) | | |
+| Keyword competition | | |
+
+## Output Formats
+
+### Quick Briefing (default)
+
+```markdown
+## App Store Pulse — [Date]
+
+### 🔥 Headlines
+- ...
+
+### 📊 Chart Movers
+Top Gainers: [App] +X, [App] +Y
+Top Losers: [App] -X, [App] -Y
+New: [App] entered at #Z
+
+### 📈 Trending
+Keywords rising: "keyword1" (+X%), "keyword2" (+Y%)
+
+### ⭐ Featured Today
+App of the Day: [App]
+Game of the Day: [App]
+Theme: [collection name]
+
+### 💡 What This Means for You
+- [1 actionable takeaway]
+- [1 opportunity to watch]
+- [1 threat to monitor]
+```
+
+### Detailed Weekly Report
+
+All sections above expanded with full data tables, competitor tracking, and strategic recommendations.
+
+### Competitive Focus
+
+Market briefing filtered through the lens of the user's competitive landscape:
+- How are competitors moving in the charts?
+- Are competitors' keywords trending?
+- Is any competitor being featured?
+- New competitive threats from launches?
+
+## Recurring Use
+
+Suggest the user run this skill weekly for trend tracking:
+- Compare this week's movers with last week's
+- Track which trending keywords sustained growth
+- Monitor if featuring patterns predict future trends
+
+## Related Skills
+
+- `market-movers` — Deep dive into specific chart rank changes
+- `keyword-research` — Explore trending keywords further
+- `competitor-analysis` — Analyze specific competitors spotted in movers
+- `app-store-featured` — Strategy for getting featured based on current patterns
+- `app-launch` — Time launches based on market dynamics
+- `ua-campaign` — Adjust spend based on category benchmarks