前言¶

做投放分析、競品素材調研或應用商店情報時，常見做法是在瀏覽器裏反覆點篩選，或自己寫腳本拼 curl。數據維度一多（創意、應用、排名、下載與收入估算），接口參數和枚舉碼又分散在多份文檔裏，Agent 很難在對話裏穩定復現同一套查詢。

下面介紹 SkillHub 上的 @zcwl/admapix（AdMapix廣告投放工具）。它把 AdMapix 讀 API 封裝成 Agent 可執行的 SKILL 指令：按端點拉取原始 JSON，由調用方 Agent 決定調用哪些接口、如何組合多步流程以及如何做分析，Skill 本身不做彙總、排行解讀或自動生成報告頁。

這是什麼¶

一句話定位：AdMapix 廣告原始數據層的薄客戶端 Skill，覆蓋廣告創意、應用/產品、排名、下載與收入等讀接口。

維護與來源：發佈者爲智創未來，Skill 座標 @zcwl/admapix，當前版本 1.0.5，SkillHub 分類爲 business-ops，來源標記爲 enterprise。官方入口：SkillHub 頁面、API 座標頁。

SkillHub 側數據（以抓取資料爲準）：評分 100000，下載 220399；標籤含 requires_api_key=true，使用前必須配置 AdMapix API Key。

核心功能¶

Skill 明確不在範圍內的能力包括：HTML/H5 頁面生成、託管式「深度研究」、自主多步調研、摘要與洞察、推薦、儀表盤、代發消息等。實際提供的是對 https://api.admapix.com/api/data/ 下各端點的結構化訪問說明，主要能力分組如下（均返回 API 原始 JSON，字段名保持原樣）。

1. 創意 / 廣告：如 POST /api/data/search 搜索創意，POST /api/data/count、count-all、distribute 做計數與分佈，GET /api/data/content-detail 查單條創意詳情等。
2. 元數據 / 篩選：GET /api/data/filter-options 拉取國家、媒體渠道、廣告類型、設備等過濾枚舉，用於把自然語言條件映射爲合法參數碼。
3. 應用 / 產品 / 公司：統一產品搜索、應用詳情、開發者詳情、相似應用、SDK、與產品關聯的創意等（如 unified-product-search、app-detail、similar-apps 等）。
4. 排名：應用商店榜單（store-rank）、通用榜單（generic-rank）及類目、國家碼錶接口。
5. 下載與收入：按日期、明細、國家維度的下載與收入估算接口；Skill 註明此類數字爲第三方估算，非官方實數，展示時需由 Agent 向用戶說明。
6. 分發與市場：應用級分發、全球推廣及市場級檢索聚合等。

創意搜索若宿主提供 admapix.search_creatives 協議工具則優先使用；否則直接 POST /api/data/search。search 的 page_size 上限爲 10，更大請求需 clamp 並用 page 翻頁。

觸發關鍵詞（Skill 元數據）：apps、admapix、data、creatives、layer。

安裝與啓用¶

安裝 SkillHub CLI（若尚未安裝）¶

先檢查是否已有 CLI：

command -v skillhub && skillhub --version

未安裝時可按 SkillHub 官方說明執行（完整安裝或僅 CLI）：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
# 僅 CLI：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only

安裝 @zcwl/admapix¶

安裝時必須用 --dir 指向當前 Agent 的 skills 目錄，否則默認落在 ./skills/ 可能無法被識別。常用路徑示例：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或項目下的 .agents/skills/

安裝命令（與 SkillHub 搜索條目一致）：

skillhub install admapix --namespace zcwl --dir ~/.cursor/skills/

SkillHub 頁面也支持讓 AI 按 SkillHub 安裝說明 安裝 @zcwl/admapix；邏輯等價於上述 CLI 流程。

安裝完成後重啓或刷新 Agent，使 SKILL.md 被加載。

配置 AdMapix API Key¶

Skill 使用環境變量 ADMAPIX_API_KEY，請求時作爲 HTTP 頭 X-API-Key 發送；不得在日誌或回覆中打印 Key。

檢查是否已配置（不輸出 Key 值）：

[ -n "${ADMAPIX_API_KEY:-}" ] && echo ok || echo missing

未配置時，Skill 要求引導用戶到 admapix.com 註冊並在控制台創建 API Key，然後任選其一：

export ADMAPIX_API_KEY="你的_API_KEY"

或在 Skill 平臺 / SkillHub 場景：

skill-platform config set skills.entries.admapix.apiKey "你的_API_KEY"

無 Key 時不應發起 API 調用；Agent 層應返回 missing_api_key 錯誤結構（見 Skill 內 Error Handling）。

典型用法¶

1. 通用 GET/POST 調用模式¶

任意端點均可按同一模式用 curl 驗證（Agent 在對話中應等價執行，並遵守 Output Rules：不篡改、不摘要 API 字段）：

admapix_auth_header="X-API-Key: ${ADMAPIX_API_KEY}"
curl -s "https://api.admapix.com/api/data/{endpoint}?{params}" -H "$admapix_auth_header"
curl -s -X POST "https://api.admapix.com/api/data/{endpoint}" \
  -H "$admapix_auth_header" -H "Content-Type: application/json" -d '{...}'

將 {endpoint}、{params} 或 POST body 替換爲 SKILL.md 中 Endpoint Catalog 所列路徑與參數。首次使用某端點前，Skill 要求閱讀其對應的 references/*.md 以確認參數與響應字段；若安裝包內未附帶這些 reference 文件，可先調用 GET /api/data/filter-options 或端點自帶的維度接口獲取合法枚舉。

2. 創意搜索（直接 API）¶

在 Key 已配置的前提下，創意檢索走 POST /api/data/search（或宿主提供的 admapix.search_creatives）。響應中常見分頁字段爲 pageIndex、pageSize、totalSize、list；totalSize 在部分過濾條件下可能爲 null，此時以 list 長度爲準。空 list 表示無匹配，不是錯誤。

3. 多步工作流（由 Agent 編排）¶

Skill 設計爲單次請求返回單次原始結果。例如：先 filter-options 解析國家與渠道碼 → 再 search 拉創意 → 再 item-apps 或 product-content-search 關聯應用與素材。組合邏輯、對比與結論均由調用 Agent 完成，Skill 不提供內置分析模板。

適用場景與注意¶

適合誰

• 已在 Cursor、Claude Code、Codex 等支持 SKILL.md 的環境中工作，希望用自然語言驅動「查創意、查應用、看榜單、拉下載/收入估算」的投放與情報同學。
• 需要可審計的原始 JSON，便於自行入庫或再做 BI，而不是 Skill 內嵌的分析結論。

限制與注意

• 必須有 AdMapix API Key；401 且 INVALID_API_KEY / NOT_AUTHENTICATED 時不應盲目重試。
• 下載/收入爲估算值，對外呈現時需說明數據來源性質。
• 不要指望 Skill 生成 H5 落地頁、儀表盤或自動「調研報告」；這些屬於 Agent 在拿到數據之後的可選步驟，且需用戶明確要求。
• 安裝時使用 admapix --namespace zcwl，與座標 @zcwl/admapix 對應；僅寫 slug 可能匹配到其他命名空間的同名 Skill。

結尾¶

AdMapix廣告投放工具把 AdMapix 讀 API 收斂成 Agent 可執行的端點清單與調用規範：認證、參數映射、錯誤碼與「只返 JSON、不做分析」的邊界都寫在 SKILL 裏，適合作爲投放與應用情報的數據層接入對話式工作流。

官方 Skill 地址：https://www.skillhub.cn/skills/zcwl/admapix · https://api.skillhub.cn/zcwl/admapix