Yandex Direct — пайплайн создания кампании
Скилл проводит маркетолога от брифа до залитой в DRAFT рекламной кампании в Яндекс.Директе. Фокус — только создание: семантика → кластеризация → минусы → объявления → заливка. Аналитика, оптимизация уже работающих кампаний, исследования рынка — не задача этого скилла.
Пайплайн опирается на два MCP: yandex-direct (прогноз CPC, аудит аккаунта, дедупликация, заливка кампании целиком) и yandex-wordstat (частотности и сбор семантики на Шагах 1 и 3). Оба — хостовые серверы aihub.click.ru: локально ничего не запускается, Bun и клон репозитория не нужны. Подключение — scripts/setup_yandex_direct_mcp.py (пишет конфиги Cursor / Claude Code / Claude Desktop), общий справочник — docs/hosted-mcp-setup.md репозитория пакета. Скилл не проверяет подключение MCP заранее — если на каком-то шаге инструмент не отвечает, обрабатываем ошибку по месту: Шаг 2 уходит на справочник CPC, Шаги 1 и 3 — на scripts/wordstat_api.py или браузер, Шаг 10 — на Директ Коммандер.
Что нужно от среды
Обязательный минимум — две способности:
- Чтение и запись файлов в рабочей папке
direct-campaigns/<slug>/. На этом держится весь пайплайн: каждый шаг порождает артефакт, следующий шаг его читает.
- Диалог с пользователем — задать вопрос, получить ответ, дождаться подтверждения. Без этого не работают гейты
[GATE: маркетолог], а они здесь не формальность: заливка идёт только после явного «ОК».
Больше ничего обязательного нет. Всё перечисленное ниже — необязательно: без любой из этих способностей скилл доходит до конца, но часть данных недобрана.
Необязательные способности. У каждой есть ветка «если нет». Идёшь по ветке — печатаешь пометку о пропуске в артефакт этого шага (формат ниже).
| Способность |
Где нужна |
Если нет |
| Запуск кода — Python 3.9+ и команды оболочки |
Шаги 1, 2, 3, 8, 10 (scripts/*) |
Отдай команду пользователю текстом, попроси прислать вывод и работай с ним как со своим. Если и это невозможно: Шаги 1 и 3 — браузерный пробив частотностей или список от маркетолога; Шаг 8 и Шаг 10 — ручная сверка лимитов по references/yandex-direct-specs.md вместо preflight.py; Шаг 10 — Директ Коммандер вместо generate_ads_xlsx. Теряется: автоматическая проверка лимитов Директа перед заливкой — самая дешёвая защита от отклонённых объявлений. |
| Дочерние агенты — субагент или форк контекста |
Шаги 3–4 |
Выполни Шаги 3–4 инлайн по subagents/semantics.md и references/wordstat-filter.md. Не пересказывай CSV в чат — работай через файлы. Теряется: изоляция контекста; тысячи ключей Wordstat останутся в основном разговоре и вытеснят решения Шагов 0–2 к моменту написания объявлений. |
| Чтение веб-страниц по URL |
Шаг 0 (сайт продукта), Шаг 7 (проверка счётчика Метрики) |
Шаг 0 — попроси у маркетолога 5 пунктов словами (H1, бенефиты, CTA, цена/триал, доказательная база), помечай source: со слов клиента. Шаг 7 — попроси прислать counter_id из интерфейса Метрики. Теряется: сверка заявленного с тем, что реально на сайте. |
| Поиск в интернете |
Шаг 8 (сверка отстройки с топ-3 выдачи) |
Пиши тексты по УТП из брифа, без сверки с конкурентами. Теряется: проверка, что заголовки действительно отличают продукт, а не повторяют выдачу. |
Вызов MCP-инструментов (хостовые серверы yandex-direct и yandex-wordstat, aihub.click.ru) |
Директ: 0.5 (выбор кабинета), шаги 2, 5, 8, 10. Wordstat: шаги 1, 3 |
Шаг 2 — справочник CPC из references/frequency-calculator.md вместо живого аукциона; Шаг 5 — регионы по справочнику; Шаг 8 — дедупликация ключей по выгрузке от маркетолога; Шаг 10 — Директ Коммандер по references/direct-commander-import.md; Шаги 1 и 3 — scripts/wordstat_api.py (нужен ключ Cloud) или браузерный пробив по references/wordstat-browser.md. Теряется: живые данные аккаунта, автоматическая заливка и автоматический пробив частотностей — кампанию и семантику собирает человек руками. |
| Браузер под сессией пользователя |
Шаг 1, Шаг 3 — только когда нет ключа Wordstat |
Непробитые фразы помечай frequency: n/a. Прикидку не подставляй: выдуманная частотность хуже отсутствующей, на ней стоит весь расчёт бюджета. |
| Сетевые вызовы внешних API по ключу — Метрика; Wordstat (только как фолбек без MCP) |
Шаг 7; шаги 1, 3 (фолбек) |
Шаг 7 — режим «инструкции для UI»: скилл готовит план целей, маркетолог заводит их руками. Шаги 1 и 3 без MCP yandex-wordstat и без ключа Cloud — браузерный пробив или список ключей от маркетолога. Теряется: автоматическая настройка целей, а в фолбеке — автоматический сбор семантики. |
Названия инструментов в тексте ниже — примеры. Где встречаются WebFetch, Task, claude-in-chrome, mcp__yandex-direct__*, mcp__yandex-wordstat__* — это имена из одной конкретной среды, приведённые для наглядности. Ориентируйся на способность, а не на имя инструмента: если в твоей среде он называется иначе, но делает то же — используй его.
Пометка о пропуске
Шаг выполнен без необязательной способности — впиши в артефакт этого шага строку такого вида:
⚠️ пропущено: нет <способность или источник данных> — <что сделал вместо>. Потеряно: <что именно недобрано>. Как добрать: <что сделать человеку>.
Например:
⚠️ пропущено: нет доступа к Вордстату — частотности не пробиты, в 01_masks.json стоит frequency: n/a. Потеряно: отсев масок ниже порога 150 показов/мес. Как добрать: пробить список на wordstat.yandex.ru и вернуться на Шаг 1.
Все пометки шагов продублируй сводным списком в 10_launch_log.md, раздел «Пропущено из-за среды». Маркетолог должен видеть все пробелы в одном месте, а не искать по десяти файлам. Молча упрощённый результат не отдаём.
Когда триггерится
- «Сделай рекламную кампанию в Директе» / «запусти РК» / «создай кампанию»
- «Собери семантику для Директа» / «нужны ключи»
- «Сделай минусацию» / «собери минус-слова»
- «Напиши объявления для Директа» / «подготовь креативы»
- «Залей кампанию через MCP» / «закинь в DRAFT»
- Любой запрос на создание новой кампании в Директе для русскоязычного продукта
Главный принцип
Каждый шаг порождает артефакт. Рабочая папка: direct-campaigns/<slug>/. Артефакты накапливаются и являются входами для следующих шагов. На ключевых шагах — гейт [GATE: маркетолог] с явным «ОК» перед движением дальше. Заливка происходит только в DRAFT. Активация — всегда руками маркетолога.
Как использовать references
Длинные методологии лежат в references/ — Claude открывает их в нужный момент.
| Reference |
Когда читать |
Зачем |
references/brief.md |
Шаг 0 |
Шаблон нового брифа под короткий пайплайн |
references/mask-builder.md |
Шаг 1 |
Методология двух колонок А (сужающие) × Б (общие) |
references/frequency-calculator.md |
Шаг 2 |
Формула расчёта частотности + справочник CPC |
references/wordstat-filter.md |
Шаг 4 |
Пороги НЧ<350/СЧ 350-750/ВЧ>750 + распределение Поиск/РСЯ |
references/campaign-structure.md |
Шаг 5 |
Правила разбиения семантики на кампании и группы |
references/negative-keywords-builder.md |
Шаг 6 |
3 уровня минусов + кросс-минусация |
references/metrika-goals-setup.md |
Шаг 7 |
Шаблоны целей по нишам + Metrika Management API |
references/yandex-direct-specs.md |
Шаг 8 |
Лимиты Директа, форматы, операторы |
references/ad-copywriting.md |
Шаг 8 |
Формулы заголовков и текстов, требования модерации |
references/rsya-creatives.md |
Шаг 8.5 |
Техтребования Директа к РСЯ-креативам, workflow генерации по гейтам, чек-лист модерации |
references/visual-generation.md |
Шаг 8.5 |
Генерация картинок через OpenAI (generate_creative_images.py): архитектура, brand.json, форматы |
references/video-generation.md |
Шаг 8.5 |
Генерация видео через Replicate (generate_creative_videos.py) |
references/replicate-models.md |
Шаг 8.5 |
Каталог видео-моделей Replicate: цены, качество, рекомендации |
references/bidding-strategy.md |
Шаг 9 |
3-фазная эволюция стратегии торгов |
references/yandex-direct-mcp.md |
Шаг 10 + при сбоях MCP |
Справочник MCP: сигнатуры инструментов, единицы, dry_run, хостовое подключение, чего MCP не умеет |
references/mcp-account-integration.md |
Шаги 2, 5, 10 |
Сценарии по шагам: аудит аккаунта, дедупликация, оценка CPC, регионы и полная последовательность заливки (Use case 5) |
references/wordstat-mcp.md |
Шаги 1, 3 + при сбоях Wordstat |
Пробив частотностей через MCP yandex-wordstat (wordstat_shows_batch) и цепочка путей расширения семантики (скрипт Cloud API / комбинаторика / браузер) |
references/wordstat-browser.md |
Шаг 1 / Шаг 3 (нет ни MCP, ни API-ключа) |
Пробив частотностей через браузер пользователя (фолбек вместо симуляции) |
references/direct-commander-import.md |
Шаг 10 (фолбек) |
Импорт xlsx в Директ Коммандер — когда MCP недоступен |
references/ad-legal-topics.md |
Шаг 0 + Шаг 8 |
Факт-таблица лицензируемых/запрещённых тем: стоп-гейт и автопредупреждения |
Как использовать scripts
scripts/preflight.py — проверка 08_creatives.json против лимитов Директа перед заливкой (Шаг 10). Ошибки — заливка не стартует
scripts/generate_ads_xlsx.py — 08_creatives.json → xlsx для маркетолога и для фолбека в Коммандер (или CSV)
scripts/generate_media_plan.py — собирает артефакты пайплайна в media_plan.docx
scripts/keyword_helper.py — операторы соответствия, базовые минус-листы
scripts/forecast_cpc.py — оценка CPC: разбор keywordbids_get, прямой аукцион, либо прогноз по фразам (v4 / Click.ru DRAFT) без MCP forecast_bids
scripts/generate_creative_images.py — генерация картинок Шага 8.5 (OpenAI gpt-image-1)
scripts/generate_creative_videos.py — генерация видео Шага 8.5 (Replicate)
scripts/validate_assets.py — проверка картинок/видео под техтребования Директа
scripts/manage_credentials.py / scripts/credentials.py — реестр ключей (openai, replicate, yandex_direct, clickru) вне рабочей папки
scripts/wordstat_api.py — основной путь расширения семантики (Шаг 3, путь 1): клиент Yandex Cloud Search API (Wordstat topRequests), --mode masks / --mode semantics (рекурсивный сбор волнами с ассоциациями); env WORDSTAT_API_KEY + WORDSTAT_FOLDER_ID; --check для проверки. MCP yandex-wordstat покрывает только частотности (wordstat_shows_batch), семантику не расширяет — см. references/wordstat-mcp.md
scripts/setup_yandex_direct_mcp.py — подключение хостовых MCP yandex-direct и yandex-wordstat (aihub.click.ru) к Cursor / Claude Code / Claude Desktop: токен click.ru, --target, --dry-run, --remove. Запускается, когда MCP в среде не видны. Локальный stdio-вариант (клон репозитория + Bun) остаётся для разработки самих серверов — см. references/yandex-direct-mcp.md
Архитектура: оркестратор + субагенты
Скилл работает как оркестратор в основном контексте: держит бриф, _state.json, гейты и финальную сборку (медиаплан, заливка). Самый тяжёлый шаг — сбор и кластеризация семантики — вынесен в изолированный субагент semantics (форк), чтобы тысячи ключей из Wordstat не засоряли основной контекст к моменту генерации объявлений и заливки. Инструкция субагента — в subagents/semantics.md (это обычный файл-инструкция, а не второй SKILL.md).
| Шаг |
Где исполняется |
Почему |
| 0–2 (включая 0.5) (бриф, кабинет, маски, прогноз частотности) |
Инлайн |
Решения и гейты |
| 3 — сбор семантики |
Субагент semantics |
Тысячи ключей из Wordstat |
| 4 — кластеризация |
Субагент semantics |
Чтение того же большого CSV |
| 5–10 (структура, минусы, цели, объявления, стратегия, заливка) |
Инлайн |
Анализ, синтез, заливка |
Принцип возврата: субагент собирает семантику в своём контексте, пишет артефакты на диск и возвращает наверх только сводку ≤20 строк. Гейт и решение — у маркетолога в основном контексте.
Фолбек: если субагент недоступен (старая среда, ошибка форка, путь не резолвится) — оркестратор выполняет Шаги 3-4 инлайн по тем же reference/scripts. Делегирование — оптимизация, а не жёсткая зависимость.
Субагент лежит в subagents/semantics.md (файл-инструкция, не SKILL.md); сам по инициативе модели не запускается — его порождает оркестратор. References и scripts — единые, в корне скилла; субагент читает их по пути от корня.
Workflow: 10 шагов
Шаг 0. Бриф
Прочти references/brief.md целиком. В нём — точная формулировка вопросов и формат 00_brief.md.
Задай маркетологу одним блоком 12 пунктов брифа (продукт, URL, регион, бюджет, каналы, тип запросов, УТП + сужающие, цель в Метрике, CPA-таргет + ценность конверсии + коллтрекинг, существующие материалы, slug проекта, лицензируемая/запрещённая тематика + документы).
Параллельно — прочитай сайт продукта инструментом чтения веб-страниц (например, WebFetch). Если такого инструмента в среде нет или страница заблокирована — попроси у маркетолога 5 пунктов словами: H1, бенефиты, CTA, цена/триал, доказательная база. Помечай source: со слов клиента и впиши в 00_brief.md пометку о пропуске: «пропущено: нет чтения веб-страниц — данные о продукте со слов клиента, с сайтом не сверены».
Артефакт: direct-campaigns/<slug>/00_brief.md + _state.json (current_step, slug, product_name, доступность Wordstat: wordstat_mcp_available и/или wordstat_api_available; после Шага 0.5 добавляются direct_client_login, direct_account_name, direct_mode, direct_forecast_available, direct_server).
[GATE: маркетолог] «Бриф верный? Идём дальше?»
[СТОП-ГЕЙТ: тематика] Сверься с references/ad-legal-topics.md. Если продукт из полностью запрещённых в РФ тем (азартные игры, оружие, табак, рецептурные, аборты и т.д.) — пайплайн останавливается, кампанию в Директе не запустить: сообщи маркетологу прямо и не трать шаги на семантику. Если тема лицензируемая (медицина, финансы, алкоголь и т.д.) — зафиксируй в брифе, есть ли документы; без них — предупреждение и блок до предоставления. Учитывай автопредупреждения Директа (они съедают символы объявления на Шаге 8).
Шаг 0.5. Кабинет Директа
Читай references/mcp-account-integration.md → Use case 0.
Один вызов accounts_get({}): он проверяет связность MCP, показывает режим подключения
(прокси click.ru или прямой OAuth) и список доступных кабинетов.
[GATE: маркетолог] если кабинетов больше одного — «В какой кабинет заливаем?»
Артефакт: _state.json → direct_client_login, direct_account_name, direct_mode,
direct_forecast_available, direct_server.
Дальше client_login подставляется в каждый вызов инструментов Директа, относящихся к
кабинету (исключение — accounts_get, forecast_bids, dictionaries_*: они к кабинету не
привязаны).
Если MCP Директа нет — шаг пропускается с пометкой; пайплайн идёт по ветке без
live-данных и заканчивается Директ Коммандером.
Шаг 1. Маски
Прочти references/mask-builder.md целиком.
Передать: УТП и продукт из 00_brief.md, регион, тип спроса (определяется по контексту брифа: срочный/B2B/премиум/ручная работа/массовый), доступ к Wordstat API.
⚠️ В отличие от старого пайплайна, нет внешнего hypothesis-builder. Сужающие слова берутся напрямую из брифа: если маркетолог дал в поле «УТП» что-то вроде «премиум», «ручная работа», «срочно» — это сужающее. Если в брифе нет явных сужающих — задай один уточняющий вопрос: «Какие 1-3 слова определяют ваш угол отстройки (например: премиум, срочно, для самозанятых)?»
На выходе:
01_masks_matrix.md — две колонки А (сужающие) × Б (общие + товарозаменители) с языковыми и смысловыми синонимами
01_masks.json — machine-readable, рабочие маски с частотностями из Wordstat
01_masks_wordstat_log.md — лог итераций
Частотности масок: приоритет — MCP yandex-wordstat (wordstat_shows_batch, все маски одним вызовом, см. references/wordstat-mcp.md). Если MCP не подключён — фолбек scripts.wordstat_api --mode masks (нужен ключ Cloud Search API). Если нет ни MCP, ни ключа — пробей частотности через браузер пользователя (references/wordstat-browser.md), а не прикидкой. Пробив в браузере делает оркестратор.
Два гейта: (1) первая матрица — «правильное направление?», (2) после расширения и Wordstat — «финальный список?».
Шаг 2. Прогноз частотности
Прочти references/frequency-calculator.md целиком. Параллельно — Use case 1–3 из references/mcp-account-integration.md (аудит существующих кампаний, дедупликация ключей, оценка CPC).
Передать: бюджет на поиск из брифа (доля поиска × общий месячный бюджет), 01_masks.json (для прогноза CPC через MCP), регион из брифа.
Приоритет источника CPC: историческая AvgCpc похожих кампаний (report_campaign) → живой аукцион по ключам аккаунта (keywordbids_get, парсит scripts/forecast_cpc.py) → прогноз по своим маскам (forecast_bids, до 100 фраз, без создания кампании) → справочник CPC по нишам → override от маркетолога. Сам у маркетолога CPC не спрашиваем.
⚠️ В режиме прокси click.ru forecast_bids недоступен. Есть ли в сессии второе подключение в прямом OAuth — проверь по _state.json → direct_forecast_available (Шаг 0.5): прогноз можно посчитать там, заливка останется в выбранном кабинете. Нет — справочник CPC.
На выходе:
02_frequency.md — 3 сценария (оптимистический/базовый/пессимистический)
02_frequency.json — необходимая суммарная частотность с ×2 запасом
_account_audit.md (если есть похожие существующие кампании) — для контекста и предотвращения каннибализации
Гейт: маркетолог подтверждает или корректирует прогноз.
Шаг 3. Расширение семантики и пробив частотностей [делегируется субагенту semantics]
Расширение семантики + кластеризация (Шаг 4) вынесены в изолированный субагент semantics (форк): он готовит seed/anchors из 01_masks.json, расширяет ядро одним из путей ниже, пробивает частотности через MCP yandex-wordstat (wordstat_shows_batch) или фолбеком, пишет 03_semantics_raw.csv и сразу кластеризует его. Тысячи ключей остаются в форке.
⚠️ Сервер yandex-wordstat не расширяет семантику. Он отвечает «сколько показов у фразы», но не «какие ещё запросы бывают»: реально доступен только пакетный пробив частотностей (wordstat_shows_batch, до 1000 фраз за вызов). Рекурсивные волны через MCP невыполнимы — расширение берётся отдельно, а MCP пробивает частотности готового списка.
Что готовит оркестратор: slug из _state.json, регионы из брифа, необходимую суммарную частотность из 02_frequency.json.
Как запустить субагент: порождай дочерний агент через инструмент субагентов/форка твоей среды (например, в Claude Code — Task с subagent_type: general-purpose, тулы Bash Read Write Grep Glob), передай ему целиком текст subagents/semantics.md и три аргумента: slug, регионы, необходимая_частотность. Эквивалент вызова:
субагент semantics ← subagents/semantics.md аргументы: <slug> "<регионы>" "<необходимая_частотность>"
Субагент возвращает: сводку ≤20 строк (собрано ключей, путь расширения cloud-api | combinatorial | list | browser, распределение по 4 CSV, суммарная частотность vs нужная с флагом НЕДОБОР, причина остановки) + пути к 03_semantics_raw.csv и 04_keys_*.csv. Сырьё CSV остаётся в форке.
Если среда не умеет субагенты/форк (например, Claude Desktop без инструмента Task, ChatGPT) — выполни Шаги 3-4 инлайн по методологии ниже. Делегирование — оптимизация, а не жёсткая зависимость. Инлайн-исполнение не считается пропуском способности и пометки о пропуске не требует: данные собираются те же, страдает только чистота контекста. Но если из-за объёма пришлось урезать сбор — это пропуск, помечай.
Цепочка приоритетов расширения (полная методика и правила — references/wordstat-mcp.md → «Шаг 3»):
- Скрипт Cloud Search API (
scripts/wordstat_api.py --mode semantics) — единственный путь с настоящей рекурсией волнами и ассоциациями; нужен ключ WORDSTAT_API_KEY + WORDSTAT_FOLDER_ID и запуск кода. Частотности — из того же ответа.
- Комбинаторная генерация кандидатов из
01_masks.json + пакетный пробив через MCP wordstat_shows_batch — когда есть только MCP.
- Список от маркетолога / выгрузка сторонним сервисом + пакетный пробив.
- Браузерный пробив (
wordstat-browser.md) — нет ни MCP, ни ключа; делает оркестратор.
Готовим два файла в рабочей папке (нужны для пути 1):
_masks_seed.txt — стартовые семена: узкие комбинации из 01_masks.json плюс широкие одиночные слова продукта (база колонки Б + синонимы: картины, панно, холст). Широкие слова обязательны — без них волна 0 узкая.
_anchors.txt — якоря-основы продуктовых слов колонки Б + синонимов (картин, панно, холст), по одному на строку. Запрос становится семенем следующей волны, только если содержит хотя бы один якорь — это держит рекурсию в теме продукта.
Путь 1 (предпочтительный) — скрипт Cloud API: та же логика рекурсивных волн готовым скриптом:
python -m scripts.wordstat_api --mode semantics \
--phrases-file direct-campaigns/<slug>/_masks_seed.txt \
--anchors-file direct-campaigns/<slug>/_anchors.txt \
--regions <из брифа> \
--output direct-campaigns/<slug>/03_semantics_raw.csv
Профиль «Стандарт» (дефолт): глубина 2, до 150 семян на волну, порог семени 10 показов, стоп при <5% нового, ≤1000 вызовов / ≤15 минут. Профиль «Глубокий» — флаги --max-depth 3 --seeds-per-wave 300 --dry-threshold 0.03 --max-api-calls 5000 --max-minutes 40. Профили — свойство скрипта Cloud API, а не MCP.
Путь 2 — комбинаторика + пакетный пробив (когда есть только MCP): сгенерируй кандидатов из 01_masks.json (продуктовые слова × сужающие × модификаторы намерения × словоформы, 300–1000 штук), пробей пачкой wordstat_shows_batch, отсей stat < 150, сделай одну волну углубления. Детали — references/wordstat-mcp.md → «Шаг 3, путь 2».
Работай файлами: каждая волна/пачка дописывает 03_semantics_raw.csv, в чат — только итог (1 строка). Тысячи ключей в контекст не тащим.
Артефакт: 03_semantics_raw.csv со столбцами keyword,frequency,mask_parent,source,depth. Для Шага 4 значимы первые три столбца.
🚫 Категорически нельзя дописывать в 03_semantics_raw.csv непробитые фразы с выдуманной частотностью. Не пробита — либо frequency: n/a с пометкой, либо не в файле.
Если суммарная частотность ниже необходимой из 02_frequency.json — на пути 1 прогони профиль «Глубокий»; если всё равно мало — вернись на Шаг 1, расширь колонку Б (новые товарозаменители/синонимы) или попроси у маркетолога новые сужающие, и допиши их в _masks_seed.txt и _anchors.txt.
Если расширения через Cloud API нет (нет ключа WORDSTAT_API_KEY / нет запуска кода) — иди по путям 2–4. Через MCP расширения семантики не будет, только пробив частотностей; в 03_semantics_raw.csv и в сводке Шага 3 — обязательная пометка о пропуске: «пропущено: нет расширения семантики через Вордстат — сервер yandex-wordstat умеет только частотности; ядро построено комбинаторикой масок и пробито пакетно. Как добрать: прогнать scripts/wordstat_api.py --mode semantics с ключом Yandex Cloud или прислать ядро сторонним сервисом списком».
Если Wordstat недоступен вообще (нет MCP yandex-wordstat и python -m scripts.wordstat_api --check упал / нет ключа / среда не запускает код) — переходим на браузерный пробив частотностей (путь 4) через сессию пользователя (references/wordstat-browser.md). Пробив делает оркестратор (у форка semantics браузерных инструментов нет). Непробитые фразы помечаем frequency: n/a — прикидку не подставляем. Дальше расчёт бюджета Шага 2 считается непроверенным — так и скажи на гейте.
Шаг 4. Кластеризация (НЧ/СЧ/ВЧ + Поиск/РСЯ) [делегируется субагенту semantics]
4 CSV ниже уже произведены субагентом semantics (Шаг 3) — он кластеризует 03_semantics_raw.csv по этому же reference. Если субагент недоступен, оркестратор делает это инлайн. В любом случае гейт и решение — здесь, в основном контексте.
Прочти references/wordstat-filter.md целиком (нужно оркестратору для проверки распределения на гейте и для инлайн-фолбека).
Передать: 03_semantics_raw.csv, тип ниши и каналы из брифа (Поиск/РСЯ/оба), бюджет (для решения по ВЧ).
На выходе (4 CSV + summary):
04_keys_search_obligatory.csv — НЧ + СЧ для Поиска (база)
04_keys_search_vch.csv — ВЧ для Поиска (только при бюджете ≥100к + массовый продукт + бренд)
04_keys_rsya.csv — СЧ + ВЧ для РСЯ
04_keys_excluded.csv — отброшенные с причиной
04_wordstat_filter_summary.md — отчёт + гейт
Пороги: НЧ <350, СЧ 350-750, ВЧ >750 показов/мес. Минимум 150 показов/мес — иначе отбрасываем.
Гейт: маркетолог подтверждает распределение или корректирует.
Шаг 5. Структура кампаний
Прочти references/campaign-structure.md.
Шаг 5.1. Построение структуры
Модель объявлений одна — комбинаторное объявление в ЕПК (классическая ТГО-модель убрана: ТГО заморожены с 30.06, автомиграция ТГО→комбинаторное с 14.07 — их технически не создать). Гейта выбора модели больше нет.
Строй структуру по разделу «Модель структуры (комбинаторная ЕПК)» в references/campaign-structure.md:
- По умолчанию: 1 угол/сегмент/лендинг → 1 РК (1 группа, 1 комбинаторное объявление); Поиск+РСЯ+Галерея+Карты обслуживаются одной РК — не разделяем.
- Если нужна раздельность Поиск/РСЯ — экспертные варианты ЕПК «только Поиск» / «только РСЯ» (а не отдельные классические кампании).
- Углы/сегменты (Премиум, Срочно, Бренд, B2B) по-прежнему разносятся по отдельным РК.
- Автотаргетинг на Поиске обязателен (в ЕПК его нельзя выключить, только ограничить категориями) и может дать половину трафика группы и больше — особенно на узкой семантике. Поэтому в структуре у каждой РК задаём осознанно:
autotargeting_categories (какие категории запросов разрешены) и autotargeting_bid (ставка автотаргетинга рядом с обычной ставкой). MCP этими полями пока не управляет — они уходят в 10_launch_log.md ручной настройкой, но решение по ним принимается здесь, а не молчаливым дефолтом. Детали — references/campaign-structure.md.
Жёсткого потолка на число кампаний нет — см. «Много кампаний — мягкая подсказка» в референсе.
Артефакт: 05_campaign_structure.md — таблица с колонками #, Кампания, Тип, Угол, Бюджет, Группы + machine-readable 05_campaign_structure.json для следующих шагов.
[GATE: маркетолог] «Эту схему берём? Не объединять ли что?»
Шаг 6. Минус-слова и кросс-минусация
Прочти references/negative-keywords-builder.md целиком.
Передать: 05_campaign_structure.json, ключи из всех CSV Шага 4, сужающие слова кампаний, тип ниши.
На выходе (7 артефактов):
06_negative_keywords_account.csv — аккаунт-уровень
06_negative_keywords_search.csv — Поиск-уровень
06_negative_keywords_rsya.csv — РСЯ-уровень (короткий)
06_negative_keywords_cross.csv — кросс-минусы по кампаниям
06_cross_minus_matrix.md — наглядная матрица
06_negative_keywords.json — machine-readable, идёт в MCP-заливку
06_negative_summary.md — сводка
Гейт: маркетолог подтверждает 3-уровневое распределение + кросс-матрицу.
Шаг 7. Метрика и цели
Прочти references/metrika-goals-setup.md целиком.
Передать: URL сайта из брифа, цель в Метрике из брифа, OAuth-токен Yandex Metrika с правом write (без него — режим «инструкции для UI»), 05_campaign_structure.json, тип ниши.
На выходе:
07_metrika_audit.md — состояние счётчика и существующих целей
07_metrika_goals_plan.md — план новых целей (до создания)
07_metrika_setup_log.md — лог вызовов API
07_metrika_goals.json — финальный результат с counter_id, goal_ids и привязкой к кампаниям
Алярма: если Метрики на сайте нет — стоп пайплайна, маркетолог сначала устанавливает счётчик.
[GATE: маркетолог] подтверждает план целей до создания через API.
После — привязка к кампаниям на Шаге 10: counter_ids и priority_goals передаются прямо в campaigns_add (или в campaigns_update для уже созданной кампании). Ценность конверсии для priority_goals берётся из брифа; её нет — передаём только counter_ids, цели не выдумываем.
Шаг 8. Объявления
Обязательно прочитай references/yandex-direct-specs.md и references/ad-copywriting.md до написания.
Модель одна — одно комбинаторное объявление на РК (1 группа). См. ad-copywriting.md → «Комбинаторное объявление» и лимиты в yandex-direct-specs.md:
- 3-7 заголовков (≤56 симв., минимум 2 коротких ≤35), обязательное вхождение ключа хотя бы в один. Отдельного «Заголовка 2» в комбинаторном нет — есть набор равноправных заголовков с разными углами;
- 2-3 текста (≤81 симв.), каждый самодостаточен;
- картинки (до 5) и видео (до 6) из ассетов брифа — нет ассетов — без них, TODO в Шаг 8.5;
- быстрые ссылки (4-8), уточнения (2-4), отображаемая ссылка;
- Минусы группы — узкие, только для этой группы;
- опциональные элементы роста CTR (если есть данные в брифе): кнопка действия, цена, промоакция (до +30% CTR), карусель 2–10 изображений — см.
ad-copywriting.md → «Дополнительные элементы». Цену/акцию/промокод берём только реальные, не выдумываем.
Для лицензируемых тем сверься с references/ad-legal-topics.md: Директ вставит автопредупреждения (№334), которые съедают символы — не рассчитывай на полный лимит заголовка/текста.
Артефакт 08_creatives.json в форме ЕПК (в группе объект combined_ad) — схема assets/creatives_schema_combined_example.json.
Финальная проверка через MCP:
- Дедупликация ключей через
keywords_get (Use case 2 в mcp-account-integration.md)
- Прогноз CPC через
report_campaign с campaign_ids похожих кампаний (из _account_audit.md) и date_range: LAST_30_DAYS; без campaign_ids вызов упадёт. Иначе берём из 02_frequency.json
Артефакты: 08_creatives.md (для маркетолога) + 08_creatives.json (machine-readable). Схема: assets/creatives_schema_combined_example.json.
После — python -m scripts.preflight --workspace <path>: проверка лимитов комбинаторного (заголовки, тексты, длины слов, отображаемая ссылка, быстрые ссылки, уточнения, наличие файлов картинок, объём минус-фраз). Затем python -m scripts.generate_ads_xlsx --workspace <path> → xlsx/csv + warnings.txt для маркетолога.
Если среда не запускает код — отдай обе команды пользователю текстом и попроси прислать вывод. Не может и он — сверь лимиты вручную по references/yandex-direct-specs.md (пройди тот же перечень: заголовки, тексты, длины слов, ссылки, уточнения, объём минус-фраз) и впиши в 08_creatives.md пометку: «пропущено: нет запуска кода — preflight.py не прогонялся, лимиты сверены вручную. Потеряно: машинная проверка перед заливкой. Как добрать: прогнать python -m scripts.preflight в среде с Python». Ручная сверка не отменяет гейт: объявление с нарушенным лимитом Директ отклонит.
[GATE: маркетолог] «Объявления принимаешь?»
Шаг 8.5. Визуалы (генерация картинок и видео)
Прочти references/rsya-creatives.md и references/visual-generation.md целиком
(для видео — ещё references/video-generation.md).
Если в брифе только Поиск — шаг пропускается. Если РСЯ есть:
- Pre-flight: собери
brand.json в рабочей папке из брифа (product_name, цвета
HEX, style_references). Проверь ключи: python -m scripts.manage_credentials list.
Нет ключа openai — попроси пользователя прислать в чат и сохрани:
python -m scripts.manage_credentials set openai --key <KEY>. Ключ НИКОГДА
не пишем в артефакты рабочей папки.
- Концепции: добавь в
08_creatives.json каждой группе
combined_ad.visual_concepts (2 концепции: id A/B, type, angle, usp_on_creative —
УТП из Шага 1, углы из гипотез). [GATE: маркетолог подтверждает концепции]
- Dry-run:
python -m scripts.generate_creative_images --workspace <path> --dry-run
→ прочитай 1–2 промпта из assets/prompts/.
- Тест:
... --concept A → одна картинка. [GATE: нравится? иначе — правь
концепцию/шаблон и --force]
- Полный прогон:
python -m scripts.generate_creative_images --workspace <path>
→ до 5 картинок на группу (A×3 форматов + B×2).
- Видео (опционально): выбери модель по
references/replicate-models.md,
python -m scripts.generate_creative_videos --workspace <path> --model <slug> —
1 ролик 5–10 с, 16:9. Ключ replicate — как в п.1. Предупреди о стоимости до запуска.
- Валидация:
python -m scripts.validate_assets --workspace <path> — все ассеты
должны пройти (450–5000 px, соотношения, ≤10/100 МБ).
- [GATE: маркетолог смотрит assets/images и assets/videos перед заливкой]
Фолбек без ключей: собери 08_5_rsya_creatives_TODO.md (ТЗ дизайнеру по
references/rsya-creatives.md), кампания заливается без визуалов, TODO в launch log.
Артефакты: assets/images/*.png, assets/videos/*.mp4, assets/prompts/,
assets/generation_log.json, assets/validation_report.json; обновлённый
08_creatives.json (visual_concepts, images, videos).
Шаг 9. Стратегия торгов
Прочти references/bidding-strategy.md целиком (подраздел «Комбинаторная ЕПК — одна стратегия на РК»).
В комбинаторной ЕПК Поиск и РСЯ — одна кампания, поэтому одна стратегия на РК (без раздельных Поиск/РСЯ-стратегий); в 09_bidding_strategy.json у кампаний "channel": "epk".
Бюджет — недельный (базовая единица 2026, мин. 300 ₽/нед); дневной — только для ручных ставок на Поиске, тоже от 300 ₽. Если РК несколько по разным углам с одной целью — рассмотри пакетную стратегию (общий пул обучения: порог ≥10 конв/нед считается суммарно по пулу, до 100 РК) — это спасает мелкие/премиум РК от «голода» по конверсиям. Детали — в bidding-strategy.md.
Передать: 05_campaign_structure.json (кампании + бюджеты), целевые CPC из 02_frequency.json, целевые CPL/CPA из брифа, 07_metrika_goals.json (критичный вход — goal_id для оптимизации в Фазе 3), состояние коллтрекинга (из брифа), тип ниши.
На выходе:
09_bidding_strategy.md — план с 3-фазной эволюцией (Старт → Промежуточная → Масштаб) и триггерами переключения
09_bidding_strategy.json — machine-readable для заливки: каждая фаза описана параметрами API (search_strategy / network_strategy с типом и обязательными полями), а не свободным текстом. Таблица соответствия — в bidding-strategy.md → «Маппинг в API»
09_bidding_monitoring.md — что и когда мониторить
Стратегия Фазы 1 заливается через MCP вместе с кампанией на Шаге 10 — доделывать руками её не нужно. Пакетную стратегию MCP не умеет: если она рекомендована, пункт уходит в 10_launch_log.md.
Главное правило: на старте — НЕ «Максимум конверсий». «Максимум кликов» (с ограничением средней цены клика) 2 недели → ужесточить ограничение средней цены клика → (после 10+ конверсий/нед, для приложений 70/нед) → «Максимум конверсий» с оплатой за конверсии и ограничением CPA.
Алярма: если коллтрекинг не настроен (важно для срочного спроса и B2B) → Фаза 3 заблокирована, предупреждение до запуска.
[GATE: маркетолог] подтверждает стратегию по каждой кампании.
Шаг 10. Заливка через MCP + финальные артефакты
10А. Финальный чек-лист готовности
Перед заливкой пройдись по ВСЕМ артефактам:
✅ 00_brief.md
✅ 01_masks.json
✅ 02_frequency.json
✅ 03_semantics_raw.csv
✅ 04_keys_search_obligatory.csv (+ keys_search_vch.csv если применимо)
✅ 04_keys_rsya.csv (если есть РСЯ)
✅ 05_campaign_structure.json
✅ 06_negative_keywords.json
✅ 07_metrika_goals.json
✅ 08_creatives.json
✅ 09_bidding_strategy.json
✅ region_ids в 05_campaign_structure.json (Use case 4 в mcp-account-integration.md)
Хоть один артефакт отсутствует — не запускай заливку. Вернись на соответствующий шаг.
10Б. Заливка через MCP
Полная последовательность — references/mcp-account-integration.md, Use case 5. Здесь только каркас, не дублируй логику.
MCP заливает всю ЕПК целиком: оболочку кампании (campaigns_add с campaign_type: "UNIFIED"), группу (adgroups_add с group_type: "UNIFIED"), комбинаторное объявление (ads_add_responsive), быстрые ссылки, уточнения, отображаемую ссылку, ключи, ставки и корректировки.
- Pre-flight:
python -m scripts.preflight --workspace <path>. Есть ошибки — заливка не стартует. Среда не запускает код — ручная сверка по references/yandex-direct-specs.md (см. ветку в Шаге 8) плюс пометка о пропуске; блокирующая роль гейта сохраняется.
- Предпросмотр: весь конвейер с
dry_run: true — инструменты вернут тела запросов, ничего не создавая, но выполнив все проверки. Покажи маркетологу сводку и дождись «ОК».
- Заливка по порядку: ассеты (картинки → быстрые ссылки → уточнения) → кампания → группа → объявление → ключи → ставки → корректировки. ID каждого объекта пиши в
10_launch_log.md сразу, а не в конце: при обрыве заливка продолжается с места, повторный campaigns_add создаст дубль. ⚠️ Но 19-значные ID сейчас приходят от MCP округлёнными (references/yandex-direct-mcp.md → «Конверт ответа»), поэтому идемпотентность по записанному ID ненадёжна: при обрыве и повторном проходе проверяй, что уже создано, через campaigns_get по имени/дате, а не полагайся только на ID из лога. Убрать эту оговорку после фикса коннектора (TASK-mcp-connector-fixes.md, Баг 1).
- Проверяй ответы целиком. Ответ может быть
success: true и при этом содержать отклонённые объекты — «вернулось без ошибки» не значит «всё создано».
⚠️ На хостовом MCP картинки не заливаются. adimages_add принимает только file_path на диске сервера, а файлы маркетолога хосту недоступны; URL-параметра в схеме нет (сверено 26.08.2026, MCP 0.5.0). Поэтому: объявление заливается без image_hashes, а добавление картинок уходит в 10_launch_log.md списком ручной работы (интерфейс Директа или Коммандер). Появится URL-параметр — вернуть сюда ветку загрузки по ссылке. Остальная цепочка на хостовом MCP работает как обычно.
Кампании остаются в DRAFT.
Что MCP не умеет — уходит в 10_launch_log.md честным списком: автотаргетинг (в ЕПК на Поиске он обязателен!), Библиотека минус-фраз при переполнении лимита кампании, пакетная стратегия, временной таргетинг, кнопка действия/цена/промоакция/карусель, видео, условия ретаргетинга. Полный перечень — в references/yandex-direct-mcp.md → «Чего MCP не умеет».
Фолбек — Директ Коммандер. Если MCP не подключён и scripts/setup_yandex_direct_mcp.py не помог, либо маркетологу нужен визуальный ревью структуры до отправки: импорт ads.xlsx/keywords.xlsx Шага 8 по references/direct-commander-import.md.
10В. Финальные артефакты для маркетолога
После заливки:
python -m scripts.generate_media_plan --workspace <path> → media_plan.docx (агрегирует все артефакты пайплайна)
python -m scripts.generate_ads_xlsx --workspace <path> → ads.xlsx + keywords.xlsx + warnings.txt
10_launch_log.md — что создано, что не получилось залить через MCP, что доделать руками
Если среда не запускает код — оба генератора пропускаются: медиаплан собери прозой прямо в media_plan.md по тем же артефактам, таблицу объявлений — таблицей Markdown в ads.md. Пометка: «пропущено: нет запуска кода — media_plan.docx и ads.xlsx не собраны, вместо них .md. Как добрать: прогнать scripts/generate_media_plan.py и scripts/generate_ads_xlsx.py в среде с Python». Для импорта в Директ Коммандер нужен именно xlsx или csv — без запуска кода этот путь фолбека закрыт, скажи об этом прямо.
Обязательный раздел 10_launch_log.md — «Пропущено из-за среды». Собери в него все пометки о пропуске со всех шагов одним списком: какой шаг, какой способности не было, что сделано вместо, что недобрано, что делать человеку. Пусто — напиши «пропусков нет, все шаги выполнены полностью». Этот раздел маркетолог читает до активации кампании: он показывает, на каких данных построена кампания, а на каких — нет.
Покажи файлы пользователю тем способом, который есть в среде (например, computer://-ссылками): Media plan, Ads, Keywords, Launch log. Способа показать нет — перечисли пути к файлам от корня рабочей папки.
КРИТИЧНО: ИИ НИКОГДА не активирует кампании сам
Кампании остаются в DRAFT. Финальный клик «Активировать» (campaigns_resume) делает только маркетолог в интерфейсе Директа.
Активация = реальный расход бюджета. Нужен последний человеческий чек: посадочные открываются, Метрика работает, коллтрекинг подключён, бюджеты налиты, ОРД-маркировка включена.
Стиль работы
- Не клянчи. Один прямой вопрос за раз. В Шаге 0 — единый блок брифа.
- Не вываливай простыни. Артефакт — в файл, сводка в чат 5-10 строк.
- Гипотеза > пустой вопрос. «Вот моя версия — согласны?»
- Защищай качество на гейтах. Если reference сказал «алярма — нет Метрики на сайте» — не закрывай это «ой ладно, как-нибудь без неё».
- Бюджет важен — предупреди при <30-50к ₽/мес.
- Не выдумывай метрики и УТП. «Не знаю» лучше выдуманного.
- Пропуск всегда виден. Шаг, выполненный без необязательной способности среды, получает пометку о пропуске в свой артефакт (формат — в «Что нужно от среды»), а на гейте ты говоришь об этом словами. Молча упрощённый результат — хуже честно недобранного.
- References обязательны. На шагах с пометкой «прочти
references/<name>.md целиком» — это не намёк, а обязательное чтение.
Возобновление
«Продолжаем по Директу» → найди direct-campaigns/*/, прочитай _state.json, продолжай с того места. Не начинай сначала. Кабинет Директа (direct_client_login) читай из _state.json и не спрашивай заново — Шаг 0.5 уже пройден. Если кампания уже залита — этот скилл закончил работу; дальнейшие изменения — другая задача.
Карта артефактов (связи между шагами)
00_brief.md ──┬─→ Шаг 1 (УТП → сужающие, продукт)
├─→ Шаг 2 (бюджет, регион)
├─→ Шаг 4 (тип ниши, каналы)
├─→ Шаг 7 (URL, тип конверсии)
├─→ Шаг 8 (УТП → заголовки)
└─→ Шаг 9 (CPA, коллтрекинг)
01_masks.json ──→ Шаг 2 (прогноз CPC через MCP)
└─→ Шаг 3 (seed-фразы для Wordstat API)
02_frequency.json ──→ Шаг 4 (минимальный порог)
└─→ Шаг 9 (целевой CPC)
03_semantics_raw.csv ──→ Шаг 4 (кластеризация)
04_keys_*.csv ──→ Шаг 5 (группировка по кампаниям)
└─→ Шаг 6 (контекст для минусов)
05_campaign_structure.json ──→ Шаг 6 (кросс-минусы)
├─→ Шаг 7 (привязка целей)
├─→ Шаг 8 (распределение по группам)
├─→ Шаг 9 (стратегия на кампанию)
└─→ Шаг 10 (заливка)
06_negative_keywords.json ──→ Шаг 10 (3 уровня минусов)
07_metrika_goals.json ──→ Шаг 9 (goal_id для Фазы 3)
└─→ Шаг 10 (counter_id + goal_ids в кампаниях)
08_creatives.json ──→ Шаг 10 (заливка комбинаторного объявления через MCP: ads_add_responsive)
09_bidding_strategy.json ──→ Шаг 10 (стратегия + триггеры)
При сбое любого шага — проверь, что у него есть все нужные входы. Нет входа — возвращайся, закрой пробел, потом продолжай.
Субагенты (слой сбора тяжёлых данных)
| Субагент |
Шаги |
Что делает |
Что возвращает |
semantics |
3–4 |
расширение семантики (скрипт Cloud API wordstat_api --mode semantics либо комбинаторика масок) + пакетный пробив частотностей через MCP yandex-wordstat (wordstat_shows_batch) → кластеризация по wordstat-filter.md на 4 CSV |
сводку ≤20 строк + 03_semantics_raw.csv + 04_keys_*.csv + 04_wordstat_filter_summary.md |
Инструкция — subagents/semantics.md (файл-инструкция, не SKILL.md). Запускается инструментом субагентов/форка среды (например, Task с subagent_type: general-purpose, набор тулов Bash Read Write Grep Glob); читает единые references/ и scripts/ по пути от корня скилла. Если дочерние агенты недоступны — оркестратор выполняет Шаги 3-4 инлайн по тем же reference/scripts (см. ветку в Шаге 3).