Skip to content

Commit 50b48eb

Browse files
charlieviettqcharlieviettq
authored
Merge pull request #33 from charlieviettq/codex/asgard-skill-pack
feat: import asgard skill pack and bundles
2 parents d397330 + bc5221b commit 50b48eb

2,155 files changed

Lines changed: 431823 additions & 1300 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/skills/algo-ad-bidding/SKILL.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
name: "\"algo-ad-bidding\""
3+
description: "\"Implement and select ad bidding strategies from manual CPC to automated target-CPA and target-ROAS. Use this skill when the user needs to choose a bidding strategy, set up automated bidding, or optimize bid parameters — even if they say 'what bidding strategy should I use', 'target CPA setup', or 'smart bidding configuration'.\"."
4+
allowed-tools: Read, Glob, Grep
5+
---
6+
7+
# Ad Bidding Strategies
8+
9+
## Overview
10+
11+
Bidding strategies determine how much an advertiser pays per auction. Range from manual CPC (full control) to automated strategies (Target CPA, Target ROAS, Maximize Conversions) that use ML to optimize bids in real-time based on contextual signals.
12+
13+
## When to Use
14+
15+
**Trigger conditions:**
16+
- Choosing between manual and automated bidding strategies
17+
- Setting up or troubleshooting Target CPA / Target ROAS campaigns
18+
- Analyzing bid strategy performance and making adjustments
19+
20+
**When NOT to use:**
21+
- When designing the auction mechanism itself (use GSP/VCG)
22+
- When building a CTR prediction model (use CTR prediction skill)
23+
24+
## Algorithm
25+
26+
```
27+
IRON LAW: Automated Bidding Requires SUFFICIENT Conversion Data
28+
Below ~30 conversions/month, the algorithm lacks signal and performs
29+
WORSE than manual bidding. Strategy selection depends on data volume:
30+
- < 30 conv/month: Manual CPC or Maximize Clicks
31+
- 30-50 conv/month: Maximize Conversions
32+
- 50+ conv/month: Target CPA
33+
- 50+ conv/month + revenue data: Target ROAS
34+
```
35+
36+
### Phase 1: Input Validation
37+
Assess: monthly conversion volume, conversion tracking accuracy, campaign budget, business goal (volume vs efficiency vs revenue).
38+
**Gate:** Conversion tracking verified, sufficient data for chosen strategy.
39+
40+
### Phase 2: Core Algorithm
41+
**Manual CPC:** Set bid per keyword. Adjust based on: device, time, location, audience performance data.
42+
43+
**Target CPA:** 1. Set target cost-per-acquisition. 2. Algorithm predicts conversion probability per auction using contextual signals. 3. Bids up for high-probability conversions, down for low. 4. Aims to average at target CPA over time.
44+
45+
**Target ROAS:** Same as CPA but optimizes for return on ad spend = conversion_value / cost.
46+
47+
### Phase 3: Verification
48+
Monitor: actual CPA vs target, conversion volume stability, impression share changes, budget utilization.
49+
**Gate:** Actual CPA within 20% of target after learning period (2-4 weeks).
50+
51+
### Phase 4: Output
52+
Return strategy recommendation with expected performance ranges.
53+
54+
## Output Format
55+
56+
```json
57+
{
58+
"recommendation": {"strategy": "target_cpa", "target": 500, "currency": "TWD", "confidence": "high"},
59+
"expected_performance": {"cpa_range": [400, 600], "volume_change": "-10% to +15%"},
60+
"metadata": {"monthly_conversions": 85, "current_cpa": 550, "learning_period_days": 14}
61+
}
62+
```
63+
64+
## Examples
65+
66+
### Sample I/O
67+
**Input:** E-commerce campaign, 120 conversions/month, current CPA=NT$450, goal: maintain CPA, increase volume
68+
**Expected:** Target CPA at NT$450. Expected: volume +10-20% as algorithm finds efficient auctions.
69+
70+
### Edge Cases
71+
| Input | Expected | Why |
72+
|-------|----------|-----|
73+
| 10 conversions/month | Manual CPC | Insufficient data for automation |
74+
| Target CPA too aggressive | Volume drops to near zero | Algorithm can't find profitable auctions |
75+
| Conversion tracking broken | All strategies fail | Garbage data → garbage optimization |
76+
77+
## Gotchas
78+
79+
- **Learning period volatility**: First 2 weeks after switching strategies show unstable performance. Don't change targets during this period.
80+
- **Conversion delay**: If conversions take days to attribute (e.g., B2B), the algorithm optimizes on stale data. Use conversion modeling or extend the attribution window.
81+
- **Budget as a constraint**: Target CPA won't spend if it can't hit the target. Setting an aggressive CPA with a large budget doesn't increase spend — it just saves money.
82+
- **Micro-conversions**: If training on a proxy conversion (add to cart) instead of final purchase, the algorithm optimizes for the proxy. Ensure the tracked conversion aligns with business value.
83+
- **Seasonality shocks**: Automated bidding learns from recent data. Black Friday, holidays, or competitive events can throw it off. Use seasonality adjustments.
84+
85+
## References
86+
87+
- For bid strategy migration playbook, see `references/migration-playbook.md`
88+
- For learning period best practices, see `references/learning-period.md`

‎.claude/skills/algo-ad-bidding/examples/sample_scenario.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# Example: 家居品牌從手動 CPC 轉換至 Target CPA
2+
3+
## Scenario
4+
5+
**公司：** 居家生活電商 HomePlus（台灣本地品牌，年營收約 NT$8,000 萬）
6+
7+
**廣告帳戶狀況（2026 年 3 月）：**
8+
- 平台：Google Ads，搜尋廣告為主
9+
- 預算：NT$150,000 / 月
10+
- 目前策略：手動 CPC，平均出價 NT$12–35（依關鍵字分組）
11+
- 月轉換數：112 筆（追蹤事件：完成結帳）
12+
- 目前平均 CPA：NT$580
13+
- 目標 CPA：NT$500（行銷主管設定的 KPI）
14+
- 轉換追蹤：Google Ads Tag + GA4 匯入，已驗證無重複計算
15+
16+
**使用者問題：**
17+
> 我們手動出價很費時，帳戶有 112 筆月轉換，想改用自動出價。Target CPA 設多少合適？什麼時候可以切？切完要觀察哪些指標？
18+
19+
---
20+
21+
## Analysis
22+
23+
### Phase 1：Input Validation
24+
25+
| 檢核項目 | 數值 | 判斷 |
26+
|----------|------|------|
27+
| 月轉換數 | 112 筆 | ✅ 超過 50 筆門檻，可用 Target CPA |
28+
| 轉換追蹤準確性 | Google Tag + GA4 驗證通過 | ✅ 資料品質可信 |
29+
| 有無收益資料 | 有（結帳金額），但各 SKU 差異大 | Target ROAS 可考慮，但先以 CPA 穩定基線 |
30+
| 業務目標 | 降低 CPA（580→500）+ 維持量 | 效率優先 → Target CPA 適合 |
31+
| 月預算 | NT$150,000 | CPA 目標 NT$500 → 理論最大量：300 筆；目前量 112 筆，預算非瓶頸 |
32+
33+
**Gate 通過：** 轉換資料充足、追蹤正確、策略選擇明確。
34+
35+
---
36+
37+
### Phase 2：Core Algorithm 應用
38+
39+
**策略選擇：Target CPA**
40+
41+
依 Iron Law 數據門檻：
42+
- 112 conv/month >> 50 門檻 → Target CPA 可用
43+
- 有收益資料 → 未來可升級 Target ROAS，但目前 SKU 均價差異（NT$800–NT$4,500）會讓 ROAS 目標難以設定，先以 CPA 控制效率
44+
45+
**Target CPA 初始值設定：**
46+
47+
不應直接設目標值 NT$500（過於激進），應從當前表現開始緩步收斂：
48+
49+
```
50+
初始 Target CPA = 當前 CPA × 1.0 ~ 1.1
51+
= NT$580 × 1.05
52+
= NT$609（建議設 NT$600）
53+
```
54+
55+
原因：演算法在學習期需要足夠的拍賣空間找到轉換，若目標設得比現況低 14%，學習期曝光量會大幅萎縮，難以蒐集足夠訊號。
56+
57+
**收斂計畫（3 個月）：**
58+
59+
| 時段 | Target CPA | 預期操作 |
60+
|------|------------|----------|
61+
| 第 1–2 週（學習期） | NT$600 | 禁止調整，僅監控 |
62+
| 第 3–4 週 | NT$575 | 學習期結束後，若 CPA < NT$600 則降 |
63+
| 第 5–8 週 | NT$530 | 穩定後再收斂 |
64+
| 第 9–12 週 | NT$500 | 達成 KPI 目標 |
65+
66+
**出價邏輯（Target CPA 運作方式）：**
67+
68+
每次拍賣，演算法根據以下訊號預測轉換機率（P_conv）：
69+
- 使用者裝置、時段、地點
70+
- 搜尋意圖（查詢語意）
71+
- 受眾屬性（再行銷清單、相似受眾）
72+
- 歷史互動行為
73+
74+
出價公式：
75+
```
76+
bid = Target CPA × P_conv
77+
= NT$600 × P_conv
78+
79+
高意圖用戶（P_conv = 0.08）→ bid = NT$48
80+
低意圖用戶（P_conv = 0.01）→ bid = NT$6
81+
```
82+
83+
目標：跨所有拍賣平均 CPA 趨近 NT$600。
84+
85+
---
86+
87+
### Phase 3：Verification 指標
88+
89+
學習期（前 14 天）監控清單：
90+
91+
| 指標 | 基準值 | 警戒線 | 行動 |
92+
|------|--------|--------|------|
93+
| 日轉換數 | ~3.7 筆/天 | < 1 筆/天連續 5 天 | 檢查預算是否限制、CPA 是否過緊 |
94+
| 曝光份額 | （切換前記錄） | 下降 > 40% | Target CPA 可能過低，暫緩調降 |
95+
| 實際 CPA | NT$580 | > NT$800 | 學習期波動允許，超過才介入 |
96+
| 轉換追蹤正常 | 每日有數據 | 連續 2 天 0 轉換 | 立即查 Tag 是否失效 |
97+
98+
**Gate：** 第 14 天後，若實際 CPA 落在 NT$480–720（目標 ±20%），視為學習期通過。
99+
100+
---
101+
102+
### Gotchas 應對（本案適用）
103+
104+
1. **學習期波動**：告知行銷主管第 1–2 週 CPA 可能飆至 NT$800+，這是正常現象，不要在此期間更動目標值。
105+
106+
2. **轉換延遲**：HomePlus 分析顯示，消費者平均在點擊後 1.8 天完成購買。Google Ads 轉換窗口應設為 **30 天**（非預設 7 天），確保演算法拿到完整訊號。
107+
108+
3. **預算非瓶頸**：目前 112 筆 × NT$580 = NT$64,960 實際花費，遠低於 NT$150,000 預算。Target CPA 不會因預算充裕就放量——它只在找得到符合 CPA 目標的拍賣時才出價。勿期待切換後花費自動倍增。
109+
110+
4. **季節性衝擊**：6 月父親節、雙 11 前後，競價環境劇變。需提前在 Google Ads 設定**季節性調整（Seasonality Adjustment）**，避免演算法誤判。
111+
112+
---
113+
114+
## Result
115+
116+
```json
117+
{
118+
"recommendation": {
119+
"strategy": "target_cpa",
120+
"target": 600,
121+
"currency": "TWD",
122+
"confidence": "high",
123+
"rationale": "112 conv/month exceeds 50-conversion threshold; start at NT$600 (current CPA x1.05) to preserve learning signal, then step down to NT$500 over 12 weeks"
124+
},
125+
"expected_performance": {
126+
"cpa_range": [480, 720],
127+
"volume_change": "-5% to +20%",
128+
"note": "Volume may dip during 14-day learning period before recovering"
129+
},
130+
"convergence_plan": {
131+
"week_1_2": {"target_cpa": 600, "action": "freeze — learning period"},
132+
"week_3_4": {"target_cpa": 575, "action": "reduce if actual CPA < 600"},
133+
"week_5_8": {"target_cpa": 530, "action": "reduce if stable"},
134+
"week_9_12": {"target_cpa": 500, "action": "KPI target reached"}
135+
},
136+
"metadata": {
137+
"monthly_conversions": 112,
138+
"current_cpa": 580,
139+
"learning_period_days": 14,
140+
"conversion_window_recommended_days": 30,
141+
"budget_monthly_twd": 150000,
142+
"budget_is_binding": false
143+
}
144+
}
145+
```
146+
147+
**切換時機建議：** 避開促銷檔期（如雙 11、節慶），選在流量平穩的週二或週三上午切換，以確保學習期資料不被異常流量污染。

0 commit comments

Comments
 (0)