# Vk Ads Audit

> Аудит и анализ кабинета VK Рекламы (ads.vk.ru) только на чтение через MCP vk-ads, опционально с Метрикой. ГЛУБОКИЙ АУДИТ — структура кампаний, групп и объявлений, расход и результат, слив без конверсий, CPA выше цели, низкий CTR, выгорание креативов, голодание автостратегий, гигиена (пустые группы, отклонённые объявления, бюджеты, дубли таргетингов, пиксель), лидеры для масштабирования → HTML-отчёт с приоритетами и ограничениями. БЫСТРЫЙ АНАЛИЗ — сводка за вчера или неделю, аномалии в 10 строк. Триггеры: «аудит VK», «разбери кабинет VK», «почему дорогой лид в VK», «что отключить в VK», «как у нас в VK», «сводка VK за вчера», «как прошла неделя в VK». НЕ для создания и правки кампаний — это vk-ads-manager.

- Skill: `ai-hub-open/vk-ads-audit` (Agent Skill, multi-file: 30 files)
- Install (CLI): `npx get-skill add ai-hub-open/vk-ads-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ai-hub-open/vk-ads-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: ai-hub-open (https://skillmd.com/u/ai-hub-open)
- Updated: 2026-11-18
- Page: https://skillmd.com/skills/ai-hub-open/vk-ads-audit

---


# VK Реклама — аудит и анализ (только чтение)

Два режима над одним кабинетом:

- **Глубокий аудит** — разовая диагностика за период → `АУДИТ_<slug>.html` с находками по приоритету.
- **Быстрый анализ** — «как вчера/неделя» → 5–10 строк в чат, только аномалии.

**Скилл ничего не меняет в кабинете.** Скрипты ходят в MCP через белый список инструментов чтения
(`scripts/mcp_client.py`). Ты на пути A вызываешь **только** инструменты чтения: `*_list`, `*_get`,
`vk_ads_statistics_*`, `vk_ads_auth_check`, `vk_ads_account_info`, `vk_ads_accounts_list`. Просьбу «поправь»,
«выключи», «создай» передай в vk-ads-manager: находки сформулированы как действия.

**Просят изменить кабинет — прямой отказ, одним сообщением:**

1. **Прямо, первой фразой:** «Нет, я только читаю кабинет и не могу поставить кампанию на
   паузу». Назови действие словами пользователя.
2. **Где это сделать:** паузу, правку, создание — агент запуска VK Рекламы (vk-ads-manager)
   после вашего «ОК» или вы сами в кабинете ads.vk.ru; удаление и запуск — только вы в кабинете.
3. **Что можешь вместо:** передать находку агенту запуска или показать, на чём она основана, —
   вопросом.
4. **Стоп.** Не продолжай аудит и не переходи к следующему шагу, пока человек не ответит.

Инструмента нет среди доступных или вызов отклонён (`forbidden`, `not allowed`, `permission`,
`403`) — тоже отказ, а не сбой: не повторяй и не обходи, скажи человеку, что не получилось
прочитать, и запиши это в ограничения отчёта.

**Ты не считаешь.** Все числа — из `dataset.json` и `findings.json`, их считают скрипты. Твоя работа —
маршрут, вопросы, выводы словами и гейт.

## Проверка версии (один раз за разговор, до выбора режима)

Прочитай `VERSION` рядом с этим файлом и одним запросом загрузи
`https://raw.githubusercontent.com/ai-hub-open/vk-ads-audit/main/VERSION`.

- Совпадает или загрузить не вышло — молча работай дальше.
- На GitHub новее (semver) — одним сообщением: вышла X (у тебя Y),
  [CHANGELOG](https://github.com/ai-hub-open/vk-ads-audit/blob/main/CHANGELOG.md); обновление:
  Claude Code — `/plugin marketplace update ai-hub-open` и перезапуск; архив — скачать `vk-ads-audit.skill` из
  [релизов](https://github.com/ai-hub-open/vk-ads-audit/releases/latest). Спроси: обновиться или продолжить.

Файлы скилла сам не скачивай и не заменяй.

## Режим

| Запрос | Режим |
|---|---|
| «аудит», «разбери кабинет», «почему дорого», «что отключить», «найди точки роста» | Глубокий аудит |
| «как у нас», «сводка за вчера», «как прошла неделя», один конкретный вопрос | Быстрый анализ |

Не уверен — спроси одним вопросом.

## Где что лежит

Скрипты — в папке скилла, запуск `python -m scripts.<имя>` только оттуда. Рабочая папка —
`<папка пользователя>/vk-audits/<slug>-<YYYY-MM-DD>/`, **не внутри скилла**; `--workspace` всегда абсолютный.
Скрипты сами откажутся работать с папкой внутри скилла. Ниже `<ws>` — этот абсолютный путь.

**Повторный прогон — всегда новая рабочая папка** (`<slug>-<YYYY-MM-DD>-2`). Папку с заполненным `raw/`
не переиспользуй: сбор откажется (код 4), а ручное дописывание в чужой `raw/` смешает данные разных прогонов.

Запуска кода в среде нет — скилл работать не может (вся арифметика в скриптах): скажи об этом прямо.

---

# Глубокий аудит

## Шаг 0. Охват

1. Кабинет: `vk_ads_accounts_list`; несколько — покажи список, зафиксируй `account_id`.
2. Период: по умолчанию 30 последних полных дней (до вчера), минимум 14. Период всегда заканчивается
   не позже вчерашнего дня. VK хранит дневную статистику 366 дней: начало периода раньше — скажи пользователю
   доступную дату (путь B сам остановится с кодом 2 и назовёт её; ответ `WRONG_DATE` тоже разбирай так, а не показывай сырым).
3. Целевой CPA/CPL: спроси один раз. Нет — опорный CPA считается по медиане кабинета, в отчёте пометка.
4. Создай `<ws>`, запиши `_state.json`: `{"mode","account_id","date_from","date_to","target_cpa"}`.

## Шаг 1. Предполётка (только чтение)

1. `vk_ads_auth_check`, `vk_ads_account_info` (баланс, валюта, id пользователя).
2. Путь. **В claude.ai и Claude Desktop у коннектора vk-ads нет персональной ссылки подключения — там сбор всегда идёт
   путём A (ты вызываешь MCP сам и кладёшь ответы в `raw/`); ссылку у пользователя в этих средах не спрашивай и
   `collect --probe` не запускай.** Путь B — только там, где скрипты ходят в сеть сами (Claude Code, терминал) и ссылка
   есть: `python -m scripts.collect --probe --account-id <ID>`.
   - Код 0 → путь B.
   - Код 2 «ссылка не сохранена» → в Claude Code спроси у пользователя персональную ссылку подключения MCP
     (вид `https://…/c/<токен>`), сохрани: `python -m scripts.credentials set --url <ссылка>`, повтори probe.
     В чате ссылку не повторяй. Нет ссылки или probe снова 2 («путь B не работает») → путь A.
3. Расход за период (путь A; путь B делает это сам, пишет расход в `collect_log.json` и при 0 ₽ без живых групп
   выходит с кодом 5): один вызов
   `vk_ads_statistics_day(entity="users", ids=<id пользователя из account_info>, date_from, date_to, metrics="base")`.
   На пути A ответ положи в `<ws>/raw/` как обычный вызов (`vk_ads_statistics_day__NNN.json`, `entity: "users"`):
   по нему отчёт отличит «кабинет потратил 0 ₽» от «0 ₽ у живых групп». Расход 0 ₽ — вызови `vk_ads_campaigns_list`
   (строка 2 `references/mcp-read-tools.md`): живых групп нет (все `deleted` или с `ARCHIVED`) — скажи пользователю, что
   кабинет не откручивает, и предложи другой кабинет; сбор и отчёт не начинай. Живые группы есть — собирай дальше:
   отчёт выйдет с плашкой «0 ₽», скажи об этом пользователю и предложи другой период.
4. Метрика: есть ли коннектор Метрики; если да — какой счётчик (спроси или найди по домену посадочных).
5. Запиши выбор в `_state.json`, в чат одной строкой: «Путь B, Метрика: счётчик N» или что недоступно.

## Шаг 2. Сбор

**Путь B:** `python -m scripts.collect --workspace <ws> --account-id <ID> --date-from D --date-to D`.
Если дата конца позже вчера, скрипт сам сдвинет её и скажет об этом. Коды выхода:

| Код | Что значит | Что делать |
|---|---|---|
| 0 | сбор выполнен, возможно частично | ошибки отдельных вызовов — в `collect_log.json` (`errors`), они сами попадут в ограничения; сбор не повторяй вслепую |
| 2 | нет ссылки, probe не прошёл, неверные даты, период пуст после сдвига или старше истории VK (~366 дней) | исправь ввод или переходи на путь A; про историю — назови пользователю доступную дату из сообщения |
| 3 | критический сбой: список кампаний не получен, описи кабинета нет | покажи причину из `collect_log.json`; путь A — только в новой рабочей папке |
| 4 | `raw/` уже не пуст | возьми новую рабочую папку, старую не чисти и не дописывай |
| 5 | расход за период 0 и живых групп нет: собраны только списки кампаний и групп | скажи пользователю и предложи другой кабинет (0 ₽ при живых группах — код 0, отчёт с плашкой) |

**401.** `HTTP 401` в выводе probe/collect или в ошибке `collect_log.json` — ссылка подключения недействительна
или истекла: попроси у пользователя новую, `python -m scripts.credentials set --url <ссылка>`, повтори probe. На
молчаливый переход на путь A из-за 401 не соглашайся. 401 или ошибка авторизации на пути A — попроси переавторизовать
коннектор vk-ads и остановись.

Журнал `collect_log.json` пишется всегда; при падении посреди сбора в нём поле `aborted`.

**Путь A** — ты кладёшь ответы инструментов в `<ws>/raw/` по формату `scripts/raw_store.py`:
файл `<инструмент>__<NNN>.json` = `{"tool": ..., "arguments": {...}, "response": <ответ целиком, без правок>}`.
`NNN` — целое число; `tool` в содержимом совпадает с именем в названии файла. Для списков можно по файлу на
страницу либо один общий файл `{"items": [...]}` — но не оба сразу (дубли с разным содержимым останавливают
нормализацию); ответ списка — объект с массивом `items`.
**В `raw/` только такие файлы** — любой другой файл (заметки, черновики) ломает проверку.
Сбой — не данные: **ответ-ошибку в `raw/` не клади** (`isError`, `{"error": true, …}`): проверка его отвергнет, сбой запиши в `collect_log.json`.
Порядок и поля — `references/mcp-read-tools.md`; выполни строки 1–6 его таблицы, включая сегменты,
списки аудиторий и пиксели (без пикселей проверка пикселя пропускается). Сегменты — с
`fields=id,name,pass_condition,flags,relations,relations_count,created,updated`: по связям (`relations`) скрипты
определяют слой (пиксель, база — тёплый, ключевые фразы — холодный); сервер отверг `fields` — повтори без них. На пути A: кампании, группы и статистика по дням
(`vk_ads_statistics_day`, `entity=campaigns`, пачки ≤ 50 id, все группы кроме удалённых — архивные тоже, их расход
входит в итоги); объявления (`vk_ads_banners_list`; для архивных групп не вызывай) и их статистика по дням
(`entity=banners`) — только у 5 групп с наибольшим расходом; у дней `metrics="base"`. **Итоги периода считаются суммой дней:
`vk_ads_statistics_summary` — только за всё время, даты не передавай (с датами MCP откажет), `metrics="base,uniques"`.**
Строка 7 (сводка групп) необязательна: она даёт охват и
частоту только группам, созданным внутри периода; без неё частота «не определена», выгорание молчит, отчёт честно скажет.
**Большой ответ (Claude Desktop сохраняет его файлом, например список из десятков групп ≈ 260 КБ) руками не вставляй и
не пересказывай:** `python -m scripts.raw_store import --workspace <ws> --tool <инструмент> --arguments '<json аргументов
вызова>' --from <путь к файлу>` (в PowerShell удобнее `--arguments-file <файл с json>`). Команда сама проверит JSON и
отказывает по-русски на обрезанном или нетекстовом файле — тогда повтори вызов с меньшей выборкой (`limit`, `offset`).
Любой неудавшийся вызов инструмента запиши в `<ws>/collect_log.json` в том же виде, что пишет сбор:
`{"mode": "deep"|"quick", "date_from": "D", "date_to": "D", "calls": [{"tool": "...", "arguments": {...},
"ok": false, "error": "..."}], "errors": N, "critical": false}` (`critical: true`, если не получен
`vk_ads_campaigns_list`). `vk_ads_users_lists_list` с `code: zero_quota` (MCP 0.12.0 — HTTP 403) или 429 с `limits` с нулём — это не перегрузка, а нет прав:
повторять не надо, запиши вызов с `"no_access": true` — отчёт скажет «нет доступа к базам клиентов». Отчёт сам вынесет эти сбои в «Ограничения» — молча пропущенный вызов хуже записанного. Сбой, после которого тот же
вызов (тот же инструмент и те же аргументы) прошёл и лежит в `raw/`, отчёт сам не покажет — запись о нём не удаляй.
После — `python -m scripts.raw_store check --workspace <ws>` (код 3 — исправь названные файлы и повтори) до шага 3.

## Шаг 3. Нормализация

`python -m scripts.normalize --workspace <ws> --date-from D --date-to D [--target-cpa N] --path A|B`

Код 3 — **остановись**, `dataset.json` не записан. Причины и что делать:

- Нет живых групп, а статистика по архивным не получена (`no_stats`): есть ли расход, неизвестно — покажи причину из
  `collect_log.json` и повтори сбор статистики в новой рабочей папке; «расхода нет» пользователю не говори.

- Проверка здравого смысла не пройдена: покажи пользователю строки из `sanity.json` и скажи, что отчёт на таких
  числах строить нельзя. `ctr_units` значит, что формат ответа VK изменился (`ctr` у VK уже в процентах), — это
  повод для задачи разработчикам. Расхождение сводки и дней аудит больше не блокирует: итоги берутся из дней.
- «raw/ не разобран» — файлы нарушают формат; запусти `raw_store check` и исправь.
- «✗ metrika.json: …» — см. шаг 4.

Код 5 — **остановись**, `dataset.json` не записан: в кабинете нет живых групп (все удалены или в архиве) и расхода по
ним за период нет. Отчёт не строй, diagnose не запускай. Скажи пользователю одной фразой: «В кабинете сейчас нет живых
групп — все удалены или в архиве, и за период по ним нет расхода, проверять нечего» — и предложи другой кабинет (если их
несколько) или вернуться, когда группы заработают. Живые группы есть, а их расход за период 0 ₽ — нормализация проходит
и предупреждает: отчёт строится с крупной плашкой вверху (проверены только настройки). Текст плашки — как в
`references/report-template.md`: «Расход кабинета за период 0 ₽» (только если предполётка подтвердила 0 ₽),
«Живые группы за период не откручивали; X ₽ пришлось на удалённые группы», «Расход кабинета за период X ₽, у живых групп 0 ₽ —
разложить разницу по группам не удалось» или «Расход живых групп за период 0 ₽» (расход кабинета не проверялся).
Перескажи пользователю текст плашки и предложи другой период.

## Шаг 4. Метрика (если подключена)

По `references/metrika-vk.md` собери `<ws>/metrika.json` и обязательно запиши в него `date_from` и `date_to`
(период аудита). Затем повтори Шаг 3 — нормализация подхватит файл. Проверка строгая: при строке
«✗ metrika.json: …» исправь файл по сообщению и снова запусти normalize. Не получается — удали
`metrika.json` и иди без Метрики, это уйдёт в ограничения.

## Шаг 5. Диагностика

`python -m scripts.diagnose --workspace <ws>` → `findings.json`: находки (`findings`), чек-лист блоков A–G с баллами
(`checklist`) и вопросы к клиенту (`questions`). Нет `dataset.json` — код 2, вернись к шагу 3.
Правила, статусы и пороги — `references/diagnostic-rules.md`, `references/thresholds.json`.
Чек-лист отвечает «настроено ли» (✅ / ❌ / «—» / ❓), находки — «сколько стоит и что делать».
Статус «—» — данных нет или нечего проверять (нет активных групп или объявлений — «нечего проверять», не «нет данных»); ❓ — воронка подписки, лид-формы или Senler не используется и её
сначала уточняем у клиента (не ошибка). В балл они не входят.

## Шаг 6. Гейт

В чат 5–10 строк: общий балл («n / m»; нет живых групп — `total` пуст, вместо балла «кабинет не откручивает»), баллы блоков A–G, топ находок (уровень, объект, ₽, действие) из
`findings.json`. Затем вопросы к клиенту: те, что в `questions` помечены `important` («важно для вашего кабинета»),
задай клиенту сразу, по одному (список — `references/client-questions.md`); остальные покажет отчёт.
Ответы на `funnel_subscription` / `funnel_leadform` / `funnel_senler` запиши в `<ws>/client_answers.json`:
`{"funnel_leadform": {"verdict": "na" | "potential", "answer": "<слова клиента>"}}` (`na` — воронка клиенту не
подходит, `potential` — подходит, но не используется; критерии — `references/client-questions.md`; ответ
неясен — не записывай). Затем снова `python -m scripts.diagnose --workspace <ws>` — чек-лист и вопросы пересоберутся
(`na` / 🟢 вместо ❓, при `potential` — находка «Потенциал роста»); ✅ и ❌ ответ не меняет.
Повторный запуск перезаписывает `findings.json`, поэтому `client_note` впиши после него. Ответ клиента, объясняющий конкретную находку, впиши в неё полем `"client_note": "<текст клиента>"`, числа не правь;
отчёт покажет её с пометкой «Объяснено клиентом». Общий ответ — в сводку. И один вопрос: «Есть контекст, который
меняет вывод? Например, группа тестовая, сезон, акция». Затем шаг 7.

## Шаг 7. Отчёт

`python -m scripts.render_report --workspace <ws> --slug <slug>` → `<ws>/АУДИТ_<slug>.html`: чек-лист с баллами,
находки, вопросы к клиенту, ограничения (в том числе «Не проверено «…»: …»).
Покажи файл способом, который есть в среде, и дай сводку 5–10 строк; есть предупреждение «Кабинет менялся после
конца периода» — скажи, что статусы и бюджеты в отчёте на дату сбора. Структура отчёта —
`references/report-template.md`. Предложи передать действия в vk-ads-manager.

---

# Быстрый анализ

1. Создай новую рабочую папку (каждый прогон — новая). Охват: кабинет, день (по умолчанию вчера; сегодняшний и будущие дни скрипт отвергнет), целевой CPA если известен.
2. Предполётка как в Шаге 1, без Метрики.
3. Путь B: `python -m scripts.collect --workspace <ws> --account-id <ID> --mode quick --date-from <день−7> --date-to <день>`
   (коды выхода те же, что в Шаге 2);
   путь A: `vk_ads_ad_plans_list`, `vk_ads_campaigns_list` (поля из `references/mcp-read-tools.md`) и `vk_ads_statistics_day` по живым группам
   за те же 8 дней → `raw/`, затем `raw_store check`.
4. `python -m scripts.normalize --workspace <ws> --date-from <день−7> --date-to <день> --path A|B` (код 5 — живых групп
   нет, расхода нет: скажи пользователю, быстрый анализ не делай)
5. `python -m scripts.quick --workspace <ws> --day <день> [--target-cpa N]` — выведи его строки как есть.
   Флаги ставятся только активным группам (паузные входят в итоги). Нет данных за день — скрипт выведет заголовок
   и «нет данных»: передай это пользователю, не домысливай. Код 2 — неверный день или нет `dataset.json`.
6. Есть аномалии — предложи глубокий аудит; сам не запускай.

---

# Ограничения

Всегда входят в отчёт — `references/limitations.md`. Плюс недобранное в прогоне: путь A, нет Метрики,
не собраны объявления, статистика или пиксели, ошибки и обрыв сбора. Молча упрощённый результат хуже
честно недобранного.

# Стиль

- Один вопрос за раз. Артефакт — в файл, в чат — сводка 5–10 строк.
- Новая просьба важнее плана: сообщение посреди аудита — сначала ответ на него, а не следующий
  шаг. Просьба изменить кабинет — прямой отказ (в начале файла) и стоп.
- Не выдумывай причин: «не знаю, данных нет» лучше догадки. Гипотеза — помечай как гипотезу.
- Действие находки — что сделать, а не как в интерфейсе: шаги кабинета, названия пунктов и периоды не
  придумывай. Ориентир из методики (например, бюджет «2 × CPA») подавай как ориентир, с оговоркой из
  `action`, а не как требование VK; ограничение бюджета, названное пользователем, важнее ориентира.
- Деньги — в рублях, CTR — в процентах; сырые значения API не показывай.

# Возобновление

Только по просьбе продолжить; сообщение с другой просьбой — сначала ответ на неё.

«Продолжаем аудит VK» → найди последнюю `vk-audits/*/_state.json`, по наличию файлов
(`raw/`, `dataset.json`, `findings.json`, `АУДИТ_*.html`) продолжи с первого незавершённого шага.
Если `raw/` уже заполнен, заново не собирай: продолжай с нормализации.

