前言¶

做投放分析、竞品素材调研或应用商店情报时，常见做法是在浏览器里反复点筛选，或自己写脚本拼 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