--- name: yandex-direct-manager description: Тактический пайплайн создания рекламной кампании в Яндекс.Директе через MCP — сбор семантики через Wordstat, кластеризация на НЧ/СЧ/ВЧ и Поиск/РСЯ, минусация (3 уровня + кросс), создание объявлений по лимитам Директа, настройка целей в Метрике, выбор стратегии торгов и заливка в DRAFT. Используй когда пользователь говорит «сделай РК в Директе», «собери семантику», «нужны ключи и минусы», «напиши объявления», «запусти кампанию», «залей через MCP». Не для аналитики, не для оптимизации работающих кампаний, не для стратегии бренда — только создание новой кампании от брифа до DRAFT. --- # 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//`. На этом держится весь пайплайн: каждый шаг порождает артефакт, следующий шаг его читает. - **Диалог с пользователем** — задать вопрос, получить ответ, дождаться подтверждения. Без этого не работают гейты `[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//`. Артефакты накапливаются и являются входами для следующих шагов. На ключевых шагах — гейт `[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//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 аргументы: "<регионы>" "<необходимая_частотность>" ``` **Субагент возвращает:** сводку ≤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»): 1. **Скрипт Cloud Search API** (`scripts/wordstat_api.py --mode semantics`) — единственный путь с настоящей рекурсией волнами и ассоциациями; нужен ключ `WORDSTAT_API_KEY` + `WORDSTAT_FOLDER_ID` и запуск кода. Частотности — из того же ответа. 2. **Комбинаторная генерация кандидатов** из `01_masks.json` + пакетный пробив через MCP `wordstat_shows_batch` — когда есть только MCP. 3. Список от маркетолога / выгрузка сторонним сервисом + пакетный пробив. 4. Браузерный пробив (`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//_masks_seed.txt \ --anchors-file direct-campaigns//_anchors.txt \ --regions <из брифа> \ --output direct-campaigns//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:** 1. Дедупликация ключей через `keywords_get` (Use case 2 в `mcp-account-integration.md`) 2. Прогноз 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 `: проверка лимитов комбинаторного (заголовки, тексты, длины слов, отображаемая ссылка, быстрые ссылки, уточнения, наличие файлов картинок, объём минус-фраз). Затем `python -m scripts.generate_ads_xlsx --workspace ` → 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`). Если в брифе только Поиск — шаг пропускается. Если РСЯ есть: 1. **Pre-flight:** собери `brand.json` в рабочей папке из брифа (product_name, цвета HEX, style_references). Проверь ключи: `python -m scripts.manage_credentials list`. Нет ключа openai — попроси пользователя прислать в чат и сохрани: `python -m scripts.manage_credentials set openai --key `. Ключ НИКОГДА не пишем в артефакты рабочей папки. 2. **Концепции:** добавь в `08_creatives.json` каждой группе `combined_ad.visual_concepts` (2 концепции: id A/B, type, angle, usp_on_creative — УТП из Шага 1, углы из гипотез). **[GATE: маркетолог подтверждает концепции]** 3. **Dry-run:** `python -m scripts.generate_creative_images --workspace --dry-run` → прочитай 1–2 промпта из `assets/prompts/`. 4. **Тест:** `... --concept A` → одна картинка. **[GATE: нравится? иначе — правь концепцию/шаблон и --force]** 5. **Полный прогон:** `python -m scripts.generate_creative_images --workspace ` → до 5 картинок на группу (A×3 форматов + B×2). 6. **Видео (опционально):** выбери модель по `references/replicate-models.md`, `python -m scripts.generate_creative_videos --workspace --model ` — 1 ролик 5–10 с, 16:9. Ключ replicate — как в п.1. Предупреди о стоимости до запуска. 7. **Валидация:** `python -m scripts.validate_assets --workspace ` — все ассеты должны пройти (450–5000 px, соотношения, ≤10/100 МБ). 8. **[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`), быстрые ссылки, уточнения, отображаемую ссылку, ключи, ставки и корректировки. 1. **Pre-flight:** `python -m scripts.preflight --workspace `. Есть ошибки — заливка не стартует. Среда не запускает код — ручная сверка по `references/yandex-direct-specs.md` (см. ветку в Шаге 8) плюс пометка о пропуске; блокирующая роль гейта сохраняется. 2. **Предпросмотр:** весь конвейер с `dry_run: true` — инструменты вернут тела запросов, ничего не создавая, но выполнив все проверки. Покажи маркетологу сводку и дождись «ОК». 3. **Заливка** по порядку: ассеты (картинки → быстрые ссылки → уточнения) → кампания → группа → объявление → ключи → ставки → корректировки. 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). 4. **Проверяй ответы целиком.** Ответ может быть `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В. Финальные артефакты для маркетолога После заливки: 1. `python -m scripts.generate_media_plan --workspace ` → `media_plan.docx` (агрегирует все артефакты пайплайна) 2. `python -m scripts.generate_ads_xlsx --workspace ` → `ads.xlsx` + `keywords.xlsx` + `warnings.txt` 3. `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/.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).