@leejungkiin/awkit 1.1.6 → 1.1.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/README.md +51 -1
  2. package/bin/awk.js +2 -2
  3. package/core/GEMINI.md +45 -7
  4. package/package.json +8 -5
  5. package/skill-packs/neural-memory/skills/nm-memory-sync/SKILL.md +14 -1
  6. package/skills/ab-test-store-listing/SKILL.md +220 -0
  7. package/skills/android-aso/SKILL.md +197 -0
  8. package/skills/app-analytics/SKILL.md +210 -0
  9. package/skills/app-clips/SKILL.md +163 -0
  10. package/skills/app-icon-optimization/SKILL.md +170 -0
  11. package/skills/app-launch/SKILL.md +153 -0
  12. package/skills/app-marketing-context/SKILL.md +129 -0
  13. package/skills/app-store-featured/SKILL.md +213 -0
  14. package/skills/apple-search-ads/SKILL.md +205 -0
  15. package/skills/asc-metrics/SKILL.md +157 -0
  16. package/skills/aso-audit/SKILL.md +179 -0
  17. package/skills/competitor-analysis/SKILL.md +163 -0
  18. package/skills/competitor-tracking/SKILL.md +185 -0
  19. package/skills/crash-analytics/SKILL.md +181 -0
  20. package/skills/gitnexus-intelligence/SKILL.md +224 -0
  21. package/skills/in-app-events/SKILL.md +176 -0
  22. package/skills/keyword-research/SKILL.md +141 -0
  23. package/skills/localization/SKILL.md +165 -0
  24. package/skills/market-movers/SKILL.md +137 -0
  25. package/skills/market-pulse/SKILL.md +170 -0
  26. package/skills/metadata-optimization/SKILL.md +170 -0
  27. package/skills/monetization-strategy/SKILL.md +175 -0
  28. package/skills/onboarding-optimization/SKILL.md +194 -0
  29. package/skills/orchestrator/SKILL.md +306 -25
  30. package/skills/press-and-pr/SKILL.md +204 -0
  31. package/skills/rating-prompt-strategy/SKILL.md +184 -0
  32. package/skills/retention-optimization/SKILL.md +165 -0
  33. package/skills/review-management/SKILL.md +154 -0
  34. package/skills/screenshot-optimization/SKILL.md +167 -0
  35. package/skills/seasonal-aso/SKILL.md +141 -0
  36. package/skills/spec-gate/SKILL.md +312 -0
  37. package/skills/subscription-lifecycle/SKILL.md +206 -0
  38. package/skills/swiftui-pro/references/design.md +44 -0
  39. package/skills/symphony-enforcer/SKILL.md +92 -11
  40. package/skills/symphony-orchestrator/SKILL.md +9 -7
  41. package/skills/systematic-debugging/SKILL.md +32 -7
  42. package/skills/ua-campaign/SKILL.md +207 -0
  43. package/skills/verification-gate/SKILL.md +23 -2
  44. package/workflows/gitnexus.md +123 -0
  45. package/symphony/LICENSE +0 -21
  46. package/symphony/README.md +0 -178
  47. package/symphony/app/api/agents/route.js +0 -152
  48. package/symphony/app/api/events/route.js +0 -22
  49. package/symphony/app/api/knowledge/route.js +0 -253
  50. package/symphony/app/api/locks/route.js +0 -29
  51. package/symphony/app/api/notes/route.js +0 -125
  52. package/symphony/app/api/preflight/route.js +0 -23
  53. package/symphony/app/api/projects/route.js +0 -116
  54. package/symphony/app/api/roles/route.js +0 -134
  55. package/symphony/app/api/skills/route.js +0 -82
  56. package/symphony/app/api/status/route.js +0 -18
  57. package/symphony/app/api/tasks/route.js +0 -157
  58. package/symphony/app/api/workflows/route.js +0 -61
  59. package/symphony/app/api/workspaces/route.js +0 -15
  60. package/symphony/app/globals.css +0 -2605
  61. package/symphony/app/layout.js +0 -20
  62. package/symphony/app/page.js +0 -2122
  63. package/symphony/cli/index.js +0 -1060
  64. package/symphony/core/agent-manager.js +0 -357
  65. package/symphony/core/context-bus.js +0 -100
  66. package/symphony/core/db.js +0 -223
  67. package/symphony/core/file-lock-manager.js +0 -154
  68. package/symphony/core/merge-pipeline.js +0 -234
  69. package/symphony/core/orchestrator.js +0 -236
  70. package/symphony/core/task-manager.js +0 -335
  71. package/symphony/core/workspace-manager.js +0 -168
  72. package/symphony/jsconfig.json +0 -7
  73. package/symphony/lib/core.mjs +0 -1034
  74. package/symphony/mcp/index.js +0 -29
  75. package/symphony/mcp/server.js +0 -110
  76. package/symphony/mcp/tools/context.js +0 -80
  77. package/symphony/mcp/tools/locks.js +0 -99
  78. package/symphony/mcp/tools/status.js +0 -82
  79. package/symphony/mcp/tools/tasks.js +0 -216
  80. package/symphony/mcp/tools/workspace.js +0 -143
  81. package/symphony/next.config.mjs +0 -7
  82. package/symphony/package.json +0 -53
  83. package/symphony/scripts/postinstall.js +0 -49
  84. package/symphony/symphony.config.js +0 -41
package/README.md CHANGED
@@ -6,15 +6,46 @@ AWKit là framework điều phối AI agent chuyên nghiệp. Đây là **nơi d
6
6
 
7
7
  ---
8
8
 
9
+ ## 🧠 Gstack Core Principles
10
+
11
+ AWKit (Antigravity v12+) thực thi 8 nguyên tắc lõi (Gstack-inspired) nhằm đảm bảo AI hoạt động an toàn và hiệu quả:
12
+
13
+ 1. **Anti-sycophancy:** AI phải phản biện các hướng tiếp cận có rủi ro, không đồng ý mù quáng khi có red flags.
14
+ 2. **Search Before Building (3-layer):** Tìm kiếm NeuralMemory/codebase → Tìm standard libraries/SDKs → Chỉ code mới nếu 2 bước trên thất bại.
15
+ 3. **Completion Status Protocol:** 4 trạng thái rõ ràng: `DONE`, `DONE_WITH_CONCERNS`, `BLOCKED`, `NEEDS_CONTEXT`.
16
+ 4. **6 Decision Principles:** Complete > Shortcuts, Evidence > Assumptions, Standard > Custom, Explicit > Implicit, Test > Trust, Small > Big.
17
+ 5. **3-Strike Escalation:** Sau 3 lần thử fix bug thất bại → STOP, báo cáo context và chờ user quyết định.
18
+ 6. **Scope Freeze:** Khi debugging: KHÔNG sửa code không liên quan, KHÔNG refactor. Chỉ tập trung root cause.
19
+ 7. **Boil-the-Lake Checklist:** Checklist trước khi báo DONE: error handling, edge cases, logging, cleanup, input validation...
20
+ 8. **Safety Guardrails:** Chặn auto-run cho các lệnh nguy hiểm (`rm -rf`, `git push --force`, deploy production). Bắt buộc double-confirm.
21
+
22
+ ---
23
+
9
24
  ## 🚀 Quick Start
10
25
 
11
- ### Cài đặt nhanh qua NPM (Khuyên dùng)
26
+ ### Cài đặt (3 bước)
27
+
12
28
  ```bash
29
+ # 1. AWKit Core (CLI + workflows + skills)
13
30
  npm install -g @leejungkiin/awkit
14
31
  awkit install
32
+
33
+ # 2. Symphony (Task Management & Multi-Agent Orchestration)
34
+ npm install -g @leejungkiin/awkit-symphony
35
+
36
+ # 3. NeuralMemory (AI Memory Engine — requires Python >= 3.11)
37
+ pip install neural-memory
38
+ nmem init
39
+
40
+ # Verify
15
41
  awkit doctor
42
+ symphony --version
43
+ nmem --version
16
44
  ```
17
45
 
46
+ > 💡 **Bước 2 & 3 được tự động cài khi chạy `awkit install`** nếu môi trường đầy đủ.
47
+ > AI agent cũng tự detect và cài các dependency thiếu khi init session.
48
+
18
49
 
19
50
  ## 📦 Commands
20
51
 
@@ -132,6 +163,25 @@ awkit tg send "Hello from AWKit!"
132
163
  awkit tg send "Hello" --chat -100123456789 --topic 1234
133
164
  ```
134
165
 
166
+ ## 🧠 GitNexus Code Intelligence
167
+
168
+ AWKit (từ bản cập nhật tích hợp mới) sử dụng **GitNexus** làm engine cung cấp Code Intelligence & Knowledge Graph cho AI Agent. Sau khi chạy `npm install` AWKit, GitNexus sẽ sẵn sàng để dùng ngay.
169
+
170
+ Để kích hoạt GitNexus trên bất kỳ project nào anh/chị đang code:
171
+
172
+ ```bash
173
+ # 1. Quét toàn bộ project để tạo knowledge graph (chỉ cần chạy lần đầu hoặc khi cấu trúc code thay đổi lớn)
174
+ npx gitnexus analyze
175
+
176
+ # 2. Sử dụng CLI để phân tích code hoặc explore codebase:
177
+ gitnexus query "điểm thực thi workflow" # Tìm các file/class liên quan theo ngữ nghĩa
178
+ gitnexus impact "tên_hàm_cần_sửa" # Xem mức độ ảnh hưởng (blast radius) trước khi edit code!
179
+ gitnexus context "tên_class" # Góc nhìn 360 độ (Ai gọi nó? Nó gọi ai?)
180
+ gitnexus rename "tên_cũ" "tên_mới" --dry-run # Đổi tên an toàn qua biểu đồ
181
+ ```
182
+
183
+ AI agent của hệ thống cũng tự động gọi qua cổng GitNexus bằng MCP Tools để tự phân tích rủi ro trước khi commit!
184
+
135
185
  ## 📦 Skill Packs
136
186
 
137
187
  ```bash
package/bin/awk.js CHANGED
@@ -283,7 +283,7 @@ function checkSymphony({ silent = false } = {}) {
283
283
  return true;
284
284
  } catch (_) {
285
285
  if (!silent) warn('Symphony CLI not found. Please install it manually:');
286
- if (!silent) dim(' npm install -g awkit-symphony');
286
+ if (!silent) dim(' npm install -g @leejungkiin/awkit-symphony');
287
287
  return false;
288
288
  }
289
289
  }
@@ -1797,7 +1797,7 @@ function cmdInit(forceFlag = false) {
1797
1797
 
1798
1798
  const symReady = checkSymphony({ silent: true });
1799
1799
  if (!symReady) {
1800
- dim('Symphony CLI is not installed. Run: npm i -g awkit-symphony');
1800
+ dim('Symphony CLI is not installed. Run: npm i -g @leejungkiin/awkit-symphony');
1801
1801
  }
1802
1802
  }
1803
1803
 
package/core/GEMINI.md CHANGED
@@ -1,6 +1,6 @@
1
- # GEMINI.md — Antigravity v11.0
1
+ # GEMINI.md — Antigravity v12.1
2
2
 
3
- > Rules + routing only. Gate details → skills. Updated: 2026-03-18
3
+ > Rules + routing only. Gate details → skills. Updated: 2026-03-23
4
4
 
5
5
  ---
6
6
 
@@ -50,10 +50,19 @@ Mỗi skill tự xử lý gate logic riêng — xem SKILL.md của từng skill.
50
50
  - AI models: Gemini 2.5+ only.
51
51
  - Firebase: Firebase AI Logic SDK.
52
52
 
53
- ### Spec-First (NEW v11.0)
54
- - PLANNING mode PHẢI đọc `docs/specs/` **trước** khi viết `implementation_plan.md`.
55
- - Mỗi task trong plan NÊN format XML `<task>` (xem `templates/specs/task-spec-template.xml`).
56
- - `implementation_plan.md` PHẢI reference `TECH-SPEC.md` constraints khi relevant.
53
+ ### 5-Gate Autonomous System (NEW v12.0)
54
+ - orchestrator PHẢI triage complexity (TRIVIAL/MODERATE/COMPLEX) trước mọi task.
55
+ - COMPLEX tasks PHẢI qua 5 Gates tuần tự:
56
+ - Gate 1 (Spec): `brainstorm-agent` → BRIEF.md / spec document
57
+ - Gate 2 (Architecture): `spec-gate` → design doc + user approve
58
+ - Gate 3 (Tasks): `symphony-enforcer` → tạo Symphony tickets
59
+ - Gate 4 (Execution): code theo ticket, đối chiếu design doc
60
+ - Gate 5 (Verification): `verification-gate` + `code-review`
61
+ - TRIVIAL tasks bypass → thẳng Gate 4.
62
+ - MODERATE tasks → Gate 3 + 4 + 5.
63
+ - AI tự detect gate state — user KHÔNG CẦN gọi workflow bằng tay.
64
+ - Trong lúc code, nếu cần sửa schema khác approved design → ⛔ DỪNG, quay Gate 2.
65
+ - Chi tiết: xem `orchestrator/SKILL.md` (triage) + `spec-gate/SKILL.md` (Gate 2).
57
66
 
58
67
  ### NeuralMemory
59
68
  - Brain = projectId. Switch trước mọi nmem call.
@@ -67,6 +76,34 @@ Mỗi skill tự xử lý gate logic riêng — xem SKILL.md của từng skill.
67
76
  - Kết thúc task: Tóm tắt + Test + Next steps.
68
77
  - Không rõ: Hỏi lại, tối đa 2 lần.
69
78
 
79
+ ### Anti-sycophancy (Trung thực)
80
+ - PHẢI push back khi approach của user có vấn đề — giải thích rõ trade-offs.
81
+ - KHÔNG nói "Great idea!" nếu idea có red flags → nêu rủi ro trước.
82
+ - Nêu cả ưu VÀ nhược điểm của mọi approach, không chỉ list ưu điểm.
83
+ - Nếu request vi phạm best practices → cảnh báo TRƯỚC khi implement.
84
+ - Khi phát hiện pattern sai → đề xuất alternative, không im lặng đồng ý.
85
+ - Acknowledge limitations: nói "Tôi không chắc" khi không chắc.
86
+
87
+ ### Safety Guardrails (Destructive Commands)
88
+ - KHÔNG BAO GIỜ set `SafeToAutoRun=true` cho các commands sau:
89
+ - `rm -rf`, `rm -r`, `rmdir` (recursive delete)
90
+ - `git push --force`, `git reset --hard`, `git clean -fd`
91
+ - `DROP TABLE`, `DROP DATABASE`, `DELETE FROM` (without WHERE)
92
+ - `docker system prune`, `docker volume rm`
93
+ - `npm publish`, `pod trunk push`
94
+ - Bất kỳ command nào deploy lên production
95
+ - Double-confirm với user trước khi chạy destructive command.
96
+ - Nếu không chắc command có destructive hay không → hỏi trước.
97
+
98
+ ### 6 Decision Principles (Auto-decide)
99
+ Khi AI cần tự quyết định mà không hỏi user:
100
+ 1. **Complete > Shortcuts** — Implement đủ, không bỏ edge cases.
101
+ 2. **Evidence > Assumptions** — Dựa trên data, không đoán.
102
+ 3. **Standard > Custom** — Ưu tiên solution có sẵn, chuẩn ngành.
103
+ 4. **Explicit > Implicit** — Code rõ ràng, không "clever" tricks.
104
+ 5. **Test > Trust** — Viết test, không "chắc chắn đúng".
105
+ 6. **Small > Big** — Incremental changes, không big-bang refactor.
106
+
70
107
  ### Project Context
71
108
  - CODEBASE.md tồn tại → KHÔNG scan raw directory.
72
109
  - KHÔNG hỏi user về project structure.
@@ -85,7 +122,8 @@ Mỗi skill tự xử lý gate logic riêng — xem SKILL.md của từng skill.
85
122
 
86
123
  ## Routing
87
124
 
88
- - **Execution order:** `symphony-orchestrator` → `awf-session-restore` → `nm-memory-sync` → `symphony-enforcer` → `orchestrator` → action
125
+ - **Execution order:** `symphony-orchestrator` → `awf-session-restore` → `nm-memory-sync` → `symphony-enforcer` → `orchestrator` (triage + gate-check) → action
126
+ - **Gate skills:** `orchestrator` (triage) → `brainstorm-agent` (G1) → `spec-gate` (G2) → `symphony-enforcer` (G3) → `verification-gate` (G5)
89
127
  - **Skill catalog:** xem `orchestrator/SKILL.md`
90
128
  - **Workflows:** 75+ (`/xxx`). Core: `/init` `/code` `/debug` `/recap` `/next` `/todo`
91
129
  - **Shortcuts:** `/todo` `/done` `/next`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@leejungkiin/awkit",
3
- "version": "1.1.6",
3
+ "version": "1.1.9",
4
4
  "description": "Antigravity Workflow Kit. Unified AI agent orchestration system.",
5
5
  "main": "bin/awk.js",
6
6
  "bin": {
@@ -19,7 +19,7 @@
19
19
  "keywords": [
20
20
  "awkit"
21
21
  ],
22
- "author": "Kien AI",
22
+ "author": "Kien Le",
23
23
  "license": "MIT",
24
24
  "engines": {
25
25
  "node": ">=18.0.0"
@@ -33,9 +33,12 @@
33
33
  "schemas/",
34
34
  "templates/",
35
35
  "docs/",
36
- "symphony/",
37
36
  "README.md",
38
37
  "CHANGELOG.md",
39
38
  "VERSION"
40
- ]
41
- }
39
+ ],
40
+ "dependencies": {
41
+ "@leejungkiin/awkit-symphony": "^0.1.0",
42
+ "gitnexus": "^1.4.7"
43
+ }
44
+ }
@@ -165,9 +165,22 @@ This surfaces memories that a keyword search would miss.
165
165
 
166
166
  ---
167
167
 
168
+ ## Auto-Install Protocol (New Machine)
169
+
170
+ If `nmem` CLI is not available:
171
+ ```
172
+ 1. AI detects: command not found: nmem
173
+ 2. AI auto-runs: pip install neural-memory (or python3 -m pip install neural-memory)
174
+ → Requires Python >= 3.11
175
+ 3. After install: nmem init (initialize brain DB)
176
+ 4. Verify: nmem --version
177
+ 5. If Python < 3.11 or pip fails:
178
+ → Show user: "⚠️ NeuralMemory requires Python >= 3.11. Install via: brew install python@3.12"
179
+ ```
180
+
168
181
  ## Fallback Mode (NeuralMemory Not Installed)
169
182
 
170
- If `nmem` is not available, falls back to flat-file behavior:
183
+ If `nmem` is not available AND auto-install fails, falls back to flat-file behavior:
171
184
  ```
172
185
  - Reads from brain/decisions/, brain/solutions/
173
186
  - Keyword overlap matching (legacy behavior)
@@ -0,0 +1,220 @@
1
+ ---
2
+ name: ab-test-store-listing
3
+ description: When the user wants to A/B test App Store product page elements to improve conversion rate. Also use when the user mentions "A/B test", "product page optimization", "test my screenshots", "test my icon", "conversion rate optimization", "CPP", or "custom product pages". For screenshot design, see screenshot-optimization. For metadata optimization, see metadata-optimization.
4
+ metadata:
5
+ version: 1.0.0
6
+ ---
7
+
8
+ # A/B Test Store Listing
9
+
10
+ You are an expert in App Store product page optimization and A/B testing. Your goal is to help the user design, run, and interpret tests that improve their App Store conversion rate.
11
+
12
+ ## Initial Assessment
13
+
14
+ 1. Check for `app-marketing-context.md` — read it for context
15
+ 2. Ask for the **App ID**
16
+ 3. Ask for **current conversion rate** (if known from App Store Connect)
17
+ 4. Ask for **daily impressions** (determines test duration)
18
+ 5. Ask: **What do you want to test?** (icon, screenshots, description, etc.)
19
+
20
+ ## What You Can Test
21
+
22
+ ### Apple Product Page Optimization (PPO)
23
+
24
+ Apple's native A/B testing tool in App Store Connect.
25
+
26
+ | Element | Testable? | Notes |
27
+ |---------|-----------|-------|
28
+ | App icon | Yes | Up to 3 variants |
29
+ | Screenshots | Yes | Up to 3 variants |
30
+ | App preview video | Yes | Up to 3 variants |
31
+ | Description | No | Not testable via PPO |
32
+ | Title | No | Not testable via PPO |
33
+ | Subtitle | No | Not testable via PPO |
34
+
35
+ **Limitations:**
36
+ - Only tests against organic App Store traffic
37
+ - Minimum 90% confidence required to declare winner
38
+ - Tests run for 7-90 days
39
+ - Can only run one test at a time
40
+ - Traffic split is automatic (not configurable)
41
+
42
+ ### Custom Product Pages (CPP)
43
+
44
+ 35 custom product pages per app, each with unique:
45
+ - Screenshots
46
+ - App preview videos
47
+ - Promotional text
48
+
49
+ **Use for:**
50
+ - Different audiences (from different ad campaigns)
51
+ - Different value propositions
52
+ - Seasonal messaging
53
+ - Localized creative for specific markets
54
+
55
+ **Not a true A/B test** — CPPs are targeted pages linked from specific URLs/campaigns, not random traffic splits.
56
+
57
+ ## Test Prioritization
58
+
59
+ ### Impact × Effort Matrix
60
+
61
+ | Element | Impact on CVR | Effort | Priority |
62
+ |---------|--------------|--------|----------|
63
+ | First screenshot | Very High (15-30% lift possible) | Medium | 1 |
64
+ | App icon | High (10-20% lift possible) | Medium | 2 |
65
+ | Screenshot order | Medium (5-15% lift possible) | Low | 3 |
66
+ | Screenshot style | Medium (5-15% lift possible) | High | 4 |
67
+ | Preview video | Medium (5-10% lift possible) | High | 5 |
68
+
69
+ ### What to Test First
70
+
71
+ **Always start with the first screenshot.** It has the highest impact because:
72
+ - It's the first thing users see in search results
73
+ - 80% of users never scroll past the first 3 screenshots
74
+ - Small improvements here affect every visitor
75
+
76
+ ## Test Design Framework
77
+
78
+ ### Step 1: Hypothesis
79
+
80
+ Write a clear hypothesis before each test:
81
+
82
+ ```
83
+ If we [change], then [metric] will [improve/increase] because [reason].
84
+ ```
85
+
86
+ **Examples:**
87
+ - "If we add social proof ('5M+ users') to the first screenshot, conversion rate will increase because it builds trust"
88
+ - "If we change the icon from blue to orange, tap-through rate will increase because it stands out more in search results"
89
+ - "If we show the app's AI feature first instead of the basic editor, conversion will increase because AI is the key differentiator"
90
+
91
+ ### Step 2: Variants
92
+
93
+ Design 2-3 variants (including control):
94
+
95
+ | Variant | Description | Hypothesis |
96
+ |---------|-------------|------------|
97
+ | Control (A) | Current version | Baseline |
98
+ | Variant B | [specific change] | [why it might win] |
99
+ | Variant C | [different change] | [why it might win] |
100
+
101
+ **Rules for good variants:**
102
+ - Change ONE thing per test (isolate the variable)
103
+ - Make the change significant enough to detect (don't test subtle color shifts)
104
+ - Each variant should have a clear hypothesis
105
+ - Don't test more than 3 variants (dilutes traffic)
106
+
107
+ ### Step 3: Sample Size
108
+
109
+ Calculate required test duration:
110
+
111
+ ```
112
+ Daily impressions: [N]
113
+ Current conversion rate: [X]%
114
+ Minimum detectable effect: [Y]% (relative improvement)
115
+ Confidence level: 95%
116
+
117
+ Required sample per variant: ~[N] impressions
118
+ Estimated duration: [N] days
119
+ ```
120
+
121
+ **Rules of thumb:**
122
+ - < 1000 daily impressions: Tests take 30-90 days (consider if worth it)
123
+ - 1000-5000 daily impressions: Tests take 14-30 days
124
+ - 5000+ daily impressions: Tests take 7-14 days
125
+ - Need at least 1000 impressions per variant for meaningful results
126
+
127
+ ### Step 4: Run the Test
128
+
129
+ **In App Store Connect:**
130
+ 1. Go to Product Page Optimization
131
+ 2. Create a new test
132
+ 3. Upload variant assets
133
+ 4. Set test duration (recommend: let it run until statistical significance)
134
+ 5. Monitor but don't stop early
135
+
136
+ ### Step 5: Interpret Results
137
+
138
+ **Statistical significance:**
139
+ - Apple requires 90% confidence minimum
140
+ - Aim for 95% confidence before making decisions
141
+ - Look at the confidence interval, not just the point estimate
142
+
143
+ **What to look for:**
144
+ - Conversion rate lift (primary metric)
145
+ - Impression-to-tap rate (for icon tests)
146
+ - Download rate (for screenshot/video tests)
147
+ - Segment differences (new vs returning, country, source)
148
+
149
+ ## Common Test Ideas
150
+
151
+ ### Icon Tests
152
+
153
+ | Test | Control | Variant | Expected Impact |
154
+ |------|---------|---------|----------------|
155
+ | Color | Current color | Contrasting color | 5-20% TTR change |
156
+ | Style | Detailed | Simplified | 5-15% TTR change |
157
+ | Element | Current symbol | Different symbol | 5-20% TTR change |
158
+ | Background | Solid | Gradient | 3-10% TTR change |
159
+
160
+ ### Screenshot Tests
161
+
162
+ | Test | Control | Variant | Expected Impact |
163
+ |------|---------|---------|----------------|
164
+ | First screenshot | Feature-focused | Benefit-focused | 10-30% CVR change |
165
+ | Social proof | No social proof | "5M+ users" badge | 5-15% CVR change |
166
+ | Text size | Small text | Large, bold text | 5-10% CVR change |
167
+ | Style | Light mode | Dark mode | 5-15% CVR change |
168
+ | Layout | Device frame | Full-bleed | 5-10% CVR change |
169
+ | Order | Current order | Reordered by benefit | 5-15% CVR change |
170
+
171
+ ### Video Tests
172
+
173
+ | Test | Control | Variant | Expected Impact |
174
+ |------|---------|---------|----------------|
175
+ | Has video | No video | 15s feature demo | 5-15% CVR change |
176
+ | Hook | Feature demo | Problem/solution | 5-10% CVR change |
177
+ | Length | 30s | 15s | 3-8% CVR change |
178
+
179
+ ## Output Format
180
+
181
+ ### Test Plan
182
+
183
+ ```
184
+ Test Name: [descriptive name]
185
+ Element: [icon / screenshots / video]
186
+ Hypothesis: If we [change], then [metric] will [improve] because [reason]
187
+
188
+ Variants:
189
+ - Control (A): [description]
190
+ - Variant B: [description]
191
+ - Variant C: [description] (optional)
192
+
193
+ Estimated Duration: [N] days
194
+ Required Impressions: [N] per variant
195
+ Success Metric: [conversion rate / tap-through rate]
196
+ Minimum Detectable Effect: [X]%
197
+ ```
198
+
199
+ ### Test Results Interpretation
200
+
201
+ When the user shares results:
202
+ 1. Is it statistically significant? (confidence level)
203
+ 2. What's the actual lift? (with confidence interval)
204
+ 3. Are there segment differences?
205
+ 4. What's the next test to run?
206
+ 5. Estimated annual impact (downloads × lift)
207
+
208
+ ### Testing Roadmap
209
+
210
+ Provide a 3-month testing calendar:
211
+ - Month 1: [highest impact test]
212
+ - Month 2: [second priority test]
213
+ - Month 3: [third priority test]
214
+
215
+ ## Related Skills
216
+
217
+ - `screenshot-optimization` — Design screenshot variants
218
+ - `metadata-optimization` — Optimize non-testable elements
219
+ - `app-analytics` — Track conversion metrics
220
+ - `aso-audit` — Identify what to test first
@@ -0,0 +1,197 @@
1
+ ---
2
+ name: android-aso
3
+ description: When the user wants to optimize their Google Play Store listing — title, short description, full description, keywords, ratings, or Play Store-specific features. Use when the user mentions "Google Play", "Android", "Play Store", "Play Console", "short description", "full description indexed", "Google Play ASO", or wants Google Play-specific keyword, creative, or ratings strategy. For iOS App Store optimization, see aso-audit and metadata-optimization.
4
+ metadata:
5
+ version: 1.0.0
6
+ ---
7
+
8
+ # Android ASO (Google Play)
9
+
10
+ You are a Google Play ASO expert. Google Play's algorithm differs fundamentally from iOS — the full description is indexed, there is no hidden keyword field, and ratings are continuous (not version-reset).
11
+
12
+ ## Key Differences vs iOS
13
+
14
+ | Factor | Google Play | Apple App Store |
15
+ |--------|------------|----------------|
16
+ | **Keyword indexing** | Title + Short desc + Full desc (all indexed) | Title + Subtitle + Keyword field only |
17
+ | **Hidden keyword field** | ✗ None | ✓ 100-char field |
18
+ | **Description indexed** | ✓ Full 4000 chars | ✗ Not indexed |
19
+ | **Ratings** | Continuous — never reset | Reset per version (can request reset) |
20
+ | **A/B testing** | Play Store Experiments (native) | Product Page Optimization |
21
+ | **Screenshots** | 2–8 per language | Up to 10 per language |
22
+ | **Feature graphic** | Required (1024×500px) | Not applicable |
23
+ | **Algorithm signals** | Installs, engagement, ratings, keywords | Keyword match, ratings, conversions |
24
+ | **Review indexing** | Reviews and replies indexed | Not indexed |
25
+
26
+ ## Character Limits
27
+
28
+ | Field | Limit | Indexed | Weight |
29
+ |-------|-------|---------|--------|
30
+ | **Title** | 30 chars | ✓ | Highest |
31
+ | **Short description** | 80 chars | ✓ | High |
32
+ | **Full description** | 4000 chars | ✓ | Medium |
33
+ | **Developer name** | — | ✓ | Low |
34
+
35
+ ## Initial Assessment
36
+
37
+ 1. Check for `app-marketing-context.md`
38
+ 2. Ask: **Do you have Play Console access?** (for actual keyword data)
39
+ 3. Ask: **What is your current title and short description?**
40
+ 4. Ask: **What are your 3 most important keywords?**
41
+ 5. Ask: **What category is your app in?**
42
+
43
+ ## Metadata Optimization
44
+
45
+ ### Title (30 chars)
46
+
47
+ - Lead with your brand name or primary keyword — whichever is stronger
48
+ - Include 1 high-volume keyword naturally: `Brand – Keyword Descriptor`
49
+ - ✅ "Headspace: Meditation & Sleep" | ❌ "Best Meditation App for You"
50
+
51
+ ### Short Description (80 chars)
52
+
53
+ - First thing users read on search results
54
+ - Pack your 2–3 most important keywords naturally in one compelling sentence
55
+ - ✅ "Guided meditation, sleep sounds & breathing exercises for stress relief"
56
+ - Do not repeat the title's primary keyword
57
+
58
+ ### Full Description (4000 chars — indexed)
59
+
60
+ **Structure for algorithm + conversion:**
61
+
62
+ ```
63
+ [Hook paragraph — 2–3 sentences]
64
+ Lead with the core value proposition. Include primary keyword in first 167 chars
65
+ (shown above the fold).
66
+
67
+ [Feature bullets — 5–8 items]
68
+ • [Feature]: [Benefit]
69
+ Use keywords naturally. Vary phrasing — don't repeat exact phrases.
70
+
71
+ [Social proof]
72
+ "Trusted by X million users" / awards / press mentions
73
+
74
+ [Call to action]
75
+ Download [App Name] today — [value prop].
76
+
77
+ [Keywords section — natural, not stuffed]
78
+ A paragraph using keyword variants, synonyms, and long-tail terms.
79
+ ```
80
+
81
+ **Keyword density rule:** Target keyword should appear 3–5 times across the full description. Exact match + variants. Never stuff.
82
+
83
+ ### Localization
84
+
85
+ Google Play indexes descriptions per language. Each locale is a fresh keyword opportunity — translate and localize, don't just auto-translate.
86
+
87
+ ## Keyword Research for Play Store
88
+
89
+ Use Appeeky keyword tools, then adapt for Play:
90
+
91
+ ```bash
92
+ GET /v1/keywords/metrics?keywords=meditation,mindfulness,sleep sounds&country=us
93
+ GET /v1/keywords/suggestions?term=meditation&country=us
94
+ ```
95
+
96
+ **Play-specific considerations:**
97
+ - Long-tail phrases work well (full description is indexed)
98
+ - Semantic similarity matters — Google's algorithm understands synonyms
99
+ - User reviews and Q&A also get indexed — common words in reviews can signal keywords
100
+
101
+ ## Feature Graphic (1024×500px)
102
+
103
+ Required for Play Store. Appears at the top of your listing when no video is present.
104
+
105
+ - Show the core use case in one image
106
+ - Text is legible — no tiny copy
107
+ - Brand-consistent with screenshots
108
+ - Works without text (text may be truncated on some surfaces)
109
+
110
+ ## Ratings Strategy
111
+
112
+ Unlike iOS, Play ratings are **never reset** — every rating ever given counts.
113
+
114
+ **To improve your rating:**
115
+ 1. Respond to every 1–3 star review (boosts score algorithmically)
116
+ 2. Reply invites re-rating — users can update their review
117
+ 3. Use `review-management` skill for response templates
118
+ 4. Fix the issues mentioned in low ratings and reply: "Fixed in version X.X"
119
+
120
+ **Rating prompt timing** (see also `rating-prompt-strategy` skill):
121
+ - Prompt after a clear success moment, not on cold open
122
+ - Use the Play In-App Review API: `ReviewManager.requestReviewFlow()`
123
+
124
+ ## Play Store Experiments (A/B Testing)
125
+
126
+ Native A/B testing for:
127
+ - Icon
128
+ - Feature graphic
129
+ - Screenshots (up to 3 variants)
130
+ - Short description (up to 3 variants)
131
+ - Full description (up to 3 variants)
132
+
133
+ Access: Play Console → Store listing experiments
134
+
135
+ **Test one element at a time. Run for minimum 7 days or 1,000 impressions.**
136
+
137
+ ## Pre-Launch (Early Access)
138
+
139
+ Use Early Access to:
140
+ - Collect reviews before public launch
141
+ - Get indexed by Google before launch
142
+ - Get editorial consideration from Google Play
143
+
144
+ ## Output Format
145
+
146
+ ### Play Store Listing Draft
147
+
148
+ ```
149
+ Title (30): [text]
150
+ Short desc (80): [text]
151
+
152
+ Full Description:
153
+ [Hook — 2–3 sentences, primary keyword in first 167 chars]
154
+
155
+ ✨ Features:
156
+ • [Feature]: [Benefit]
157
+ • [Feature]: [Benefit]
158
+ • [Feature]: [Benefit]
159
+ • [Feature]: [Benefit]
160
+ • [Feature]: [Benefit]
161
+
162
+ [Social proof paragraph]
163
+
164
+ [CTA sentence]
165
+
166
+ [Keyword-rich closing paragraph]
167
+
168
+ Keywords targeted: [list primary keywords used]
169
+ ```
170
+
171
+ ### ASO Audit (Play)
172
+
173
+ Score each field 1–10:
174
+
175
+ ```
176
+ Title: [N]/10 — [note]
177
+ Short description: [N]/10 — [note]
178
+ Full description: [N]/10 — [note]
179
+ Screenshots: [N]/10 — [note]
180
+ Feature graphic: [N]/10 — [note]
181
+ Ratings: [N]/10 — [note]
182
+ Overall: [N]/60
183
+
184
+ Top 3 improvements:
185
+ 1. [specific change with expected impact]
186
+ 2. [specific change with expected impact]
187
+ 3. [specific change with expected impact]
188
+ ```
189
+
190
+ ## Related Skills
191
+
192
+ - `aso-audit` — iOS-focused audit (compare approaches)
193
+ - `metadata-optimization` — iOS metadata (different field rules)
194
+ - `review-management` — Respond to Play reviews to recover rating
195
+ - `rating-prompt-strategy` — In-App Review API timing and strategy
196
+ - `ab-test-store-listing` — Play Experiments methodology
197
+ - `localization` — Per-language listing optimization