Полная документация ниже — автоматически из репозитория ai-hub-open/vk-ads-manager (ветка main). Оригинальные материалы проекта распространяются на условиях его лицензии.

vk-ads-manager

Скилл для ИИ-агента, который собирает рекламную кампанию в VK Рекламе и заводит её в кабинет ads.vk.ru: изучает конкурентов, проектирует аудитории, считает прогноз бюджета, пишет объявления, привязывает креативы и создаёт структуру кампании через API.

Скилл — папка с инструкциями и скриптами, по которым агент выполняет работу таргетолога. Маршрут шагов лежит в SKILL.md, методики по разделам VK Рекламы — в references/, расчёты и генераторы — в scripts/. Агент читает их сам, отдельного приложения у скилла нет.

Версия 0.7.6, лицензия Apache-2.0. Диалог, документы и справочники — на русском языке. Числа в этом файле сверены с кодом этой версии.

Кампания, группы объявлений и объявления создаются на паузе. Переводить объекты в активный статус агенту запрещено: показы включает маркетолог в кабинете, и до этого бюджет не расходуется.

Скилл работает только с кабинетом VK Реклама (ads.vk.ru). Старый кабинет ВКонтакте и myTarget закрыты для создания кампаний с января 2026 года и не поддерживаются.

Что делает

Маршрут подготовки кампании — от брифа до структуры в кабинете. Каждый шаг оставляет файл в рабочей папке vk-campaign-<slug>/, следующий шаг читает его.

1. Бриф. Продукт, цена, тип спроса, целевой CPL и его предел, бюджет, срок теста, цель кампании, состояние пикселя. Отдельно — материалы бренда: логотип, цвета, изображения продукта, скриншоты, готовые ролики.
2. Конкуренты. Прямые и непрямые конкуренты, заменители и сценарий «ничего не делать»; затем разбор офферов, цен, подачи, сообществ и рекламных форматов. Список кандидатов подтверждается до глубокого разбора.
3. Позиционирование и УТП — отдельное сообщение для каждого сегмента.
4. Портреты покупателей и матрица аудиторий. Матрица строится по двум осям: теплота (горячие — те, кто уже взаимодействовал; тёплые — похожие аудитории и тематические интересы; холодные — соцдем и широкие интересы) и портрет покупателя. Заполняются не все клетки: в работу идут 4–6 ячеек с самой сильной гипотезой, одна ячейка — одна группа объявлений.
5. Пиксель и события. Если счётчика нет, скилл выдаёт код пикселя и перечень событий под цель кампании — page_view, lead, purchase, add_to_cart, registration.
6. Посадочная страница и прогноз бюджета. Три сценария: минимальный, целевой и расширенный. Сценарии отличаются не коэффициентом «на глаз», а тем, какую границу каждой метрики берёт расчёт: минимальный считает по высокому CPM и низким CTR и конверсии, расширенный — наоборот.
7. Объявления и креативы. Тексты под форматы VK Рекламы с проверкой ограничений и модерации, по 3–5 вариантов на ключевую связку «гипотеза → аудитория → посадочная страница».
8. Создание кампании в кабинете и итоговый отчёт-стратегия.

Быстрый запуск. На просьбу «запусти быстро», «без стратегии», «минимальная кампания» скилл идёт коротким путём (references/quick-launch.md): бриф из пяти вопросов, три сегмента, креативы, залив на паузе. Конкуренты, портреты и прогноз пропускаются, и в журнале запуска перечислено, что пропущено и чем это грозит. Согласование сегментов и текстов, проверка юридической чистоты, данные для ОРД и запрет активации остаются. Это не мастер «Быстрый запуск» в самом кабинете VK — там аудиторию и текст подбирает VK, и через API такая кампания не создаётся.

Связка «гипотеза → аудитория → воронка → посадочная → креатив» держится в одном файле creatives.json, поэтому таблица объявлений, отчёт и структура в кабинете не расходятся между собой.

Сессия прерывается без потери работы: состояние лежит в _state.json и журналах рабочей папки, по фразе «продолжаем по VK» агент поднимает его и идёт дальше, а не начинает заново.

Таргетинги

В матрицу попадают только те типы таргетинга, которые настраиваются в кабинете: интересы, ключевые фразы, ремаркетинг, похожие аудитории, свои списки контактов. Ключевые фразы в VK Рекламе — один тип таргетинга, а не собранное поисковое ядро: потолок 15–40 точных фраз на горячий сегмент. Минус-слов в VK Рекламе нет, сужение идёт исключениями интересов и сообществ.

Технические пороги площадки, которые скилл проверяет до сборки: похожая аудитория — от 1000 совпавших пользователей в источнике, загрузка базы контактов — от 1000 записей после сопоставления.

Работа с активной кампанией

Кроме подготовки, в references/lifecycle-runbook.md описаны 13 сценариев повседневной работы: сводка по кабинету и ежедневная проверка, изменение бюджета, пауза и запуск, похожие аудитории, загрузка базы контактов, замена креатива, сужение аудитории, недельная оптимизация, смена стратегии ставок, предзапусковый чек-лист, корректировки по соцдему, копирование кампании.

Перед изменением агент показывает план и ждёт подтверждения, после изменения перечитывает объект и пишет операцию в журнал. Сущности не удаляются — только ставятся на паузу. Статус кампании агент меняет исключительно по явной команде маркетолога, по своей инициативе — никогда.

Точки контроля

Места маршрута, где агент останавливается и ждёт решения маркетолога: бриф, список конкурентов, позиционирование, матрица аудиторий, прогноз бюджета, пиксель и события, ревью изображений и видео, тексты объявлений, создание структуры в кабинете. Сквозного прогона без человека нет.

Установка

Claude Code — плагином, с обновлениями

В сессии Claude Code:

/plugin marketplace add ai-hub-open/claude-plugins
/plugin install vk-ads-manager@ai-hub-open

Скилл вызывается как /vk-ads-manager:vk-ads-manager или просьбой своими словами («запусти таргет в VK»).

Затем включите автообновление: /plugin → Marketplaces → ai-hub-open → Enable auto-update.
С ним новые версии приходят сами при старте сессии. Без него — командой
/plugin marketplace update ai-hub-open.

Python-зависимости плагин сам не ставит — один раз выполните python install.py в папке плагина
(путь покажет /plugin → vk-ads-manager). Ключи хранятся в ~/.vk-ads-manager/, вне папки плагина, —
обновление их не трогает. Если раньше скилл лежал папкой в ~/.claude/skills/, удалите её, иначе
скилл будет загружаться дважды.

Вручную — папкой или архивом

Скачайте репозиторий, откройте его папку и запустите:

python install.py

Скрипт проверяет версию Python, ставит зависимости из requirements.txt, создаёт каталог ~/.vk-ads-manager/ для ключей и делает быстрый smoke-тест импортов. Запускать повторно безопасно.

Второй способ — готовый файл скилла: dist/vk-ads-manager.skill загружается в среду, которая умеет ставить скиллы, либо распаковывается вручную (внутри обычный ZIP). Собрать такой файл из исходников можно командой ./package.sh или python -m scripts.package_skill — рабочие папки, кэши и .git в него не попадают.

Подключение MCP

MCP — подключение агента к API рекламной системы. Через него агент читает кабинет и создаёт в нём объекты.

Скилл рассчитан на хостовый сервер https://vkads-mcp.aihub.click.ru/mcp — 46 инструментов VK Ads API с именами вида vk_ads_*: кампании, группы, объявления, аудитории, пиксели, контент, статистика, справочники. Ставить и клонировать ничего не нужно, установщик только дописывает адрес и заголовки в конфиг агентной среды:

python -m scripts.setup_vk_ads_mcp --token <CLICK_RU_TOKEN> --vk-account-id <ID> --target all

Цели записи: cursor, cursor-project, claude-code, claude-desktop, all. Полезные флаги — --dry-run (показать, что будет записано), --remove (снять записи), --click-ru-user-id (мастер-аккаунт). Существующие серверы в конфиге сохраняются, перед записью делается резервная копия. Полная инструкция, включая ручную правку конфигов, — в docs/hosted-mcp-setup.md.

Вместе с vk-ads установщик подключает хранилище картинок keepimage и сохраняет токен в реестр ключей, чтобы заливка креативов работала сразу; --no-keepimage это отключает.

Два способа дать доступ к кабинету.

• Через click.ru. Один API-токен из профиля click.ru/userinfo.html, поле «API Token». Аккаунт VK Рекламы должен быть подключён в click.ru; в заголовки идут токен и идентификатор аккаунта. Заявка на API VK Рекламы и собственное OAuth-приложение при этом не нужны.
• По прямым доступам VK Рекламы, если кабинет заведён не через click.ru. Сервер принимает готовый токен доступа либо пару client_id и client_secret приложения из кабинета (Настройки → API). Разница практическая: готовый токен живёт сутки и после этого требует обновления, а по ключам приложения агент получает и продлевает токен сам — для постоянной работы нужны они. У VK Рекламы ограничение в 5 активных токенов на пару «приложение × пользователь», частота запросов — 5 в секунду.

Доступ выдаёте и отзываете вы: токен снимается в том же профиле, откуда выдан, а --remove убирает сервер из конфига среды. Ключи хранятся в ~/.vk-ads-manager/credentials.json (на Unix права 600) — отдельно от папки скилла и от рабочих файлов кампании, в файлы кампании они не попадают. Вводить их лучше скрытым вводом, чтобы значение не осталось в истории команд:

python -m scripts.manage_credentials set vk_ads     # ключ VK Рекламы
python -m scripts.manage_credentials set openai     # генерация изображений
python -m scripts.manage_credentials list           # что уже сохранено
python -m scripts.manage_credentials delete openai  # удалить

Терминология API

API наследует имена myTarget, и в новом кабинете они означают другое:

Отсюда два следствия, из-за которых скилл создаёт структуру одним вызовом. Группа без ad_plan_id создаётся, но в новом кабинете не видна. Объявления передаются внутри группы при её создании — отдельного метода «добавить объявление в существующую группу» в API нет, и пустая группа останется пустой навсегда: её придётся удалить и пересоздать.

Запуск

После установки напишите агенту, что нужно сделать, — например:

Собери кампанию в VK Рекламе для <продукт>, сайт <адрес>. Бюджет теста <сумма>, цель <заявки / трафик>.

Агент задаст бриф одним блоком, разберёт нишу и поведёт по шагам, останавливаясь в точках контроля.

Креативы

Свои картинки маркетолога имеют приоритет над генерацией: агент спрашивает о них до того, как что-то рисовать. Дальше развилка по тому, где лежит файл.

• Картинки файлами. Кладутся в assets/images/ под именами креативов. При заливе через MCP они выкладываются во временное хранилище скриптом upload_creatives_to_storage.py — ссылка живёт не больше двух часов и нужна только на момент вызова, VK скачивает картинку в свой контент. Хостовый сервер локальные пути не читает, поэтому шаг обязателен; токен click.ru для него агент спрашивает в начале работы, а не на заливе. Без токена картинки идут через REST-клиент, ручную загрузку или прямыми ссылками — передавать картинку текстом (base64) в вызове агент не пытается.
• Размер квадрата. Квадратная картинка в объявлении — ровно 600×600: VK отклоняет 1080×1080 в этой роли. Исходник можно держать 1080, скрипты загрузки ужимают копию до 600 сами; 16:9 и 4:5 не трогают. Логотип 256×256 нужен в каждом объявлении.
• Картинки публичными ссылками. Идут в кабинет напрямую. Перед загрузкой каждая ссылка проверяется HEAD-запросом: если вернулся text/html, это страница просмотрщика облачного диска, а не файл, и агент запросит замену вместо битой загрузки.
• Видео. Хранилище принимает только изображения (PNG, JPEG, GIF, WebP). Видеокреатив заливается публичной ссылкой либо локальным файлом через REST-клиент скилла.
• Генерация. Источник картинок агент выбирает по тому, какие инструменты есть в среде. Есть инструмент create_ad_image (так на платформе AI Hub) — рисует им: по картинке за вызов, сразу в размере роли VK, без текста на изображении, ключ не нужен. Инструмента нет — изображения собираются скриптом через OpenAI Images API (gpt-image-1 или dall-e-3); это внешний сервис, нужен ключ и оплата на его стороне. Видео — через Replicate, Runway, Kling или Veo. Нет ни инструмента, ни ключа — модуль пропускается целиком, а вместо картинок агент собирает техническое задание дизайнеру и говорит прямо, что без визуала кампанию не залить. Если create_ad_image дважды вернул ошибку, агент называет её причину и предлагает только варианты про картинки: позже, свои файлы или ТЗ дизайнеру.
• Загрузка с платформы. Где инструмент загрузки принимает путь к файлу рабочей папки (платформа AI Hub), картинка уходит в кабинет по пути, без временного хранилища и токена click.ru.

Как объекты попадают в кабинет

Три пути, агент берёт первый доступный в среде:

На третьем пути скилл собирает LAUNCH_GUIDE.md — пошаговую инструкцию с точными значениями из файлов кампании, по которой структуру заводят руками.

Перед заливом агент спрашивает, заполнены ли в кабинете данные рекламодателя для ОРД: без них VK отклоняет объявления (ord_data_required). После создания агент проверяет каждую группу по списку её объявлений: пустой список означает, что креативы не залились, и такой результат не выдаётся за успешный. Поле объявлений в карточке группы на паузе всегда пустое, поэтому по нему не судят.

Без пикселя с целью агент берёт пакет с оплатой за клики: оптимизация на конверсии требует цели пикселя.

Что на выходе

• Структура в кабинете — кампания, группы объявлений и объявления со ссылкой на кампанию в интерфейсе.
• Матрица аудиторий — сегменты по теплоте и портретам с типом таргетинга, размером и источником данных для каждой ячейки.
• Прогноз бюджета — три сценария с воронкой «бюджет → показы → клики → заявки → лиды» и пометкой источника у каждой метрики: api (цифра из кабинета), client (от клиента), benchmark или assumption. Лиды и CPL уходят в стратегию только с источником api или client; всё остальное помечено как несогласованное.
• Таблица объявлений ads.xlsx с проверкой ограничений площадки.
• Отчёт-стратегия strategy_report.md (и .docx) — резюме и УТП, карта воронок, посадочные, структура кампаний, прогноз, список запросов клиенту. Плюс самодостаточные файлы по блокам, каждый можно отдать отдельно.
• Чек-лист перед запуском — пиксель, события, ссылки, тексты, маркировка, бюджет.
• Раздел «Пропущено из-за среды» в журнале запуска и в отчёте: где агент пошёл обходным путём, что именно недобрано и как это добрать руками. Если пропусков не было, так и написано.

Данные помечаются, а не додумываются: таргетинги берутся из тех, что реально настраиваются в кабинете, у каждой цифры прогноза виден источник, неподтверждённое помечается как непроверенное.

Требования

• Агентная среда — программа, в которой работает агент. Обязательный минимум от неё: чтение и запись файлов в рабочей папке и диалог с подтверждениями. Без диалога не работают точки контроля.
• Выполнение Python-скриптов — ими собираются прогноз, таблица объявлений, отчёт, креативы и заливка. Формально скилл доходит до конца и без них, но тогда расчёт и документы ложатся на человека, а проверка ограничений текстов теряется.
• Python 3.9 или новее — эту границу проверяет install.py.
• Доступ к кабинету VK Рекламы — токен click.ru либо прямые доступы VK Рекламы (см. «Подключение MCP»).
• Креативы — готовые изображения и видео либо ключи внешних сервисов генерации.
• Реквизиты рекламодателя для маркировки — юридические данные вносит человек в кабинете.
• FFmpeg — только для склейки видеосегментов.

Необязательные способности среды — поиск в интернете, чтение веб-страниц по ссылке, показ файлов — расширяют разбор конкурентов и посадочных. Что теряется без каждой из них, перечислено в SKILL.md, раздел «Что нужно от среды».

Ограничения

Чего скилл не делает:

• не создаёт лид-формы: API умеет создать только объявление-обёртку со ссылкой на готовую форму, саму форму собирают в кабинете руками;
• не создаёт и не устанавливает пиксель. Пиксель заводит человек в кабинете (Сайты → Добавить пиксель): VK требует для этого пароль от счётчика Top@Mail.ru, а пароли агент в чате не спрашивает. Агент выдаёт код и список событий и берёт id готового пикселя через API; код на сайт ставит человек, и он же подтверждает, что события засчитываются;
• не рисует креативы без внешнего сервиса генерации;
• не оформляет маркировку: реквизиты, договоры и акты заполняются в кабинете, API их только читает;
• не удаляет сущности при ведении кампании — ставит на паузу;
• не заменяет таргетолога: аудитории, прогноз и тексты объявлений остаются решением маркетолога.

Границы площадки и клиента:

• REST-клиент при первой загрузке не создаёт похожие аудитории (нужен источник, которого у новой кампании ещё нет) и не загружает базу контактов; его форма объявления (роли текста и картинки) сверена через MCP, но сам путь через REST вживую не проверен, видео и карусель в нём не проверены;
• у кампании (ad_plan) нет метода смены статуса: пауза и запуск верхнего уровня идут обновлением объекта, у группы метод есть;
• прохождение модерации и присвоение ERID зависят от площадки и ОРД, ожидание доходит до 10 дней;
• реальные скриншоты интерфейса продукта и ролики с людьми предоставляет клиент — сгенерированные для этого не годятся;
• лимиты площадки, под которые собирается структура: до 100 групп в кампании, до 30 объявлений в группе, до 10 000 аудиторий в кабинете, общий лимит 300 объявлений и не более 200 в сутки;
• лимиты текстов, которые проверяет таблица объявлений: заголовок до 25 знаков для сайта и до 40 для сообщества, приложения и лид-формы; текст рядом с кнопкой до 30 знаков; поле «О компании» до 115 знаков.

Состав репозитория

vk-ads-manager/
├── SKILL.md            маршрут шагов и правила работы агента
├── README.md
├── CHANGELOG.md
├── LICENSE
├── requirements.txt
├── install.py
├── references/         методики: конкуренты, аудитории, объявления, прогноз,
│                       спецификации форматов, модерация, ОРД, лид-формы,
│                       каталоги, приложения, API, MCP, lifecycle
├── scripts/            прогноз, генераторы документов и медиа, заливка,
│                       установщик MCP, реестр ключей, упаковка
├── docs/               подключение хостового MCP, отчёты о проверках
├── tests/              тесты разработчика (в .skill не попадают)
├── pytest.ini
├── requirements-dev.txt
├── package.sh
└── package.bat

Рабочие папки кампаний создаются вне папки скилла и в репозиторий не попадают.

Тесты

pip install -r requirements-dev.txt
python -m pytest

Сеть в тестах закрыта (tests/conftest.py запрещает socket.connect), HOME
подменяется на временную папку — реальные ключи из ~/.vk-ads-manager и живой
кабинет не задеваются. Залив проверяется только в dry_run.

Покрыто: настройка консоли и её подключение во всех точках входа, установщик MCP
(все четыре способа авторизации), заливка картинок в KeepImage, упаковщик .skill,
инварианты залива (всё создаётся в blocked, группа всегда с ad_plan_id, бюджеты
в рублях и защита от больших сумм), форма объявления по ролям и лимиты текстов, регистрация
ссылок, ошибка ОРД, ужатие квадрата до 600×600 и гейт прогноза. Прогон — меньше секунды.

Лицензия и участие

Лицензия Apache-2.0, текст — в LICENSE. Журнал изменений — в CHANGELOG.md; до версии 1.0 состав шагов и материалов может меняться.

Нашли ошибку в маршруте, устаревший факт о площадке или расхождение документации с поведением — откройте Issue с описанием шага, ожидаемого и фактического результата. Правки принимаются запросами на слияние в ветку dev. Секреты в Issues, запросах и файлах кампаний не публикуются: в репозитории только плейсхолдеры.