广告情报免费版（Ad Creative Intel Free）

面向买量投放、创意策划、市场研究人员的轻量级广告情报查询工具。在一个会话内完成创意搜索、应用洞察、榜单查询三件事，所有结果以原始结构化 JSON 返回，由调用 Agent 决定分析与呈现方式。

本免费版面向个人用户试用与轻量查询场景。如需批量导出、历史趋势回溯、下载/收入预估数据等高级能力，请使用 ad-creative-intel-pro 专业版。

设计动机：四大高频痛点

使用流程

Step 1：检查 API Key（< 10 秒）

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

若输出 ok 进入步骤 2；若输出 missing，按"API Key 配置"章节完成设置后重试。

Step 2：发现筛选元数据（< 30 秒）

首次使用前调用一次筛选元数据接口，缓存国家、媒体、广告类型、行业等代码表：

curl -s "https://api.ad-creative-intel.com/api/data/filter-options" \
  -H "X-API-Key: ${ADC_INTEL_API_KEY}"

Step 3：执行第一次创意搜索（< 60 秒）

curl -s -X POST "https://api.ad-creative-intel.com/api/data/search" \
  -H "X-API-Key: ${ADC_INTEL_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"rpg","countries":["US"],"mediaChannels":[1],"pageSize":10,"page":1}'

返回原始 JSON，包含 list（创意列表）、totalSize、pageIndex 等字段。

Step 4：查看创意详情（< 20 秒）

curl -s "https://api.ad-creative-intel.com/api/data/content-detail?contentId=XXXXX&related=imagevideo" \
  -H "X-API-Key: ${ADC_INTEL_API_KEY}"

核心能力

1. 广告创意搜索

提供关键词与多维度筛选的创意搜索能力，返回原始结构化数据。

关键参数约束：

• pageSize 上限为 10（超过自动降为 10，使用 page 翻页）
• countries、mediaChannels、adTypes 等筛选代码需从 /filter-options 获取
• tradeLevel 为树形结构（如 602=游戏、607=金融），子行业需调用维度接口

输入: 用户提供广告创意搜索所需的指令和必要参数。 处理: 按照skill规范执行广告创意搜索操作,遵循单一意图原则。 输出: 返回广告创意搜索的执行结果,包含操作状态和输出数据。

2. 应用与开发者洞察

查询应用、开发者、SDK 等基础信息，构建"创意-应用-开发者"三层数据视图。

输入: 用户提供应用与开发者洞察所需的指令和必要参数。 处理: 按照skill规范执行应用与开发者洞察操作,遵循单一意图原则。 输出: 返回应用与开发者洞察的执行结果,包含操作状态和输出数据。

3. 应用商店榜单查询

查询应用商店排名数据，支持免费/付费/畅销榜与分类榜单。

输入: 用户提供应用商店榜单查询所需的指令和必要参数。 处理: 按照skill规范执行应用商店榜单查询操作,遵循单一意图原则。 输出: 返回应用商店榜单查询的执行结果,包含操作状态和输出数据。 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：解决竞品创意看不、投放动态摸不透、榜单变化追不到的、免费广告情报查询、广告情报免费版是、面向买量投放、创意策划、市场研究人员的轻、量级广告情报查询、竞品创意素材分散、在多平台难以横向、新投放素材发现滞、应用榜单排名变化、无法及时追踪、缺乏统一的数据查、询入口、四大痛点而设计、它把多源广告情报、数据封装为统一查、询接口、让用户在一个会话、内完成创意搜索、应用洞察、榜单查询三件事等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

参数映射与筛选代码

调用搜索类端点前，需将自然语言转换为 API 代码：

未覆盖代码的获取方法：调用 GET /api/data/filter-options 拉取完整代码表，或调用端点专属维度接口（如 store-categories）。

输出规则

• 严格返回 API 响应的原始结构化 JSON，保留 API 字段名
• 不重命名、删除、汇总、排序或编辑加工数据
• 不生成 H5/落地页/卡片/仪表盘
• 不自动运行多步研究或产出分析建议（除非用户明确要求）
• 空的 list 是合法结果（无匹配），不是错误
• 第三方预估数据（如下载/收入）必须原样返回，呈现时由调用方标注"预估值"
• 若工具协议实现可用，优先使用工具协议工具调用；否则直接调用 HTTP 端点

示例

场景一：买量团队监控竞品 RPG 游戏创意

任务：调研美国市场近 30 天 RPG 游戏类广告创意 Top 50

执行步骤：
1. 调用 /filter-options 获取 trade_level1=602（游戏）确认
2. 调用 /search：
   {
     "keyword": "rpg",
     "countries": ["US"],
     "tradeLevel1": "602",
     "dateRange": "30d",
     "pageSize": 10,
     "page": 1
   }
3. 翻页 5 次收集 50 条创意
4. 调用 /count-all 按 adType 分组统计
5. 输出原始 JSON 与统计概览

注意：本免费版单次 pageSize 上限 10，需翻页 5 次

场景二：创意策划寻找金融类短视频灵感

任务：查找金融行业（tradeLevel1=607）的视频类广告创意

执行步骤：
1. 调用 /filter-options 确认 creativeType=010（视频）
2. 调用 /search：
   {
     "tradeLevel1": "607",
     "creativeType": "010",
     "pageSize": 10
   }
3. 对感兴趣的创意调用 /content-detail 获取详情
4. 调用 /item-apps 追溯关联应用，了解是哪个产品在投
5. 输出创意列表 + 关联应用清单

场景三：应用开发者跟踪自家产品榜单变化

任务：查询美国 App Store 游戏分类免费榜 Top 100，看自家产品是否上榜

执行步骤：
1. 调用 /store-categories 获取游戏分类代码
2. 调用 /store-rank：
   {
     "country": "US",
     "category": "<game_category_code>",
     "rankType": "free",
     "pageSize": 100
   }
3. 在返回的 list 中查找自家产品 unifiedProductId
4. 若需进一步定位产品详情，调用 /app-detail
5. 输出榜单原始数据 + 自家产品排名位置

场景四：市场研究员分析某开发者全部在投创意

任务：调研开发者 "Supercell" 旗下所有应用当前在投的广告创意

执行步骤：
1. 调用 /company-search 搜索 "Supercell" 获取开发者 ID
2. 调用 /developer-detail 获取其应用列表
3. 对每个应用调用 /product-content-search 获取创意
4. 调用 /product-content-counts 统计各应用创意数
5. 输出开发者-应用-创意三层视图（原始 JSON）

API Key 配置

调用前必须配置 ADC_INTEL_API_KEY 环境变量。若未配置，本技能会输出缺 Key 引导而非直接报错。

配置方式

方式一：环境变量（推荐）

# Linux / macOS
export ADC_INTEL_API_KEY="your_api_key_here"

# Windows PowerShell
$env:ADC_INTEL_API_KEY = "your_api_key_here"

方式二：Agent 平台配置

skill-platform config set skills.entries.ad-creative-intel.apiKey "your_api_key_here"

获取 API Key

1. 访问广告情报数据服务官网注册账号
2. 登录后在控制台找到 API Keys 菜单
3. 创建一个新的 Key 并复制保存
4. 按上述方式配置到环境中

安全提示：永远不要在对话中打印、回显或存储 API Key。本技能仅通过环境变量读取，不会接受用户在对话中直接输入的 Key。

错误处理

Agent 层错误（未发起请求）

当 ADC_INTEL_API_KEY 缺失时，返回结构化错误而非崩溃：

{
  "error": {
    "code": "missing_api_key",
    "message": "未配置 ADC_INTEL_API_KEY 环境变量",
    "retry": false,
    "guide": "请参考 API Key 配置章节完成设置后重试"
  }
}

API 层错误（请求返回非 2xx）

API 返回 { "detail": "...", "code": "..." }，本技能原样透传并附加 HTTP 状态码：

FAQ

Q1：免费版有没有调用次数限制？ A：没有次数限制。免费版仅限制 3 项高级功能（批量导出 >10 条/次、历史趋势回溯、下载/收入预估数据），日常创意搜索、应用查询、榜单查询不限次数。

Q2：为什么 pageSize 被自动改成 10？ A：免费版单次返回上限为 10 条，超过会自动 clamp 为 10。使用 page 参数翻页可获取更多数据。专业版支持更大单次返回。

Q3：返回的 list 为空是出错了吗？ A：不是。空的 list 是合法结果，表示当前筛选条件下无匹配创意。请检查筛选代码是否正确（可调用 /filter-options 核对）。

Q4：下载/收入数据为什么返回 403？ A：下载/收入预估数据属于高级功能，免费版无权限访问。如需此数据请使用专业版 ad-creative-intel-pro。

Q5：能否同时查询多个国家的数据？ A：可以。countries 参数支持数组，如 ["US","JP","KR"]。但跨地区对比分析需调用方自行聚合，本技能返回原始 JSON 不做加工。

Q6：创意详情里的 related=imagevideo 是什么意思？ A：表示同时返回该创意的图片与视频素材信息。可选值取决于 /screen-types 返回的代码表。

故障排查

已知限制

本免费体验版限制以下高级功能：

• ❌ 批量导出：单次返回上限 10 条，无法一次性导出大批量数据（专业版支持无上限）
• ❌ 历史趋势回溯：无法查询历史时间段的创意/榜单变化趋势（专业版支持任意时间段回溯）
• ❌ 下载/收入预估数据：无法访问 /download-* 与 /revenue-* 端点（专业版开放全部预估数据）

解锁全部功能请使用专业版：ad-creative-intel-pro

依赖说明

运行环境

• Agent 平台：支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
• 操作系统：Windows / macOS / Linux
• 网络：需可访问 api.ad-creative-intel.com 域名

依赖详情

API Key 配置

• 存储位置：环境变量 ADC_INTEL_API_KEY
• 禁止：在 SKILL.md 或脚本中硬编码 Key
• 禁止：在对话中接受用户输入的 Key 并回显

可用性分类

• 分类：MD+EXEC（纯 Markdown 指令，部分功能需 exec 执行 curl 命令）
• 说明：基于 Markdown 的 AI Skill，通过自然语言指令驱动 Agent 调用广告情报数据 API

License 与版权声明

本 skill 基于原始作品改进，保留原始版权声明：

• 原始作品：广告创意数据 API 客户端
• 原始 license：MIT
• 改进作品：© 2026 Ad Creative Intel
• 改进 license：MIT

本改进作品在原始作品基础上进行了深度差异化改造，包括但不限于：

• 重新设计为中文痛点导向的免费/专业双版本架构
• 新增四大痛点对策矩阵与场景化使用指南
• 新增 FAQ、故障排查表、API Key 安全配置规范
• 新增筛选元数据自动发现机制与参数映射说明
• 移除原项目专属标识，统一为"广告情报数据服务"抽象命名
• 将工具协议引用从特定实现改为通用"工具协议"标准术语
• 新增分级时间快速开始与 4 个真实场景示例

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

适用场景

任务：调研美国市场近 30 天 RPG 游戏类广告创意 Top 50

执行步骤：
1. 调用 /filter-options 获取 trade_level1=602（游戏）确认
2. 调用 /search：
   {
     "keyword": "rpg",
     "countries": ["US"],
     "tradeLevel1": "602",
     "dateRange": "30d",
     "pageSize": 10,
     "page": 1
   }
3. 翻页 5 次收集 50 条创意
4. 调用 /count-all 按 adType 分组统计
5. 输出原始 JSON 与统计概览

注意：本免费版单次 pageSize 上限 10，需翻页 5 次

不适用场景

以下场景广告情报免费版不适合处理：

• 实时流数据处理
• 小规模数据手动分析
• 非结构化文本情感分析

触发条件

需要数据分析、报表生成、统计洞察、数据可视化时使用。不适用于非本工具能力范围的需求。