Полный lifecycle для VK Рекламы (ads.vk.ru) — от стратегии и медиаплана до запуска через API и работы с активной кампанией. Включает воронку подготовки (бриф → конкуренты по 4 кругам с заменителями «снизу» → персоны → аудитории → семантика → УТП по сегментам → прогноз с гейтом маркетолога → структура → креативы → залив) и lifecycle (мониторинг, бюджет, пауза, lookalike, оптимизация). Используй когда пользователь хочет запустить таргет в VK Рекламе / VK Ads / ВКонтакте, собрать медиаплан или с...
Scanned 9/5/2026
Install to Claude Code
Skills Directorynpx -y skills add ai-hub-open/vk-ads-manager --agent claude-codeInstalls into .claude/skills of the current project.
Are you the author of vk-ads-manager?
Add the live security badge to your README — it updates automatically with every re-scan.
[](https://www.skillsdirectory.com/skills/ai-hub-open-vk-ads-manager)More formats (shields.io, HTML) on the badges page.
---
name: vk-ads-manager
description: Полный lifecycle для VK Рекламы (ads.vk.ru) — от стратегии и медиаплана до запуска через API и работы с активной кампанией. Включает воронку подготовки (бриф → конкуренты по 4 кругам с заменителями «снизу» → персоны → аудитории → семантика → УТП по сегментам → прогноз с гейтом маркетолога → структура → креативы → залив) и lifecycle (мониторинг, бюджет, пауза, lookalike, оптимизация). Используй когда пользователь хочет запустить таргет в VK Рекламе / VK Ads / ВКонтакте, собрать медиаплан или стратегию, проанализировать конкурентов, проработать аудитории и УТП, составить объявления, спрогнозировать охваты/лиды/CPL, собрать отчёт для агентства — а также «как у нас в VK», «отчёт по VK», «увеличь бюджет VK», «пауза VK», «запусти кампанию VK», «добавь lookalike», «оптимизация VK», «прошла неделя что доработать». Триггерится и на обобщённое «таргет», «таргетированная реклама», «реклама в соцсетях» для русскоязычных продуктов. Работает на русском языке.
---
# VK Ads Funnel — полный lifecycle
Скилл проводит как через 10-шаговую воронку подготовки кампании в VK Рекламе (ads.vk.ru), так и через повседневную работу с уже существующей кампанией. На максимуме автоматизации, который позволяет среда: сам ищет конкурентов в интернете, читает лендинги, генерит persona, проектирует структуру аудиторий и креативы. Пользователь — source of truth и редактор, не оператор. Что скилл требует от среды и что делает, когда способности нет, — в разделе «Что нужно от среды» ниже.
С января 2026 года старый кабинет ВКонтакте (vk.com/ads) и myTarget закрыты для создания новых кампаний — всё ведётся через единый кабинет VK Реклама (ads.vk.ru), который покрывает VK, OK, Дзен, Mail и проекты VK. Этот скилл — только про новый кабинет.
## ⚠️ Терминология VK Ads API (важно знать)
API использует legacy myTarget имена. В новом UI ads.vk.ru они означают **другое**:
| UI термин | API термин |
|---|---|
| **Кампания** (top-level контейнер) | `ad_plan` |
| **Группа объявлений** | `campaign` |
| **Объявление** | `banner` |
**🚨 Главный gotcha:** `campaign` (= группа объявлений) без `ad_plan_id` создаётся, но становится **orphan** — невидим в новом UI. Всегда создавать ad_plan с nested campaigns атомарно, или указывать существующий `ad_plan_id`.
В диалоге с пользователем используй UI-термины («Кампания / Группа / Объявление»). В API-вызовах и логах — `ad_plan / campaign / banner`. См. `references/vk-ads-mcp-integration.md` для полной таблицы.
## Что нужно от среды
**Обязательный минимум — две способности:**
- **Чтение и запись файлов** в рабочей папке `<outputs>/vk-campaign-<slug>/`. Каждый шаг порождает артефакт, следующий шаг его читает.
- **Диалог с пользователем** — задать вопрос, получить ответ, дождаться подтверждения. Пользователь здесь source of truth и редактор: без диалога не работают гейты (согласование списка конкурентов, прогноз, креативы).
Больше ничего обязательного нет. Всё ниже — **необязательно**: без любой из этих способностей скилл доходит до конца, но часть работы уходит человеку, а часть данных недобрана.
**Необязательные способности.** У каждой есть ветка «если нет». Идёшь по ветке — **печатаешь пометку о пропуске** в артефакт этого шага (формат ниже).
| Способность | Где нужна | Если нет |
|---|---|---|
| **Запуск кода** — Python 3.10+ и команды оболочки | Почти везде: `scripts/*` — прогноз, xlsx, картинки M1, видео M2, PDF M3, залив M4, ключи, пиксель, отчёт | Отдай команду пользователю текстом, попроси прислать вывод и работай с ним как со своим. Не может и он: прогноз Шага 9.5 считай вручную по `references/forecasting.md`; таблицу объявлений отдай Markdown-таблицей вместо xlsx; M1/M2/M3 пропускаются целиком (см. их ветки); залив идёт путём A (MCP) или ручным гайдом, который ты пишешь сам. **Теряется:** валидация лимитов и юр.чистоты из `generate_ads_xlsx`, все генераторы медиа и автоматический залив по REST. |
| **Вызов MCP-инструментов** (хостовый сервер `vk-ads`, aihub.click.ru) | Шаг 0.5 (аудит аккаунта), Шаг 9.5 (фактические CPM/CTR), Шаг 11 путь A | Путь B — наш REST через `scripts/deploy_campaign.py`; нет и запуска кода — путь C, ручной залив в кабинете. Фактические CPM/CTR из кабинета не получить: в прогнозе они остаются `benchmark`. **Теряется:** автоматический залив и живые данные аккаунта. |
| **Сетевые вызовы внешних API по ключу** — VK Ads, OpenAI, Replicate/Runway | Шаг 11 путь B, модули M1 (картинки), M2 (видео), M3 (PDF) | Залив — путь C, ручной. M1/M2 — визуал заказывается у дизайнера по ТЗ, которое ты пишешь текстом. **Теряется:** готовые креативы; Шаг 10 отдаётся с описаниями визуала вместо файлов, и это блокер запуска, а не косметика. |
| **Поиск в интернете** | Шаги 3, 4, 7 — конкуренты и их реклама | Спроси у клиента прямо: «с кем вас сравнивают, что говорят при отказе»; попроси 3–5 скриншотов рекламы конкурентов из ленты VK; возьми список из брифа. Четыре круга заполняются со слов, тег `source-trust: client`. **Теряется:** широкая корзина кандидатов и круг «заменители снизу», которых клиент сам не называет — а они часто крупнейшие по объёму. |
| **Чтение веб-страниц по URL** | Шаги 1, 2, 4, 9 — лендинг и сайты конкурентов | Спроси у пользователя 5 пунктов словами: H1, бенефиты, CTA, цена/триал, доказательная база. Чек-лист посадочной Шага 9 пройди вопросами к пользователю, а не сам. **Теряется:** сверка обещания в креативе с тем, что реально на лендинге — прямая причина слитого бюджета. |
| **Показ файлов пользователю** — превью, ссылки на файлы | Шаги 10.5–10.7, 11, 12 | Перечисли пути к файлам от корня рабочей папки и скажи, что открыть. **Теряется:** быстрый визуальный ревью креативов. |
**Дочерних агентов этот пакет не требует** — все шаги выполняются в основном контексте.
**Названия инструментов в тексте ниже — примеры.** Где встречаются `mcp__workspace__bash`, `mcp__vk-ads__*`, `WebSearch`, `WebFetch`, `computer://`-ссылки — это имена из одной конкретной среды, приведённые для наглядности. Ориентируйся на **способность**, а не на имя: если инструмент называется иначе, но делает то же — используй его.
### Пометка о пропуске
Шаг выполнен без необязательной способности — впиши в артефакт этого шага строку такого вида:
> ⚠️ **пропущено: нет `<способность или источник данных>`** — `<что сделал вместо>`. Потеряно: `<что именно недобрано>`. Как добрать: `<что сделать человеку>`.
Например:
> ⚠️ **пропущено: нет поиска в интернете** — список конкурентов собран со слов клиента, 4 кандидата вместо 10–20. Потеряно: круг «заменители снизу» (Excel, руки, ассистент). Как добрать: поискать «как вести <задачу> в Excel» и вернуться на Шаг 3.
Пометки складываются в **обязательный раздел «Пропущено из-за среды»** в `launch_log.md` и в сводный отчёт Шага 12. Пропусков не было — напиши «пропусков нет». Пользователь должен видеть, где данные недобраны, а не получать молча упрощённый результат.
## ⚠️ Как работаем: пользователь не оператор
Скилл рассчитан на **не-технического пользователя**. Правила ниже действуют, **когда нужные способности из таблицы есть**:
- ✅ **Скрипты запускаешь сам** инструментом запуска кода (например, `mcp__workspace__bash`). Пользователь не открывает терминал.
- ✅ **Результаты собираешь сам** и показываешь превью или итоги в чате.
- ✅ **Ключи API пользователь скидывает в чат** — сохраняй через `manage_credentials.py set <service> --key <KEY>`. Способ Б — дефолт для коллег. Способ А (`getpass` в терминале) — только если пользователь явно скажет «я сам».
- ✅ **Каждый Шаг 1-10 + lifecycle** выполняешь сам, не передаёшь пользователю команды для копи-паста.
- ❌ **Не передавай пользователю команды для терминала**, если можешь выполнить сам. Исключение — в среде нет запуска кода: тогда команду отдаёшь с пояснением, зачем она нужна, и просишь прислать вывод.
**Onboarding нового пользователя (первая встреча):**
1. Проверь установлены ли зависимости — выполни:
```
python -c "import openai, PIL, requests, openpyxl, docx" 2>&1
```
Если ошибка — попроси пользователя один раз запустить `python <skill-path>/install.py` (это идемпотентно, безопасно). **Запуска кода в среде нет** — пропусти проверку: библиотеки нужны только скриптам, а те шаги всё равно пойдут по своим ветками «если нет».
2. Проверь сохранены ли ключи — выполни:
```
python -m scripts.manage_credentials list
```
Если каких-то нужных нет — попросишь когда дойдёшь до шага где они нужны (не заранее всех сразу). **Запуска кода нет** — хранилища ключей нет: спрашивай ключ в тот момент, когда он нужен, и не сохраняй его.
3. **Проверь, есть ли у тебя инструменты MCP-сервера `vk-ads`** (в одной среде они видны как `mcp__vk-ads__*`, в другой имена выглядят иначе — смотри по короткому имени, например `vk_ads_auth_check`). Есть — это primary путь для финального залива (Шаг 11), скажи об этом пользователю. Нет — предложи подключение к **хостовому** серверу через `scripts/setup_vk_ads_mcp.py` (нужны только токен click.ru и ID аккаунта; клонировать репозиторий и ставить Bun не надо). Не блокирующее: без MCP скилл работает через наш REST, а без него — ручным заливом.
4. Спроси что хочет запустить и иди по 10-шаговой воронке.
## Когда триггерится
**Подготовка (10-шаговая воронка):**
- «Запусти таргет в VK» / «нужна VK Реклама» / «сделай РК во ВКонтакте»
- «Подготовь медиаплан под VK Ads»
- «Собери аудитории для VK» / «спроектируй lookalike»
- «Загрузи базу клиентов в VK» / «настрой CRM-аудиторию»
- Любой запрос на запуск таргета в соцсетях для русскоязычного продукта без явного указания канала
**Lifecycle (мониторинг + изменения через API):**
- «Как у нас VK?» / «Что в VK Рекламе?» / «Отчёт по кампании»
- «Daily check» / «Сводка по VK за вчера»
- «Увеличь / сократи бюджет VK»
- «Пауза кампании» / «Запусти снова»
- «Активируй кампанию» / «Включи»
- «Добавь lookalike» / «Сделай похожих»
- «Загрузи новую базу» / «Обнови CRM-аудиторию»
- «Измени текст объявления» / «Поправь заголовок»
- «Добавь интересы» / «Сузь по соцдему»
- «Скопируй кампанию»
- «Оптимизация по VK» / «Прошла неделя что доработать»
Lifecycle-сценарии — **`references/lifecycle-runbook.md`**.
## Главный принцип
**Каждый шаг порождает артефакт.** Рабочая папка: `<outputs>/vk-campaign-<slug>/`. Артефакты пронумерованы (`01_brief.md` ... `10_creatives.md`), плюс `_state.json`, `_account_audit.md` (если есть доступ к API), `_audiences.md`, `_semantics.md`, `_usp.md`, `_forecast.md`, `operations_log.md` (для lifecycle), финальные `ads.xlsx`, `audiences.json`, `creatives.json`.
**Промежуточные артефакты самодостаточны** — каждый можно отдать/показать отдельно: анализ конкурентов (`_competitors.md`), семантика (`_semantics.md`), УТП по сегментам (`_usp.md`), посадочные (`_landings.md`), стратегия (`_strategy.md`), структура кампаний (`_campaign_structure.md`). Финальный Шаг 12 (`scripts/generate_strategy_report.py`) собирает их в `report/` + сводный отчёт для команды агентства.
## Как использовать references
- `references/vk-ads-specs.md` — **обязательно** перед Шагом 10. Лимиты символов по форматам, требования к креативам, дисклеймеры модерации.
- `references/targeting-strategy.md` — **обязательно** перед Шагом 6.5. Методология подбора аудиторий: соцдем + интересы + поведение, кастомные на собственных данных, баланс «алгоритмическое vs ручное» для алгоритмов VK 2026.
- `references/audiences-and-lookalike.md` — **обязательно** перед Шагом 7. Пиксель VK Ads, события, CRM-загрузки (phone/email), lookalike (мин. 1000), стратегии комбинирования.
- `references/competitor-research.md` — шаги 3-4, 7. Четыре круга конкурентов (прямые / непрямые / заменители «снизу» / ничего не делать), расширенный сбор, **гейт согласования списка человеком**, иерархия источников.
- `references/buyer-personas.md` — шаг 6. Структура персон, специфика VK (поведенческая и сообществовая активность).
- `references/ad-copywriting.md` — шаги 5 и 10. **УТП и боли ОТДЕЛЬНО по сегментам** (не смешивать; отдельно «конкуренты снизу»), формулы, **юр.чистота** (нет имён конкурентов в текстах, защита от сравнений «лучше чем X», закон о рекламе), анти-«ни о чём», маркировка ОРД.
- `references/forecasting.md` — **обязательно** перед Шагом 9.5. Откуда берутся охваты/клики/CTR/конверсии/лиды, теги источников (`api`/`client`/`benchmark`/`assumption`), почему лиды/CPL нельзя отдавать без проверки, reality-check, гейт согласования с маркетологом.
- `references/landing-checklist.md` — шаг 9.
- `references/vk-ads-api.md` — REST API endpoints (OAuth2, campaigns, ad_plans, banners, statistics).
- `references/lifecycle-runbook.md` — **обязательно** для всех lifecycle-сценариев. 13 готовых сценариев с проверками безопасности и логированием.
- `references/visual-generation.md` — методология генерации картинок через AI (Шаг 10.5, модуль M1).
- `references/video-generation.md` — методология генерации видео через AI (Шаг 10.6, модуль M2). Провайдер-абстракция Replicate / Runway / Kling / AiSMM / Veo + A/B variants workflow + FFmpeg склейка длинных видео.
- `references/replicate-models.md` — каталог моделей Replicate (Kling, Hunyuan, Seedance, Wan, Hailuo) с input-параметрами и стоимостью. Расширяется при появлении новых SOTA-моделей без переписывания скилла.
- `references/pdf-generation.md` — методология PDF lead magnet (Шаг 10.7, модуль M3). Workflow: Claude пишет markdown в чате → скрипт собирает PDF с обложками от M1.
- `references/credentials.md` — универсальная система API-ключей. **Обязательно перед** любым шагом, требующим API (OpenAI, VK Ads, Runway, Kling и т.д.). Объясняет как спрашивать ключ у пользователя безопасно.
- `references/vk-ads-mcp-integration.md` — **рекомендуемый путь работы с VK Ads API через хостовый MCP-сервер** vk-ads-mcp (45 инструментов, aihub.click.ru). Включает: подключение (Cursor / Claude Code / Claude Desktop), авторизацию через click.ru, список tools, маппинг наших задач на tools, правильную терминологию (`ad_plan` vs `campaign` vs `banner`). **Обязательно прочитать перед Шагом 11** — если MCP-инструменты доступны, идём по ним вместо нашего REST.
### Тематические справочники по разделам VK Рекламы (читать по потребности задачи)
Сверены построчно с официальной справкой ads.vk.com/help; у фактов проставлены слаги-источники. Каждый блок помечен [MCP] (автоматизируемо через API) или [UI] (только в кабинете).
- `references/start-and-launch.md` — процесс запуска: «Быстрый запуск vs Режим эксперта», лимиты объявлений/бюджета, статусы, операции с сущностями, «цель нельзя менять после запуска». Читать, когда вопрос про создание/статусы/лимиты.
- `references/moderation-rules.md` — **читать при написании текстов и креативов** (Шаги 5, 10): полные запрещённые/лицензируемые категории (таблица «категория → документ»), требования к тексту/визуалу, размеры дисклеймеров, 18+, конкурсы, банкротство, крипта. Расширяет краткий блок из `vk-ads-specs.md`.
- `references/ord-agency.md` — **читать для агентских кабинетов**: ОРД-онбординг клиента/договоров, обязательные ежемесячные акты (15-30 числа), сбор 3% (ФЗ-479), статусы ОРД, размеры дисклеймеров. Связан с `preflight_ord()` в API-клиенте.
- `references/lead-forms.md` — при работе с лид-формами: конструктор (типы/лимиты), интеграции CRM, уведомления (нюанс для агентств), визитка, лендинг-прогрев, сплит-тест. API создаёт только объявление-обёртку.
- `references/ecommerce-catalogs.md` — при рекламе товаров: каталоги/фиды (форматы, поля, лимиты), [MCP] события динамического ретаргетинга с `product_id`, группы товаров, макросы `{{product.*}}`, маркетплейсы (Ozon/WB/AliExpress/Яндекс.Маркет), FSA.
- `references/app-promotion.md` — при продвижении мобильных приложений: добавление/подтверждение владения, трекеры/MMP, диплинки, категории событий, «агентский кабинет не может быть владельцем приложения».
- `references/branding-formats.md` — медийные CPM-форматы «Узнаваемость и охват» (аудио, баннерная, HTML5, видео-branding до 180-300 сек, Дзен, ОК, музыка, профили/каналы, премиум, прямые сделки). Спеки тут ДРУГИЕ, не путать с перформанс из `vk-ads-specs.md`.
- `references/mini-ads.md` — [UI-fallback] упрощённый/мобильный кабинет: через MCP не заливается, знание для консультаций (свои цели/лимиты/автоподбор).
## Как использовать scripts
- `scripts/generate_strategy_report.py` — **главный итоговый отчёт для команды агентства**. Собирает `report/strategy_report.md` (+ `.docx` с `--docx`) и отдельные самодостаточные .md-артефакты по блокам (`_competitors.md`, `_semantics.md`, `_usp.md`, `_landings.md`, `_funnels.md`, `_campaign_structure.md`, `_forecast.md`, `_client_requests.md`, `_strategy.md`). Воронки, посадочные/лид-формы и структуру выводит из creatives.json — единый источник со ads.xlsx, не противоречат друг другу. Запускать в самом конце обработки (Шаг 12).
- `scripts/forecast.py` — прогноз по сценариям (минимальный/целевой/расширенный) с тегами источников и reality-check. `--init` создаёт `forecast_inputs.json` (заполнить CPM/CTR из MCP, CR от клиента) → запуск без `--init` собирает `_forecast.md` со статусом согласования. См. `references/forecasting.md`.
- `scripts/generate_media_plan.py` — артефакты → docx (или md фолбек). Технический сборник всех артефактов; для агентства используем `generate_strategy_report.py`.
- `scripts/generate_ads_xlsx.py` — creatives.json → xlsx (или CSV фолбек). Колонки связки (campaign/group/segment/hypothesis/audience_id/funnel_stage/landing). Валидация лимитов VK + юр.чистоты (сравнения, имена конкурентов из `brand.json.competitor_names`, «ни о чём»).
- `scripts/vk_ads_api.py` — REST клиент к VK Ads API (OAuth2, campaigns, banners, audiences, statistics). Для lifecycle и финального залива.
- `scripts/vk_pixel_helper.py` — генерация кода пикселя VK для встраивания на сайт + чек-лист событий.
- `scripts/generate_creative_images.py` (M1) — **генератор картинок** через OpenAI Images API. Читает creatives.json + brand.json → генерит обложки eBook, pain-split, abstract-brand композиции, карусели. См. `references/visual-generation.md`.
- `scripts/prompt_templates.py` — 7 шаблонов промптов для М1 (ebook_cover/preview/cta, pain_split, abstract_brand, carousel_card, ui_mockup).
- `scripts/brand_defaults.json` — defaults бренд-конфига для M1 (переопределяется локальным `brand.json`).
- `scripts/credentials.py` + `scripts/manage_credentials.py` — **универсальная система API-ключей**. Скрипты модулей не привязаны к env-переменным — ключ один раз сохраняется в `~/.vk-ads-manager/credentials.json` через `python -m scripts.manage_credentials set <service>`. См. `references/credentials.md`. Поддерживаемые сервисы: `openai`, `vk_ads`, `runway`, `kling`, `aismm`, `anthropic`.
- `scripts/generate_creative_videos.py` (M2) — **генератор видео** через провайдер-абстракцию (Runway / Kling / AiSMM / Veo). Читает creatives.json, для каждого видео-креатива (format/image_or_video содержат «video») генерит 5-10s MP4 в `assets/videos/`. Дефолт-провайдер `runway` (полностью реализован). Опция `--use-seed-images` использует `assets/images/<name>.png` как первый кадр (image-to-video). См. `references/video-generation.md`.
- `scripts/video_prompt_templates.py` — 3 шаблона видео-промптов (pain_reframe, ugc_testimonial, product_demo).
- `scripts/video_providers/` — провайдер-абстракция: `runway.py`, `kling.py`, `veo.py` (Google AI Studio), `aismm.py` (generic). Все 4 реализованы.
- `scripts/video_concat.py` — FFmpeg-обёртка: склейка сегментов в длинное видео, извлечение последнего кадра (для chain-segments), overlay-текст. CLI: `python -m scripts.video_concat {check,concat,last-frame,overlay-text}`.
- `scripts/video_providers/replicate.py` — **рекомендуемый дефолт для тестирования и гибкости**. Универсальный провайдер: один ключ Replicate → доступ к десяткам видео-моделей (Kling, Hunyuan, Seedance, Wan, Hailuo, Veo). Модель задаётся через `--model <slug>`. См. `references/replicate-models.md` для каталога.
- `scripts/deploy_campaign.py` (M4) — **end-to-end залив в кабинет VK Реклама**. Читает creatives.json + audiences.json + assets/images/ + assets/videos/, загружает медиа, создаёт ad_plan + campaigns + banners — всё в `status=blocked`. Никогда не активирует — это делает пользователь через UI после прохождения Сценария 10.
- `scripts/generate_lead_magnet_pdfs.py` (M3) — **генератор PDF lead magnet** для eBook-креативов. Читает markdown из `assets/pdf_content/<creative>.md` (создаёт Claude в диалоге с пользователем), собирает в PDF через ReportLab, использует обложки от M1 если есть. См. `references/pdf-generation.md`.
- `scripts/pdf_builder.py` — низкоуровневый ReportLab builder (обложка/тело markdown/CTA).
- `scripts/package_skill.py` — упаковщик скилла в `.skill` файл для распространения. Запуск: `python -m scripts.package_skill` или двойной клик `package.bat` (Windows) / `./package.sh` (Unix). Исключает `evals/`, `assets/`, рабочие папки кампаний, кэши Python.
- `scripts/generate_launch_guide.py` (M5) — **UI fallback**. Генерирует `LAUNCH_GUIDE.md` (опционально `.docx`) для ручного залива в кабинете ads.vk.ru — все шаги от настройки ОРД до активации, с точными значениями бюджета / таргетинга / текстов баннеров. Использовать когда у клиента нет API доступа.
- `scripts/setup_vk_ads_mcp.py` — **подключает хостовый vk-ads-mcp** (https://vkads-mcp.aihub.click.ru/mcp, 45 инструментов) к Cursor / Claude Code / Claude Desktop: токен click.ru + ID аккаунта, `--target`, `--dry-run`, `--remove`. Клонировать репозиторий и ставить Bun не нужно. Требует запуска кода; без него — конфиг пишет человек по `docs/hosted-mcp-setup.md`. Путь через MCP — **primary** для Шага 11 (приоритет над нашим REST). См. `references/vk-ads-mcp-integration.md`.
---
# Workflow подготовки: 10 шагов
## Шаг 0. Подготовка
1. Имя продукта (1-2 слова) для slug.
2. Создай `vk-campaign-<slug>/`, в ней `_state.json` с `"current_step": 1`.
## Шаг 0.5. Аудит API-доступа (опциональный)
Если подключён MCP `vk-ads` — аудит делается через него: `vk_ads_auth_check` → `vk_ads_account_info` → `vk_ads_ad_plans_list`. Если MCP нет, но у пользователя есть токен VK Ads API — попроси выполнить read-only вызов `GET /api/v2/campaigns.json` через `scripts/vk_ads_api.py audit`. Запиши `_account_audit.md`: всего/активных/на паузе кампаний, имена, бюджеты, цели. Пометь семантически близкие.
Покажи: «Вижу N кампаний, K похожи. Учитываем при подборе аудиторий и прогнозе CPL?»
В `_state.json`: `"api_available": true|false, "similar_campaign_ids": [...]`.
Если ни MCP, ни токена нет — пользователь работает руками в UI ads.vk.ru, скилл всё равно полезен, просто финальный залив будет через UI (см. Шаг 11).
## Шаг 1. Продуктовый бриф
Спроси одним блоком:
1. Что продаёте (в одной фразе)
2. Сайт/лендинг
3. Цена (сумма или диапазон, подписка/разовая)
4. **Тип товара** — массовый ширпотреб / премиум / B2B / локальный сервис / SaaS / инфопродукт
5. **Тип спроса** — горячий (уже ищут) / тёплый (знают о проблеме) / холодный (нужно создавать осознание). В VK работают **все три**, но стратегия аудиторий разная.
6. **Уровень бренда** — известный или новый
7. География
8. **Целевая аудитория «в одном предложении»** (для проверки на шаге 6)
9. Метрика успеха + LTV/чек
10. **Целевой CPL** — минимально приемлемый и потолок. В VK CPL зависит от категории: от 100-300 ₽ (массовка) до 2000-5000 ₽ (B2B/услуги).
11. **Бюджет на тест** — общая сумма + срок. В VK минимум для адекватного теста — 30-50 тыс ₽ на 2 недели. Меньше — алгоритм не успеет выйти из обучения (нужно 50+ событий целевого действия).
12. **Цель кампании в VK** (см. `references/targeting-strategy.md`): подписчики сообщества, охват и вовлечение, лиды (форма VK), сайт+конверсии, посещения магазина. Алгоритмы VK оптимизируют **на уровне кампании** — смешивать цели нельзя.
13. **Пиксель установлен? События настроены?** Без него — нет lookalike по посетителям, нет оптимизации на конверсии, нет ретаргета.
14. Срок запуска
Прочитай лендинг инструментом чтения веб-страниц (например, `WebFetch`). **Если такого инструмента в среде нет или страница заблокирована** — спроси 5 пунктов у юзера: H1, бенефиты, CTA, цена/триал, доказательная база. Пометь, что данные со слов, и впиши в `01_brief.md`: «пропущено: нет чтения веб-страниц — данные о продукте со слов клиента, с лендингом не сверены».
**Артефакт:** `01_brief.md`. **Гейт:** «Идём дальше?»
## Шаг 2. Сбор визуала
VK Реклама визуально-первичная — карточки в ленте, видео в клипах, креативы в universal. Сразу собери:
- Логотип в высоком разрешении
- 5-10 скриншотов главных блоков лендинга
- Фото продукта в использовании
- Брендовые цвета (HEX)
- Уже снятые видео / отзывы клиентов (если есть)
Читаем страницы сайта (например, `WebFetch`); нет такой возможности — просим ссылки напрямую у пользователя. ⚠️ **Ссылки на изображения запрашивай сразу по правилам из `references/vk-ads-specs.md` → «Требования к ссылкам на изображения от клиента»** (там же готовый шаблон запроса). Ссылка, не отвечающая правилам, не загрузится на Шаге 11 — а к тому моменту переделывать поздно. Каждую полученную ссылку прогоняй через пре-флайт (см. Шаг 11) в момент получения, а не перед заливом. **Артефакт:** `02_visual.md` со ссылками или встроенными фрагментами + явный список **чего не хватает** (визуал — частый блокер на Шаге 10). Собрано только со слов — пометь пропуск: список «чего не хватает» в этом случае неполный.
## Шаг 3. Поиск конкурентов (+ гейт согласования списка)
**Прочитай `references/competitor-research.md`.** Собираем не только прямых — а **четыре круга**, и каждый помечаем типом:
1. **Прямые / ближайшие** (`direct`) — тот же продукт, та же ЦА.
2. **Непрямые** (`indirect`) — другой продукт, та же боль.
3. **Заменители / «конкуренты снизу»** (`substitute`) — способ обойтись без покупки: Excel, руки, ассистент, «ведём в Telegram». Если продаёте CRM — конкурент снизу это **Excel-таблица**. Почти всегда существует и часто крупнейший по объёму.
4. **Ничего не делать** (`do_nothing`) — боль не осознана.
Собери широкую корзину 10-20 кандидатов поиском в интернете (например, `WebSearch`): по транзакционным запросам И по запросам про заменители «как вести Y в Excel»; `vk.com/search`; каталоги; отзовики и подборки «альтернативы X». Плюс всегда спроси клиента: «с кем вас сравнивают / что говорят при отказе».
**Если поиска в интернете в среде нет** — корзина собирается только со слов клиента и из брифа: спроси про сравнения и отказы, попроси назвать 3–5 конкурентов, а круг «заменители снизу» вытяни вопросом «а как эту задачу решают те, кто ничего не покупает?». Все кандидаты помечаются `source-trust: client`. В `03_competitors.md` — пометка: «пропущено: нет поиска в интернете — корзина собрана со слов клиента, N кандидатов вместо 10–20. Потеряно: заменители и непрямые конкуренты, которых клиент не назвал. Как добрать: поискать транзакционные запросы и «как вести <задачу> в Excel» руками». На гейте скажи это словами — пользователь должен понимать, что согласовывает неполный список.
**🚦 Гейт:** покажи таблицу-кандидатов (название · тип · почему в списке) и спроси: «Кого глубоко анализируем, кого убрать, кого добавить?» Без подтверждения списка Шаг 4 не начинаем.
**Артефакт:** `03_competitors.md` — кандидаты с типом и пометкой «согласовано / на согласовании».
## Шаг 4. Анализ конкурентов
Читаем сайты топ-5 (инструмент чтения веб-страниц, например `WebFetch`). **Нечем читать** — разбор строится на том, что знает клиент, плюс на скриншотах, которые он пришлёт; пункты, которые так не добываются (цены, Tone of Voice), помечай `n/a`, а не догадкой, и ставь пропуск в `04_competitors_deep.md`. Для каждого:
- Офер (H1)
- УТП
- Цены
- ЦА (по позиционированию)
- Tone of Voice
- CTA
- Доказательная база (отзывы, сертификаты)
- **VK-сообщество**: размер, активность, частота постов, формат контента, наличие виджетов (лид-форма, товары)
Разбери **отдельно ближайших** (direct) и **отдельно остальные релевантные** (indirect + substitute): у заменителя нет лендинга/сообщества — вместо этого опиши «чем человек пользуется сейчас», что в этом плохо (боль), что его держит. Это вход для УТП-сегмента «конкуренты снизу» (Шаг 5).
**Артефакт:** `04_competitor_analysis.md` (каждый блок с типом). Это и есть самодостаточный `_competitors.md` для отдельной выдачи — Шаг 12 скопирует его в `report/`.
## Шаг 5. Свой смысл
Покажи саммари конкурентов и не-закрытые ниши. 2-3 вопроса, 3 варианта позиционирования. **Артефакт:** `05_positioning.md` — главное обещание + УТП + антипозиционирование.
**Особое внимание к УТП.** УТП ≠ «качество и индивидуальный подход». УТП = то, чем отличаемся от **всех** конкурентов из шага 4. См. `ad-copywriting.md` секции 0 и 0.5.
**УТП и боли — ОТДЕЛЬНО по каждому сегменту, не смешивать.** Сегмент задаётся тем, **с чем человек сравнивает нас сейчас** (его текущая альтернатива): против прямых (amoCRM), против непрямых, **«конкуренты снизу»** (Excel/руки/ничего), ничего-не-делать. У каждого — своя боль и своё УТП. Сегмент «снизу» прорабатывай отдельно и тщательно: его сообщение («хватит терять заявки в Excel») нельзя класть в одно объявление с отстройкой от amoCRM — это другой человек.
Если на сайте нет УТП и в шагах 1-4 не нашлось — **не выдумывай**. Спроси юзера прямо: «У продукта нет явного УТП на сайте. Может быть в продукте есть что-то уникальное? Менеджеры рассказывают клиентам что-то особенное?»
**Артефакты:** `05_positioning.md` (главное обещание + антипозиционирование) и **`_usp.md`** — по блоку на сегмент: текущая альтернатива → боли (3-5) → УТП → чего НЕ говорим. Каркас — в `ad-copywriting.md` секция 0.5.
**Гейт:** явное согласие на позиционирование и на разбивку по сегментам.
## Шаг 6. Buyer Personas
3-5 персон. Для каждой:
- Демография (возраст, пол, доход, образование, семейное положение, география)
- **Поведение в VK**: какие сообщества читает, какие интересы по соцграфу, частые активности
- JTBD (job to be done)
- Боли
- Возражения
- Триггеры покупки
- **5-10 точных гипотез аудиторий** (это гипотезы, не финальные настройки)
**Если API доступен** — посмотри, что уже есть: `vk_ads_remarketing_segments_list` (сегменты)
и `vk_ads_users_lists_list` (загруженные CRM-базы). Через наш REST — `vk_ads_api.py audiences-list`.
Не дублируй уже залитые. См. `references/audiences-and-lookalike.md`.
**Артефакт:** `06_personas.md` — для каждой персоны блок «Гипотезы аудиторий».
## Шаг 6.5. Архитектура аудиторий — матрица сегментации
**Это критичный шаг.** Без него на Шаге 10 структура групп объявлений будет хаотичная. Прочитай **`references/targeting-strategy.md`** и **`references/audiences-and-lookalike.md`** до начала.
**Цель:** превратить гипотезы из персон в **матрицу аудиторий**, которая ляжет в основу структуры групп объявлений (1 аудитория ≈ 1 группа).
**Как:**
1. **Сегменты по холодности (вертикальная ось):**
- Hot — те, кто уже взаимодействовал (посетители сайта, текущая база CRM, аудитория сообщества)
- Warm — lookalike по горячим / по тематическим интересам и сообществам
- Cold — широкий соцдем + интересы / посевы по сообществам конкурентов
2. **Сегменты по персоне (горизонтальная ось):**
- P1, P2, P3 из Шага 6
3. **Заполни матрицу.** Не каждая клетка обязательна — фокус на 4-6 ячейках с самой сильной гипотезой.
| Сегмент / Персона | P1 SMM-фрилансер | P2 Эксперт | P3 Блогер |
|---|---|---|---|
| Hot (посетители + база) | LAL 1% от посетителей-фрилансеров | LAL 1% от экспертов-клиентов | — |
| Warm (LAL + интересы) | Интерес «SMM», сообщества SMM-планнера | Интерес «инфобиз», аудитория курсов | Интерес «съёмка контента» |
| Cold (соцдем + широкие интересы) | 25-40, маркетинг/SMM в графе | 30-50, образование/экспертиза | 18-35, креативные индустрии |
4. **Для каждой ячейки запиши:**
- Тип аудитории VK (LAL, intent, custom, key phrases, retargeting)
- Размер (примерный)
- Источник данных (если custom — какая база; если LAL — от чего)
- Географию — **названия городов/регионов словами**; числовые `region_id` для API резолвишь позже через `vk_ads_regions_search` (Шаг 11) и фиксируешь маппинг в `_state.json`
5. **Покажи матрицу пользователю.** Очень важная точка контроля.
**Артефакт:** `_audiences.md` + новая секция в `06_personas.md`:
```markdown
## Матрица аудиторий
### Hot ячейки (3-7 дней атрибуции)
- A1: LAL 1% от посетителей лендинга (нужен пиксель + 1000+ событий)
- A2: CRM-список существующих платных клиентов (csv с phone/email, мин 1000)
### Warm ячейки
- W1: P1 — интерес «SMM и маркетинг» + ключи «контент-план», «smm специалист»
- W2: P2 — сообщества крупных образовательных платформ (список ID через UI)
### Cold ячейки
- C1: P1 — соцдем 25-40, занятость = маркетинг/SMM в профиле, gender = ж 70%
- C2: P3 — соцдем 18-35, интерес «фотография и видео» + «креатив»
```
**Гейт:** покажи матрицу, спроси «всё верно? Где-то размер слишком мал / слишком велик?». Без явного подтверждения — Шаг 10 не начинай.
**Семантика (только для горячих ячеек).** В VK «семантика» = ключевые фразы (что человек искал в VK/Mail), это **один тип таргетинга**, а не парсинг ядра как в Директе. 15-40 точных фраз на горячий сегмент — потолок. Имена конкурентов живут **здесь** (ключевые фразы / таргет на их сообщества), но **никогда в текстах объявлений** (см. `ad-copywriting.md`). Минус-слов нет — есть исключения интересов/сообществ. Оформи отдельным самодостаточным артефактом **`_semantics.md`** (каркас — в `targeting-strategy.md`, секция «Семантика в VK»).
**Особое внимание:**
- **Hot нужен пиксель** — если его нет, переходим к Шагу 7а.
- **CRM-загрузки** — минимум 1000 записей после матчинга, лучше 5000+.
- **LAL** — минимум 1000 совпавших пользователей в источнике.
## Шаг 7. Реклама конкурентов
Поиск в интернете не отдаёт креативы VK дословно. Иерархия источников:
1. **Скриншоты от пользователя** — золотой стандарт. Запроси 3-5 скриншотов рекламы в ленте VK по горячим темам.
2. **adheart.ru / publer / target hunter** если подписка.
3. **Реконструкция** через поиск в интернете (например, `WebSearch`) + ленты сообществ конкурентов. Тег `source-trust: reconstruction`.
**Если поиска в интернете нет** — остаётся только источник 1: работаем на скриншотах от пользователя. Не прислал — Шаг 7 выполнить нечем: не выдумывай креативы конкурентов. Напиши в `07_competitor_ads.md` пометку «пропущено: нет поиска в интернете и скриншотов от пользователя — реклама конкурентов не собрана. Потеряно: вход для Шага 8 (успешные паттерны). Как добрать: прислать 3–5 скриншотов рекламы в ленте VK», и на Шаге 8 строй паттерны только на брифе и разборе конкурентов Шага 4, честно назвав это гипотезой.
**Артефакт:** `07_competitor_ads.md` с пометкой источника.
## Шаг 7а. Настройка пикселя и событий (опциональный, но критичный)
Запускается если в Шаге 1 пиксель ещё не установлен. Запусти `scripts/vk_pixel_helper.py` — он сгенерит:
- Базовый код пикселя VK Ads (для вставки в `<head>`)
- Чек-лист событий под цели кампании: `page_view`, `lead`, `purchase`, `add_to_cart`, `registration` и т.д.
- Инструкцию: где взять `pixel_id` в кабинете → куда вставить → как проверить (`vk_ads_pixel_check.html`)
**Артефакт:** `07a_pixel_setup.md` с готовым кодом и пошаговой инструкцией.
**Если MCP подключён** — пиксель можно создать не руками: `vk_ads_remarketing_pixels_create(payload={...})`,
затем `vk_ads_remarketing_pixels_list` для проверки и получения `pixel_id`. Установка кода на сайт
и проверка срабатываний всё равно остаются за человеком — API отдаёт факт существования счётчика,
а не поток событий.
**Гейт:** перед запуском кампании пользователь должен подтвердить «пиксель стоит, события ловятся».
## Шаг 8. Успешные паттерны
3-5 повторяющихся паттернов из шага 7. Формулы, не текст. Включая:
- Типы офферов (скидка, дедлайн, гарантия, кейс)
- Структуры заголовков
- Композиции креативов (фото героя, скриншот продукта, видео-демо, UGC-стиль)
- CTA-формулировки
**Артефакт:** `08_patterns.md`.
## Шаг 9. Посадочные
Читаем лендинг (инструмент чтения веб-страниц, например `WebFetch`). Нечем читать или снова заблокирован — пройди чек-лист **вопросами к пользователю** и отметь каждый пункт как «со слов»; пункты, которые словами не проверить (скорость на мобиле по Lighthouse), помечай `не проверено`, а не «ок». Пометка в `09_landings.md`: «пропущено: нет чтения веб-страниц — посадочная проверена со слов, соответствие креатива и H1 не сверено».
Чек-лист (см. `landing-checklist.md`):
- H1 совпадает с обещанием в креативе
- Скорость на мобиле (Lighthouse > 70)
- Форма выше первого скролла
- Доказательства (логотипы клиентов, отзывы)
- Пиксель VK Ads установлен + события настроены
- ОРД-маркировка не требуется на лендинге (она на креативах), но юр.информация в футере обязательна
**География.** VK Реклама использует свои region_ids. Шорт-лист:
- Россия: 0 (весь), 1 (Москва), 2 (СПб), 41 (Краснодарский край), 60 (Свердловская обл.), 78 (Татарстан)
- Города: можно выбрать «город + N км»
- Беларусь: country=br, Казахстан: country=kz
- Если нужен редкий регион — через UI или `dictionaries_regions` API
**Артефакт:** `09_landing.md` + точные **regions** (с ID или названиями). Это и есть самодостаточный `_landings.md`.
## Шаг 9.5. Прогноз и сценарии бюджета (с гейтом маркетолога)
**Обязательно прочитай `references/forecasting.md`.** Это шаг, на котором скилл раньше завышал лиды/CPL. Главное правило: **базовые цифры берём из проверяемых источников, лиды/CPL не отдаём как обещание без согласования.**
Порядок:
1. **Собери базу из кабинета (MCP).** Если есть доступ (инструменты MCP-сервера `vk-ads` — например, с префиксом `mcp__vk-ads__` — либо `api_available`) — вытащи фактические **CPM и CTR** через `vk_ads_statistics_summary` / `vk_ads_statistics_day` по похожим/прошлым кампаниям клиента (из аудита Шага 0.5). Это тег `api`. Нет доступа или нет похожих кампаний → CPM/CTR только `benchmark`, и так и пометь; если причина в среде, а не в отсутствии истории, добавь пометку о пропуске в `_forecast.md`.
2. **CR и конверсию в лид НЕ выдумывай.** Спроси клиента (его Метрика/CRM). Нет ответа → прогноз обрывается на кликах, лиды = «нет данных».
3. **Посчитай сценарии:** `python -m scripts.forecast --workspace <path> --init` → впиши метрики с тегами в `forecast_inputs.json` → `python -m scripts.forecast --workspace <path>`. Получишь `_forecast.md` с тремя сценариями (минимальный/целевой/расширенный) и reality-check.
4. **Reality-check.** Если расчётный CPL ниже пола ниши, лидов меньше 50 за тест (не выйдет из обучения) или больше, чем отдел продаж обработает — **пересчитай консервативнее**, не отдавай красивое число.
5. **🚦 Гейт маркетолога.** Охваты/клики можно показывать. Лиды/CPL уходят в стратегию **только после явного согласования**: покажи таблицу источников и спроси «согласуем эти цифры?». Если «нереалистично» — возьми поправку как `client`-вход и перезапусти forecast.py.
**Артефакт:** `_forecast.md`. Лиды/CPL со статусом `⚠️ требует согласования`, пока маркетолог не подтвердил.
## Шаг 10. Креативные концепции
**Обязательно прочитай** `vk-ads-specs.md` и `ad-copywriting.md`.
Структура: для каждой ячейки матрицы аудиторий из 6.5 — отдельная группа объявлений с 3-5 креативами.
**Человеческие названия (конвенция).** Не «Кампания 1 / Группа 2», а читаемо:
- Кампания (ad_plan): `<Продукт> | <Воронка> | <Цель>` — напр. `КвартБот | Холодный трафик | Заявки`.
- Группа (campaign): `<Сегмент> · <Аудитория> · <Гипотеза>` — напр. `Снизу-Excel · C1 соцдем 22-35 · H-cold-1`.
- Креатив (banner): `cr_<сегмент>_<формат>_<вариант>` — напр. `cr_snizu_video_v2`.
**Явная связка.** В `creatives.json` у каждого креатива заполняй поля: `campaign_name`, `group_name`, `segment`, `hypothesis`, `audience_id`, `funnel_stage` (cold/warm/hot/retarget/leadmagnet/subscribers), `url` (или формат lead_form). Тогда кампания → группа → гипотеза → аудитория → воронка → посадочная → креатив связаны сквозь, и `ads.xlsx` + отчёт-стратегия строятся из одного источника и не противоречат.
**Дисциплина бюджета — не распылять.** На тесте держим деньги на немногих сильных гипотезах: ориентир ≥ ~1000 ₽/группу/день, иначе алгоритм не выходит из обучения (нужно 50+ событий). Прикинь: `бюджет/день ÷ 1000 ≈ макс. число групп`. Если гипотез больше — режь число гипотез, а не размазывай.
**Сценарии бюджета.** Заложи три (синхронно с `_forecast.md`):
- **Минимальный** — 2-3 сильнейшие группы, только горячие/тёплые ячейки.
- **Целевой** — основной план: + холодные ячейки, лид-магнит.
- **Расширенный / оптимистичный** — масштабирование на каскад LAL и доп. плейсменты после первых результатов.
**Чек-лист креатива:**
- **Заголовок** — сайт ≤ 25 знаков; приложение/сообщество/лид-форма ≤ 40 (источник: general/start/creating)
- **Текст** ≤ 2000 знаков для сайтов (новый расширенный лимит до 16 384, но первые 200-220 знаков критичны — выше «Показать ещё»)
- **Описание** для коллажа: длинное ≤ 2000 / короткое ≤ 90
- **Текст рядом с кнопкой** ≤ 30 знаков
- **«О компании»** (юр.информация) ≤ 115 знаков
- **CTA-кнопка** — из списка VK (Купить, Узнать больше, Подписаться, Записаться, Заказать звонок и т.д.)
- **Маркировка ОРД** — автоматическая в VK Реклама, но проверь что галочка «Передать данные в ОРД» включена
**Форматы (по приоритету для теста):**
1. **Универсальная запись** — flagship, работает почти всегда
2. **Карусель** — для линейки продуктов / нескольких преимуществ
3. **Видео** — для холодных аудиторий + клипы для P3 (блогеры/креаторы)
4. **Лид-форма VK** — для оптимизации на лиды без лендинга (мобильный трафик)
См. `vk-ads-specs.md` для полного списка с размерами и техтребованиями.
**Тестовая матрица:** 3 креатива на группу, различия в одной оси (заголовок / визуал / CTA — но не всё сразу).
**Проверка перед сдачей:**
- Лимиты VK (см. specs)
- УТП — настоящее (не «качество и индивидуальный подход») и **от правильного сегмента** (Шаг 5 / `ad-copywriting.md` 0.5)
- **Не «ни о чём»**: в первых 220 знаках ≥2 из 4 — оффер / боль / число / след. шаг
- **Имена конкурентов НЕ в тексте** (только в таргете/ключах) — иначе риск ст. 5 ФЗ и отказ модерации
- **Нет сравнений «лучше чем X» / «№1 / самый / единственный»** без пруфа и оговорки
- Требования модерации: нет КАПС, превосходных степеней без пруфа, контактов в основном тексте, более одного «!». Запрещены «100% гарантия», «лучший на рынке», «единственный».
- Закон о рекламе РФ: маркировка ОРД (автоматическая), лицензии для медицины/инвестиций/образования, возрастные ограничения 18+ если применимо
- Дисклеймеры: «Имеются противопоказания, проконсультируйтесь со специалистом» для медицины; «Реклама. ИП Иванов И.И., ИНН ...» в поле «О компании»
**Артефакты:** `10_creatives.md` + **`creatives.json`** (machine-readable) + **`audiences.json`** (для импорта).
После — `python -m scripts.generate_ads_xlsx --workspace <path>` → xlsx/csv + warnings.txt с проблемными креативами (превышение лимитов, потенциальные триггеры модерации).
## Шаг 10.5. Генерация визуала (M1 — картинки)
**Когда:** после Шага 10 (есть creatives.json), перед финальным заливом. **Обязательно прочитай** `references/visual-generation.md` и `references/credentials.md`.
**Цель:** превратить текстовые описания визуала в `creatives.json` (например «split-screen messy Excel vs clean PlanFix») в реальные .png-файлы готовые для залива в VK.
### Pre-flight 1: brand.json
Создай `brand.json` в рабочей папке с цветами и стилем продукта (см. `scripts/brand_defaults.json` для структуры). Если не создать — используются defaults.
Пример для B2B SaaS:
```json
{"product_name": "PlanFix", "primary_color": "#1E40AF", "accent_color": "#22C55E"}
```
Пример для e-commerce / fashion:
```json
{"product_name": "ZARA-style", "primary_color": "#000000", "accent_color": "#D4AF37"}
```
Пример для услуг (доставка / beauty / repair):
```json
{"product_name": "BeautyBot", "primary_color": "#EC4899", "accent_color": "#FB7185"}
```
### Pre-flight 2: ключ OpenAI
**Главное правило:** скилл должен работать «в одно окно» — пользователь не открывает терминал, не запускает команды, не редактирует файлы. Всё происходит через диалог с тобой.
**Если в среде нет запуска кода или сетевых вызовов по ключу — весь модуль M1 пропускается.** Ключ спрашивать не надо: генератор всё равно не запустить. Вместо картинок собери в `10_creatives.md` **ТЗ дизайнеру текстом** по описаниям визуала из `creatives.json`: формат и размер под VK, композиция, что на переднем плане, цвета из `brand.json`, текст на картинке. Пометка: «пропущено: нет генерации визуала — картинки не созданы, вместо них ТЗ дизайнеру. Потеряно: готовые файлы для залива. Как добрать: прогнать `scripts/generate_creative_images.py` с ключом OpenAI либо отдать ТЗ дизайнеру». Скажи пользователю прямо: **без визуала кампанию не залить**, это блокер Шага 11, а не мелочь.
Стратегия запроса ключа (для модели):
1. **Сначала проверь сохранён ли уже ключ.** Выполни сам инструментом запуска кода (например, `mcp__workspace__bash`):
```
python -m scripts.manage_credentials list
```
Если в выводе есть `openai` — ключ уже есть, Pre-flight 2 закрыт. Переходим к запуску генерации.
2. **Если ключа нет** — **попроси пользователя скинуть его в чат** (это Способ Б — дефолт для коллег без терминального опыта):
> Мне нужен ключ OpenAI для генерации картинок. Скинь его сюда — я сохраню в безопасном месте (`~/.vk-ads-manager/credentials.json`, права 600, вне папки проекта). Спрашивать больше не буду, ключ сработает для всех будущих кампаний.
>
> Если ключа нет — заведи на https://platform.openai.com/api-keys (нужен платёжный метод, минимум ~$5 на счёт). Это займёт 2 минуты.
3. **После того как пользователь пришлёт ключ** — сразу сохрани его через bash:
```
python -m scripts.manage_credentials set openai --key <KEY>
```
Подтверди в чате: «✓ ключ сохранён, ввожу его в работу».
4. **Альтернатива (Способ А — только если пользователь явно скажет «я сам введу»):**
Попроси пользователя самостоятельно выполнить:
```
python -m scripts.manage_credentials set openai
```
Это запросит ключ через `getpass` — ввод не светится в терминале.
**Никогда не сохраняй ключ в `_state.json`, `creatives.json`, `operations_log.md` или других артефактах рабочей папки** — они могут уйти клиенту в архиве. Только в `~/.vk-ads-manager/credentials.json`.
**После сохранения** Claude никогда не повторяет ключ в чате, только маска (через `manage_credentials get openai`).
**Workflow:**
1. **Dry-run первым** — генерация только промптов, без вызова API:
```
python -m scripts.generate_creative_images --workspace <path> --dry-run
```
Создаёт `assets/prompts/<creative_name>.txt` для каждого статичного креатива. Прочитай 1-2, оцени промпт, при необходимости попроси Claude улучшить шаблон в `prompt_templates.py`.
2. **Тест на одном креативе** — реальный вызов API:
```
python -m scripts.generate_creative_images --workspace <path> --only cr_pain_p2_static
```
Получаешь одну картинку в `assets/images/`. Смотришь, нравится / не нравится. Если не нравится — `--force` и итерируешь промпт.
3. **Полный прогон** когда промпты работают:
```
python -m scripts.generate_creative_images --workspace <path>
```
**Что генерится автоматически:**
- ✅ `ebook_cover` — обложки PDF lead magnet
- ✅ `pain_split` — split-screen «до/после»
- ✅ `abstract_brand` — брендовые композиции с текстом
- ✅ `carousel_card` — карточки карусели
**Что НЕ генерится автоматически (выводится placeholder + предупреждение):**
- ❌ `ui_mockup` — реальные UI-скриншоты продукта. AI делает их плохо. **Запрашивай у клиента реальные high-res скрины** (минимум 2160×2160).
- ❌ Видео — это модуль M2 (Veo / Kling / Runway), пока не реализован.
- ❌ UGC с реальными людьми — нужен живой человек на камеру.
**Артефакты:**
- `assets/images/<name>.png` — готовые картинки для залива
- `assets/prompts/<name>.txt` — сохранённые промпты (для аудита и тюнинга)
- `assets/generation_log.json` — лог запуска со статусами каждого креатива
**Гейт:** ревью картинок в `assets/images/` перед заливом. Те что в статусе `needs_real_screenshot` — добавь к списку запросов клиенту, приложив шаблон запроса из `references/vk-ads-specs.md` (правила к ссылкам). Скриншоты интерфейса запрашивай от 2160×2160 — меньшее разрешение придётся запрашивать повторно.
## Шаг 10.6. Генерация видео (M2 — Runway / провайдеры)
**Когда:** после Шага 10.5 (есть `creatives.json` + желательно картинки в `assets/images/`), перед заливом. **Обязательно прочитай** `references/video-generation.md`.
**Цель:** создать MP4-видео для креативов где `format` или `image_or_video` содержит «video» (например `cr_pain_p1_video`, `cr_ugc_p1`).
**Если в среде нет запуска кода или сетевых вызовов по ключу — модуль M2 пропускается целиком.** Провайдера и модель не выбирай, ключ не спрашивай. Вместо видео собери в `10_creatives.md` **ТЗ на съёмку/монтаж**: длительность, раскадровка по секундам, что в кадре, текстовые оверлеи, музыка, финальный CTA — по тем же описаниям, что пошли бы в промпт. Пометка: «пропущено: нет генерации видео — MP4 не созданы, вместо них ТЗ на съёмку. Потеряно: готовые видеокреативы. Как добрать: прогнать `scripts/generate_creative_videos.py` с ключом провайдера либо снять по ТЗ». Видео-креативы при этом **не считай готовыми** на Шаге 11: либо заливаем кампанию только с картинками, либо ждём видео.
### Pre-flight 1: выбор провайдера и модели
**Рекомендуемый дефолт — `replicate`** (один ключ → десятки моделей, быстрая смена SOTA, A/B сравнения).
При работе с Replicate **обязательно выбрать модель** через `--model <slug>`:
- `kwaivgi/kling-v1.6-standard` — универсал дефолт ($0.05/sec)
- `bytedance/seedance-1-pro` — высокое качество motion ($0.15/sec)
- `bytedance/seedance-1-lite` — дёшево для перебора вариантов ($0.04/sec)
- `minimax/hailuo-02` — лучшие лица для UGC ($0.45/clip)
- `kwaivgi/kling-v2-master` — текущий флагман Kling ($0.28/sec)
- Полный каталог: `references/replicate-models.md`
Стратегия выбора модели:
- **Pain reframe / split-screen без людей** → `kwaivgi/kling-v1.6-standard`
- **UGC с реальным человеком** → `minimax/hailuo-02` или `kwaivgi/kling-v2-master`
- **Product demo (UI скринкаст)** → `bytedance/seedance-1-pro`
- **Дешёвый перебор вариантов** → `bytedance/seedance-1-lite`
- **Премиум финал** → `google/veo-3` (если в бюджете)
**Альтернативные провайдеры** (прямые API без Replicate):
- `runway` — Runway Gen-4 Turbo ($0.05/sec, 5/10s)
- `kling` — прямой Kling API (требует AccessKey+SecretKey)
- `veo` — Google AI Studio (премиум $0.50/sec)
- `aismm` — для владельцев AiSMM Pro
Прямые провайдеры могут быть дешевле/быстрее Replicate, но требуют отдельных ключей и не дают гибкости в смене моделей.
Спроси пользователя если выбор не очевиден. Если нет ясного предпочтения — используй `replicate` с моделью под тип креатива.
### Pre-flight 2: ключ провайдера
По шаблону из Шага 10.5 Pre-flight 2 (Способ Б — дефолт):
1. Проверь через `python -m scripts.manage_credentials list` есть ли ключ выбранного провайдера.
2. Если нет — попроси пользователя скинуть в чат:
> Для видео-генерации нужен ключ Runway. Скинь сюда — я сохраню. Если ключа нет: app.runwayml.com/account → Settings → API. Минимум ~$10 на счёт.
3. Получив ключ — выполни `python -m scripts.manage_credentials set runway --key <KEY>`.
### Workflow (для Replicate — рекомендуемый)
#### Шаг A: Dry-run (бесплатно)
```
python -m scripts.generate_creative_videos --workspace <path> --dry-run
```
Промпты сохранятся в `assets/video_prompts/`. Прочитай 1-2 — убедись что качественные.
#### Шаг B: A/B Variants (3 варианта первого сегмента)
```
python -m scripts.generate_creative_videos \
--workspace <path> \
--only cr_pain_p1_video \
--provider replicate \
--model kwaivgi/kling-v1.6-standard \
--variants 3
```
Создаст `cr_pain_p1_video_seg1_var1.mp4`, `_var2.mp4`, `_var3.mp4` (~$0.75 за все 3 на Kling Standard).
**Покажи варианты пользователю** способом, который есть в среде (например, `computer://`-ссылками) — пусть выберет лучший. Нечем показать — дай пути к файлам.
#### Шаг C: Финализация с выбранным + дозагенерирование + склейка
```
python -m scripts.generate_creative_videos \
--workspace <path> \
--only cr_pain_p1_video \
--provider replicate \
--model kwaivgi/kling-v1.6-standard \
--chosen-variant 2 \
--target-duration 15 \
--chain-segments
```
- Вариант 2 копируется как `seg1`
- Генерируются `seg2`, `seg3` с предыдущим last frame как seed (плавные переходы)
- Склейка через FFmpeg → финальный `cr_pain_p1_video.mp4` (15s)
#### Альтернативный workflow (без variants, для дешёвого теста одного варианта)
```
python -m scripts.generate_creative_videos \
--workspace <path> \
--provider replicate \
--model bytedance/seedance-1-lite \
--target-duration 5
```
**MVP ограничения (важно сказать пользователю):**
- **5 секунд максимум** — Runway Gen-4 Turbo возвращает 5 или 10s, мы дефолтим в 5s через `--max-duration 5`
- **Без звука** — Runway не генерит аудио. Озвучку добавлять отдельно (ElevenLabs / реальный диктор / закадровый текст в Premiere)
- **Без overlay-текста** — добавляется в постпродакшене (CapCut / DaVinci / Premiere)
- **Image-to-video с seed** — экспериментально, лучше работает для медленного движения
**Артефакты:**
- `assets/videos/<name>.mp4` — готовые видео-файлы
- `assets/video_prompts/<name>.txt` — сохранённые промпты
- `assets/video_generation_log.json` — лог + оценка стоимости
**Гейт:** ревью видео в `assets/videos/`. Если качество не устраивает — итерируй промпт в `video_prompt_templates.py` или попроси пользователя снять реальное видео (особенно для UGC).
## Шаг 10.7. PDF Lead magnet (M3)
**Когда:** в стратегии есть eBook-креативы (формат `carousel_with_lead_form` или name содержит `ebook`). Это главная ставка стратегии — 40% бюджета на конверсионную кампанию через email-цепочку. **Обязательно прочитай** `references/pdf-generation.md`.
**Цель:** создать реальные PDF которые пользователь будет получать после заполнения лид-формы VK. Без PDF eBook-креатив не работает — нечего отдавать.
### Workflow
1. **Узнай какие PDF нужны** — выполни:
```
python -m scripts.generate_lead_magnet_pdfs --workspace <path> --list-expected
```
Скрипт покажет какие eBook-креативы есть и какие markdown-файлы ожидаются.
2. **Напиши контент в диалоге с пользователем.** Для каждого eBook-креатива:
- Спроси у пользователя: какие 5-7 разделов хочется? Есть ли реальные кейсы? Какие цифры?
- Напиши markdown — экспертный, конкретный, без воды. 5-10 страниц A4 (~1000-2000 слов).
- Сохрани через `Write` в `assets/pdf_content/<creative_name>.md`.
- Покажи пользователю → жди ОК или правки.
3. **Собери PDF**:
```
python -m scripts.generate_lead_magnet_pdfs --workspace <path>
```
- Использует обложки от M1 (`<name>_card1.png`) и CTA от M1 (`<name>_card3.png`) если они есть.
- Если их нет — генерирует программную обложку и CTA через ReportLab.
- PDF в `assets/pdfs/<name>.pdf`.
4. **Покажи пользователю PDF** тем способом, который есть в среде (например, `computer://`-ссылкой); нечем показать — дай путь к файлу. Проси проверить. Правки → меняем markdown → `--force` для перегенерации.
**Если в среде нет запуска кода — PDF не собрать.** Пункты 1 и 3 пропускаются, пункт 2 остаётся: markdown-контент лид-магнита ты всё равно пишешь в диалоге и сохраняешь в `assets/pdf_content/<creative_name>.md`. Пометка: «пропущено: нет запуска кода — PDF не собран, готов только markdown-контент. Потеряно: файл лид-магнита для залива. Как добрать: прогнать `scripts/generate_lead_magnet_pdfs.py` или собрать PDF из markdown вручную». Скажи пользователю, что eBook-креативы без файла лид-магнита заливать нет смысла — обещание в объявлении будет нечем закрыть.
### Что писать в markdown — пример каркаса
```markdown
# 5 готовых процессов для агентства
## Введение
Если вы агентство 2-5 человек, ведёте 5-10 клиентов и теряете задачи между Telegram, Trello и Excel — эта PDF для вас.
Внутри: 5 рабочих процессов которые можно настроить в PlanFix за 2 часа без программиста.
---
## Процесс 1: Брифы и согласования с клиентом
Текст с конкретикой про шаги, шаблоны полей, кто получает уведомления.
### Как настроить за 15 минут
1. Шаг
2. Шаг
3. Шаг
---
(ещё 4 раздела по той же структуре)
---
## Что делать дальше
Получили PDF — настройте 1 процесс из 5 на этой неделе. Если нужна помощь — 14 дней триал, поддержка отвечает за 2 часа.
```
`---` создаёт разрыв страницы.
**Гейт:** PDF проверен пользователем. После этого в лид-форму VK при заливе (Шаг 11) добавляется автоотправка PDF на указанный email (это настраивается в самой VK лид-форме как «успешный экран» + интеграция с email-сервисом клиента).
**Что НЕ делает MVP:**
- ❌ Автоотправка PDF на email — нужна интеграция с email-сервисом (Mindbox / SendPulse / Unisender) у клиента
- ❌ Дизайнерская вёрстка с иллюстрациями — для каждого раздела
- ❌ Embedded интерактивные элементы (формы внутри PDF)
---
# Шаг 11. Финальный залив в кабинет
**Когда:** после Шагов 10/10.5/10.6 — есть `creatives.json`, `audiences.json`, картинки в `assets/images/`, видео в `assets/videos/` (где есть). Реквизиты для ОРД зафиксированы.
## Какой путь выбрать
| Путь | Когда выбирать | Что нужно от среды |
|---|---|---|
| **A. vk-ads-mcp** (рекомендуется) | Есть инструменты MCP-сервера `vk-ads` | Вызов MCP-инструментов. Запуск кода не нужен |
| **B. Наш REST API** (M4) | MCP нет, но есть запуск кода и токен VK Ads | Запуск кода + сетевые вызовы по ключу (`scripts/deploy_campaign.py`) |
| **C. Ручной залив** (M5) | Ни MCP, ни запуска кода; либо клиент не выдаёт токен | Только файлы и диалог |
Выбирай **первый путь, который среда позволяет**, а не первый по списку предпочтений. Ушёл на путь C не по выбору клиента, а из-за среды — это пропуск, помечай его в `launch_log.md`.
### Путь A: vk-ads-mcp (рекомендуемый)
**Если инструменты MCP-сервера `vk-ads` есть** (в одной среде они видны с префиксом `mcp__vk-ads__`, в другой имена выглядят иначе — ищи по короткому имени: `vk_ads_ad_plans_create`, `vk_ads_content_upload_image`):
0. **Выбор кабинета:** если в режиме click.ru доступно несколько кабинетов — `vk_ads_accounts_list`, покажи список пользователю, зафиксируй выбранный `account_id` и передавай его в каждый последующий вызов.
0.1. **Пакет размещения (`package_id`) — обязателен, без него создание группы падает.**
`vk_ads_packages_list(objective="<цель>")` → выбери пакет и зафиксируй его `id` в `_state.json`.
Правила отбора: (1) только `status: "active"` — в выдаче встречаются `blocked`;
(2) `priced_event_type` определяет модель оплаты — `0` = CPM, `1` = CPC, `30` = oCPM;
(3) при равных условиях бери пакет с `banner_format_id: 0` (мультиформат) —
он не привязывает тебя к одному формату креатива.
Всего на сервере ~174 пакета, поэтому **всегда фильтруй по `objective`**, не тяни полный список.
Доступные значения `objective` приходят в поле `available_objectives` того же ответа;
для воронки этого скилла рабочие — `leadads` (лид-формы) и `site_conversions` (конверсии на сайте).
Покажи пользователю выбранный пакет словами («оплата за показы, мультиформат») и подтверди.
0.2. **Гео → `region_id`.** `targetings.geo.regions` принимает **числовые id**, а не названия.
Для каждого города/региона из `audiences.json` — `vk_ads_regions_search(query="<название>")`,
возьми `id` из `items`. Полное дерево (`vk_ads_dictionary_get(name="regions")`) не тяни — оно
большое (5500+ регионов). Ничего не нашлось или нашлось несколько — **спроси пользователя**,
какой регион имелся в виду, не угадывай. Зафиксируй маппинг «название → id» в `_state.json`.
1. **Пре-флайт по каждой ссылке.** До загрузки проверь URL: HEAD-запрос должен вернуть `Content-Type: image/jpeg` или `image/png`. Вернулся `text/html` — это страница просмотрщика (типовой случай: шаренная ссылка Google Drive / Яндекс.Диска), файл по ней не скачается. Вернулась ошибка или таймаут — ссылка приватная либо во внутренней сети. В обоих случаях **не вызывай загрузку**: покажи пользователю конкретную ссылку и запроси замену по правилам из `references/vk-ads-specs.md`. Ни одной битой ссылки на входе в залив.
2. **Загрузка медиа:** для каждой картинки/видео — `vk_ads_content_upload_image` / `vk_ads_content_upload_video`, параметр `source_path_or_url`. ⚠️ **Хостовый сервер (aihub.click.ru) не читает локальные файлы** — только публичный http(s)-URL. Файлы из `assets/images/` сначала выложи по ссылке (или залив медиа делай через путь B — `deploy_campaign.py` умеет локальные файлы). **Сохраняй возвращённые `id`: API не отдаёт список ранее загруженного контента, потерянный ID означает повторную заливку и мусор в хранилище.**
3. **Создание ad_plan (UI «Кампания», верхний уровень):** `vk_ads_ad_plans_create` с `payload`, где nested `campaigns: [...]` (по числу аудиторий) и nested `banners: [...]` внутри каждой campaign. Один атомарный вызов — избегаем orphan'ов.
4. **Альтернатива (если атомарный payload слишком большой):** `vk_ads_ad_plans_create` → потом `vk_ads_campaigns_create(ad_plan_id=..., banners=[...])` по одной группе за вызов. ⚠️ Баннеры передаются **внутри** payload группы: отдельного `banners_create` в API нет, «долить» объявления в уже созданную группу невозможно. Группа, созданная без `banners`, навсегда останется пустой — её придётся удалять и пересоздавать.
5. **Все объекты в `status: "blocked"`** — никогда не активируй сам.
6. **Проверка:** `vk_ads_ad_plans_get(ad_plan_id=...)`, затем по каждой группе `vk_ads_ad_groups_get(ad_group_id=..., fields="id,name,status,banners,issues")`. **Обязательно убедись, что `banners` не пустой.** Пустой массив + issue `NO_BANNERS_WITH_ACTIVE_STATUS` означает, что залив креативов провалился — сообщи пользователю и не выдавай ссылку как успешный результат.
Полезные поля для диагностики: `vk_ads_campaigns_list(fields="id,name,status,objective,budget_limit,budget_limit_day,ad_plan_id,package_id,targetings,issues")`
— `issues` показывает словами, почему группа не крутится (`NO_BANNERS_WITH_ACTIVE_STATUS`,
`NO_MONEY`, `AD_PLAN_STOPPED`, `STOPPED`).
7. **Дай ссылку:** `https://ads.vk.ru/hq/campaign/<ad_plan_id>` (в URL это всё ещё `/campaign/`, исторически).
**Если MCP-инструментов нет** — предложи подключение к хостовому серверу за 2 минуты (ничего клонировать и ставить не надо):
```
python -m scripts.setup_vk_ads_mcp --token <CLICK_RU_TOKEN> --vk-account-id <ID_АККАУНТА> --target all
```
См. `references/vk-ads-mcp-integration.md` для полной инструкции. Установщик требует запуска кода: если кода запустить нельзя — конфиг пишет человек по `docs/hosted-mcp-setup.md`, а ты идёшь на путь B или C, не пытаясь настроить MCP сам.
### Путь B: наш REST API (если MCP не подключен)
**Главный скрипт:** `scripts/deploy_campaign.py`
### Pre-flight: ключ VK Ads
По шаблону Способа Б:
1. Проверь `python -m scripts.manage_credentials list` — есть ли `vk_ads`.
2. Если нет — попроси:
> Для залива в кабинет нужен access_token VK Ads API. Получить: ads.vk.ru → Настройки → API → создать приложение → токен. Скинь сюда — я сохраню.
3. Получил → `python -m scripts.manage_credentials set vk_ads --key <KEY>`.
### Workflow для модели
1. **Сначала dry-run** — покажи пользователю что будет создано:
```
python -m scripts.deploy_campaign --workspace <path> --dry-run
```
Выведет план без реальных вызовов. Покажи пользователю саммари: «создам 1 кампанию, N групп, M баннеров, бюджет X — ОК?».
2. **После «ОК» — реальный запуск**:
```
python -m scripts.deploy_campaign --workspace <path>
```
Что произойдёт:
- Загрузит все медиа из `assets/images/` и `assets/videos/`
- Создаст ad_plan — «Кампанию» верхнего уровня (status=blocked)
- Создаст campaigns — «Группы объявлений» по числу аудиторий, каждая с `ad_plan_id` (всё blocked)
- Создаст banners — «Объявления» с привязкой медиа, каждое с `campaign_id` (всё blocked)
- Запишет в `operations_log.md`
- Сохранит `assets/deploy_plan.json` со всеми ID
3. **Дай ссылку пользователю**:
```
✅ Кампания создана: https://ads.vk.ru/hq/campaign/<id>
Открой кабинет → проверь Сценарий 10 → активируй кнопкой «Запустить».
```
**Никогда не активируй** (`status: active`) автоматически. Это всегда финальное действие пользователя через UI после прохождения чек-листа.
### Сценарий 10 (предзапусковый чек-лист) — напомни пользователю
Перед тем как пользователь нажмёт «Запустить» в кабинете:
- [ ] Все группы внутри проверены (бюджет, таргетинг, плейсменты)
- [ ] Все креативы прошли модерацию VK (`status: accepted`, обычно 1-4 часа после создания)
- [ ] Пиксель установлен и стреляет (см. Шаг 7а)
- [ ] События пикселя замаплены на цели в кабинете
- [ ] Лендинг доступен с мобилки, форма работает
- [ ] ОРД-данные заполнены (плашка «Реклама. Рекламодатель: ...»)
- [ ] UTM-метки на месте
- [ ] Бюджет соответствует плану
- [ ] Есть план на первые 3 дня мониторинга (Сценарий 11 daily check)
### Если API недоступен — M5 ручной залив
Если у пользователя/клиента нет токена VK Ads (или клиент не готов выдавать, или API возвращает ошибки), **или в среде нет вызова MCP-инструментов и запуска кода** — используй M5:
```
python -m scripts.generate_launch_guide --workspace <path>
```
Скрипт читает `creatives.json` + `audiences.json` + `_state.json` + `brand.json` → собирает `LAUNCH_GUIDE.md` с пошаговой инструкцией:
- Шаг 0: чек-лист подготовки (доступы, реквизиты ОРД, файлы)
- Шаг 1: настройка ОРД в кабинете
- Шаг 2: создание кампании (с точными значениями бюджета, цели, стратегии)
- Шаг 3: создание групп (по числу аудиторий — таргетинг описан построчно)
- Шаг 4: создание баннеров (полные тексты для copy-paste + ссылки на файлы медиа)
- Шаг 5: финальный чек-лист
- Шаг 6: активация и первые часы
Опционально добавь `--docx` чтобы сгенерить ещё `LAUNCH_GUIDE.docx` (для печати / отправки клиенту).
**Если в среде нет запуска кода** — генератор не поможет, но путь остаётся: напиши `LAUNCH_GUIDE.md` **сам**, руками, по той же структуре из семи шагов выше, взяв точные значения из `creatives.json`, `audiences.json`, `_state.json` и `brand.json`. Это единственный путь залива, который работает при обязательном минимуме способностей, поэтому пропускать его нельзя. Пометка: «пропущено: нет запуска кода — `LAUNCH_GUIDE.md` написан вручную, `.docx` не собран. Как добрать: прогнать `scripts/generate_launch_guide.py`».
Покажи получившийся гайд способом, который есть в среде (например, `computer://`-ссылкой), либо дай путь к файлу. Оператор или маркетолог со стороны клиента сможет залить руками за 1-2 часа.
**Раздел «Пропущено из-за среды» в `launch_log.md` — обязательный.** Собери в него все пометки о пропуске со всех шагов одним списком: какой шаг, какой способности не было, что сделано вместо, что недобрано, что делать человеку. Пропусков не было — напиши «пропусков нет, все шаги выполнены полностью». Этот раздел пользователь читает **до** активации кампании.
### Что НЕ делает deploy_campaign в MVP
- ❌ Не создаёт lookalike audiences (требуют source — у первого запуска нет)
- ❌ Не загружает CRM-базы (нужны CSV — опциональная отдельная команда)
- ❌ Не создаёт пиксель — путь B этого не умеет. Через MCP умеет: `vk_ads_remarketing_pixels_create` (см. Шаг 7а)
- ❌ Не активирует кампанию — только пользователь
---
---
# Шаг 11 (опциональный). Пост-релизная оптимизация
**Когда:** через 5-7 дней после активации. Триггер: «прошла неделя», «оптимизация VK».
1. Статистика за период: `vk_ads_statistics_day(entity="campaigns", ids="<id через запятую>", date_from=..., date_to=...)`.
⚠️ `ids` обязателен — режима «по всему кабинету» нет, сначала `vk_ads_campaigns_list`.
MCP недоступен — прямой REST `GET /statistics/campaigns/{id}/day.json` (см. `vk-ads-api.md`).
2. По каждой группе:
- CTR < 0.3% + Impressions > 5000 → креатив устарел / аудитория не та → перезалить или выключить
- CTR > 1.5% + Clicks > 50 → масштабировать (увеличить бюджет в 1.5-2x)
- Высокий CTR + низкий CR → проблема в лендинге, не в креативе
- Лиды есть, но дорогие → попробовать стратегию «предельная цена» с лимитом CPL
3. **Look-alike дозалив:** если в горячей аудитории накопилось > 1000 конверсий → создать LAL 1%, 2-3%, 4-5% — тестировать каскадом.
4. **Минусы:** в VK нет ключевых минус-слов, но есть исключения интересов и сообществ. Анализ — через отчёт `keywords` (если включён key phrases targeting).
5. `11_optimization.md` с конкретным action plan по каждой группе.
6. С согласия — изменения через `vk_ads_api.py`. Никогда не удаляй сущности — только пауза.
**Безопасность.** Никогда не вызывай автоматически:
`vk_ads_*_delete` (любые), `vk_ads_campaigns_set_status(status="active")`,
`vk_ads_ad_plans_update({"status": "active"})`, `vk_ads_banners_update({"status": "active"})`.
Разрешено без отдельного «запускай»: чтение, `*_update` неструктурных полей после «ОК»,
создание сегментов и списков.
⚠️ У `ad_plan` **нет** метода `set_status` — пауза и запуск «Кампании» целиком идут только
через `vk_ads_ad_plans_update({"status": "blocked"|"active"})`. У `campaign` метод есть:
`vk_ads_campaigns_set_status`.
---
# Шаг 12. Итоговый отчёт-стратегия для команды агентства
**Когда:** в самом конце обработки — собраны creatives.json, audiences.json, `_forecast.md`, артефакты конкурентов/УТП/семантики/посадочных. Триггер: «собери стратегию», «отдай отчёт для команды», «финальный документ».
Запусти:
```
python -m scripts.generate_ads_xlsx --workspace <path>
python -m scripts.generate_strategy_report --workspace <path> --docx
```
Что получится в `<path>/report/`:
- **`strategy_report.md`** (+ `.docx`) — сводный отчёт для команды агентства: резюме/УТП, **карта воронок** (холодный/ретаргет/лид-магниты/подписчики), **посадочные и лид-формы явно**, **структура кампаний** (связка из того же источника, что и `ads.xlsx`), **прогноз** со статусом согласования, **«что запросить у клиента»**, чек-лист согласований.
- Отдельные самодостаточные .md по блокам: `_competitors.md`, `_semantics.md`, `_usp.md`, `_landings.md`, `_funnels.md`, `_campaign_structure.md`, `_forecast.md`, `_client_requests.md`, `_strategy.md` — каждый можно показать/отдать по отдельности.
**Важно:** структура и воронки в отчёте выводятся из `creatives.json`, поэтому отчёт и `ads.xlsx` не противоречат друг другу. Если что-то правишь — правь creatives.json и перегенерируй оба.
**Если в среде нет запуска кода** — отчёт собери сам: напиши `report/strategy_report.md` по перечисленным разделам, читая те же артефакты, и разложи самодостаточные блоки по отдельным `.md`. Вместо `ads.xlsx` — Markdown-таблица `ads.md`. Пометка: «пропущено: нет запуска кода — отчёт и таблица объявлений собраны вручную, `.docx` и `.xlsx` не сгенерированы. Потеряно: валидация лимитов и юр.чистоты, которую делает `generate_ads_xlsx`. Как добрать: прогнать оба скрипта в среде с Python». Валидацию при этом **пройди глазами** по `references/vk-ads-specs.md` и `references/ad-copywriting.md` — иначе отчёт уйдёт с текстами, которые не пройдут модерацию.
**Раздел «Пропущено из-за среды» в отчёте — обязательный.** Продублируй в него сводный список пропусков из `launch_log.md`, чтобы команда агентства видела, какие блоки стратегии построены на полных данных, а какие нет.
**Перед выдачей** проверь чек-лист согласований в конце отчёта (список конкурентов, УТП по сегментам, прогноз согласован маркетологом, тексты юр.чисты, структура = xlsx). Покажи пользователю `strategy_report.docx` и нужные `.md` тем способом, который есть в среде (например, `computer://`-ссылками), либо перечисли пути к файлам.
---
# Lifecycle: повседневная работа с активной кампанией
Второй большой режим. **Полный набор сценариев — в `references/lifecycle-runbook.md`** (13 операций с проверками безопасности).
## Главные правила lifecycle
1. **Никогда не активируй** (`status: active`) без явного «запускай».
2. **Никогда не удаляй** сущности (audiences, campaigns, banners) — только пауза (`status: blocked`).
3. **Перед write — план + «ОК?»**.
4. **После операции — `GET`** той же сущности для проверки.
5. **Логируй в `operations_log.md`**: дата, операция, до/после, причина, подтверждение.
## Когда какой сценарий
| Триггер | Сценарий | R/W |
|---|---|---|
| «Как у нас VK?» | 1: общий отчёт | Read |
| «Daily check» | 11: ежедневный мониторинг | Read |
| «Увеличь/сократи бюджет» | 2 | Write |
| «Пауза / запусти снова» | 3 | Write |
| «Активируй кампанию» | 10: предзапусковый чек-лист | Write |
| «Добавь lookalike» / «сделай похожих» | 4 | Write |
| «Загрузи CRM-базу» | 5 | Write |
| «Измени текст / визуал креатива» | 6 | Write |
| «Добавь интересы / сузь аудиторию» | 7 | Write |
| «Прошла неделя, оптимизация» | 8 / Шаг 11 | Write |
| «Переключи стратегию ставок» | 9: «минимальная» ↔ «предельная цена» | Write |
| «Корректировки по соцдему» | 12 | Write |
| «Скопируй кампанию» | 13 | Write |
## Ограничения API VK Ads — фолбеки
| Не умеет через API | Фолбек |
|---|---|
| ~~Создать пиксель~~ — **умеет**: `vk_ads_remarketing_pixels_create` | — (фолбек не нужен) |
| Проверить, что пиксель стреляет | Только UI / браузер — API отдаёт факт существования, а не события |
| Загрузка events через UI (manual) | UI или Conversion API (отдельная интеграция) |
| Сложные правила автоматизации | UI или внешний скрипт на cron |
| Дублирование с правкой одного поля | API копирует + апдейт отдельно |
Когда упираешься — **скажи прямо**: «Через API не сделать. Покажу в UI» — и дай пошаговый сценарий для ads.vk.ru.
---
# Стиль работы
- **Не клянчи.** Один прямой вопрос за раз.
- **Не вываливай простыни.** Артефакт в файл, сводка в чат 5-10 строк.
- **Гипотеза > пустой вопрос.** «Вот моя версия — согласны?»
- **Защищай качество** на шагах 5, 6 и 6.5 — это шаги где скилл даёт максимум value.
- **Бюджет важен** — предупреди при <30 тыс ₽ / 2 недели (алгоритм не успеет выйти из обучения).
- **Не выдумывай метрики и УТП** — «не знаю» лучше выдуманного.
- **Не завышай прогноз.** Охваты/клики — из кабинета (MCP); лиды/CPL — только производные с тегом источника и **гейтом согласования маркетолога**. Нереалистично — пересчитай сценарии, не защищай красивую цифру.
- **Не смешивай сегменты.** У каждого сегмента (вкл. «конкурентов снизу» — Excel/руки) свои боли и своё УТП. Имена конкурентов — в таргете/ключах, не в текстах.
- **VK ≠ Директ.** В VK работаем с **аудиториями**, а не с поисковыми запросами. Не пытайся притянуть keyword research из контекста.
- **Пользователь не оператор.** Все скрипты запускай сам инструментом запуска кода (например, `mcp__workspace__bash`). Запускать код нечем — передай команду пользователю с пояснением «моё окружение не даёт мне это запустить, выполните пожалуйста: ...» и попроси прислать вывод. И это невозможно — иди по ветке «если нет» этого шага.
- **Пропуск всегда виден.** Шаг, выполненный без необязательной способности среды, получает пометку о пропуске в свой артефакт (формат — в «Что нужно от среды»), а на гейте ты говоришь об этом словами. Молча упрощённый результат — хуже честно недобранного.
- **Ключи в чате — это нормально.** Когда пользователь скидывает API-ключ — благодари кратко, сразу сохраняй через `manage_credentials.py set <service> --key <KEY>`, в следующих сообщениях не повторяй ключ (используй маску если нужно). Хранилища нет (нет запуска кода) — скажи прямо, что ключ сохранить негде, и не проси его заранее.
- **Показывай результат.** После генерации картинки или создания кампании — покажи файл способом, который есть в среде (например, `computer://`-ссылкой или встраиванием в чат). Нечем показать — дай путь к файлу от корня рабочей папки. Пользователь не должен лазить по папкам наугад.
# Возобновление
«Продолжаем по VK» → найди `vk-campaign-*/`, прочитай `_state.json` и `launch_log.md` / `operations_log.md`, продолжай с того места. Не начинай сначала.
Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.
No comments yet. Be the first to comment!
