AdPilot Skill Pack

AdPilot Skill Pack is a lightweight, local-first advertising analysis skill pack for agent coding environments such as Claude Code, Codex, Cursor, and similar tools.

It helps agents analyze exported advertising CSV/JSON files with deterministic Python scripts instead of asking the model to invent metrics. The first version focuses on Chinese advertising workflows while keeping common English field aliases compatible.

This repository is only the open-source skill pack. It does not include the original AdPilot web platform, OAuth integrations, account systems, backend services, or real advertising platform write operations.

What is included

Shared calculation code lives in skills/_shared/adpilot_common.py. Example data lives in skills/fixtures/.

Requirements

• Python 3.10 or newer recommended.
• No Python package installation is required; scripts use the standard library only.
• No backend, database, OAuth, API key, or advertising account connection is required.

Quick start

Clone the repository and run scripts from the repository root:

git clone https://github.com//adpilot-skill-pack.git
cd adpilot-skill-pack
python3 skills/adpilot-normalize-report/scripts/normalize_report.py skills/fixtures/mock_ad_data.json

Run the six core workflows:

python3 skills/adpilot-normalize-report/scripts/normalize_report.py skills/fixtures/mock_ad_data.json
python3 skills/adpilot-diagnose/scripts/diagnose.py skills/fixtures/mock_ad_data.json
python3 skills/adpilot-budget-planner/scripts/budget_plan.py skills/fixtures/mock_ad_data.json --total-budget 100000
python3 skills/adpilot-anomaly-scan/scripts/anomaly_scan.py skills/fixtures/anomaly_report.csv
python3 skills/adpilot-health-score/scripts/health_score.py skills/fixtures/mock_ad_data.json
python3 skills/adpilot-report-export/scripts/export_report.py skills/fixtures/mock_ad_data.json --output /tmp/adpilot-report.md

Every script prints JSON to stdout. adpilot-report-export can also write a Markdown file with --output.

Using with an agent

Point your agent at the relevant SKILL.md file, or copy the full skills/ directory into a location supported by your agent runtime.

Keep the entire skills/ directory together. The individual skill entrypoints depend on the shared helper at skills/_shared/adpilot_common.py.

Example user request:

Use adpilot-diagnose to analyze skills/fixtures/mock_ad_data.json and list the top three optimization actions.

The agent should run the matching Python script and base all numeric claims on the JSON output.

Input schema

The normalizer accepts common Chinese and English aliases and maps them into:

Metric formulas:

• ROI = (revenue - spend) / spend * 100
• ROAS = revenue / spend
• CPA = spend / conversions
• CTR = clicks / impressions * 100
• CVR = conversions / clicks * 100
• D7 retention = retained_d7 / new_users * 100

Missing numeric fields default to 0; warnings are included in script output.

Validation

If you have access to the Codex skill validator, run:

python3 /path/to/skill-creator/scripts/quick_validate.py skills/adpilot-normalize-report
python3 /path/to/skill-creator/scripts/quick_validate.py skills/adpilot-diagnose
python3 /path/to/skill-creator/scripts/quick_validate.py skills/adpilot-budget-planner
python3 /path/to/skill-creator/scripts/quick_validate.py skills/adpilot-anomaly-scan
python3 /path/to/skill-creator/scripts/quick_validate.py skills/adpilot-health-score
python3 /path/to/skill-creator/scripts/quick_validate.py skills/adpilot-report-export

You can also run the smoke commands in the Quick start section. Each command should return JSON with "status": "ok".

Safety and limitations

• This project only processes local CSV/JSON exports.
• It does not log in to ad platforms or read live ad accounts.
• It does not execute real campaign changes.
• It does not provide financial, legal, or guaranteed growth advice.
• Budget recommendations are analytical suggestions and should be reviewed by a human operator.

License

MIT. See LICENSE.

中文说明

AdPilot Skill Pack 是一个轻量广告分析技能包，适合在 Claude Code、Codex、Cursor 等 agent 环境中使用。它的目标不是替代广告平台后台，而是让投放人员把本地导出的 CSV/JSON 报表交给 agent，由确定性脚本完成指标计算，再由模型解释结果。

第一版重点覆盖：报表归一、整体诊断、预算建议、异常扫描、健康分、中文复盘报告。所有数字都应来自脚本输出，不应由模型自由编造。