Пакет для Яндекс Директ
yandex-direct-manager — скилл, который проводит от брифа до новой рекламной кампании в Яндекс Директе. ИИ-агент собирает семантику, строит структуру, готовит минус-слова и объявления, проектирует цели Метрики и стратегию торгов, а затем создаёт доступную часть кампании в черновике.
Активация всегда остаётся за человеком. Скилл не включает рекламу и не начинает расходовать бюджет.
Что делает пакет
Пакет берёт на себя трудоёмкую подготовку новой кампании:
- собирает и проверяет маски в Вордстате;
- оценивает необходимую частотность и цену клика;
- собирает и кластеризует ключевые фразы;
- строит структуру кампаний и групп;
- готовит минус-слова и кросс-минусацию;
- проектирует цели Метрики;
- пишет объявления по ограничениям Директа;
- предлагает стратегию торгов по фазам;
- создаёт кампанию в черновике через MCP: оболочку, группу, комбинаторное объявление, быстрые ссылки, уточнения, фразы и ставки;
- собирает медиаплан и таблицу объявлений, а при недоступном MCP — файлы для загрузки через Директ Коммандер.
Фокус пакета — создание новой кампании. Исследование рынка, выбор рекламного канала и оптимизация уже работающих кампаний в него не входят.
Как проходит работа
Скилл создаёт папку direct-campaigns/<имя-проекта>/. Результат каждого шага сохраняется в отдельный файл и становится входом для следующего. На важных развилках агент показывает решение и ждёт подтверждения.
- Бриф. Продукт, сайт, регион, бюджет, тип запросов, УТП, цели, целевая стоимость обращения, коллтрекинг и материалы.
- Маски. Матрица сужающих и общих слов, синонимы и товарозаменители; перспективные сочетания проверяются в Вордстате.
- Прогноз частотности. Три сценария по необходимому объёму семантики и цене клика с обязательной пометкой источника данных.
- Сбор семантики. Рекурсивный сбор запросов из Вордстата с ограничениями по времени и числу обращений.
- Кластеризация. Распределение фраз по частотности и каналам Поиск/РСЯ.
- Структура кампаний. Единая перформанс-кампания (классические текстово-графические кампании заморожены площадкой с 30.06.2026); разбиение по группам и углам позиционирования.
- Минус-слова. Минусация на уровне аккаунта и кампаний, а также кросс-минусация между кампаниями.
- Метрика и цели. Проверка счётчика, разбор существующих целей и проектирование набора конверсий.
- Объявления. Заголовки, тексты и расширения по ограничениям Директа и требованиям модерации.
- Визуалы. Техническое задание на изображения для РСЯ и комбинаторных объявлений; сами изображения добавляются вручную.
- Стратегия торгов. Переход от сбора статистики к оптимизации по конверсиям после накопления данных.
- Загрузка в черновик. Проверка готовности, создание поддерживаемых сущностей и список того, что нужно завершить вручную.
Что входит в пакет
Сбор семантики
Отдельный рабочий поток subagents/semantics.md выполняет сбор и кластеризацию, чтобы тысячи фраз не заполняли основной диалог. Если среда не поддерживает отдельные рабочие потоки, агент выполняет те же шаги в основном разговоре.
Скрипты
| Скрипт | Назначение |
|---|
wordstat_api.py | проверка масок и сбор семантики из Вордстата |
forecast_cpc.py | оценка цены клика по данным аукциона для фраз, уже заведённых в аккаунте |
keyword_helper.py | операторы соответствия, удаление дублей и базовые минус-листы |
preflight.py | проверка объявлений против ограничений Директа перед загрузкой |
generate_ads_xlsx.py | таблица объявлений и ключей для маркетолога и для Директ Коммандера |
generate_media_plan.py | итоговый медиаплан |
setup_yandex_direct_mcp.py | подключение MCP-сервера к настольному агенту |
Если библиотек для XLSX и DOCX нет, генераторы сохраняют CSV и Markdown.
Справочники
В references/ лежат методики по брифу, маскам, частотности, фильтрации семантики, структуре кампаний, минус-словам, целям Метрики, объявлениям, визуалам РСЯ, стратегиям торгов и работе через API.
Что делает агент, а что остаётся человеку
Агент:
- собирает семантику и оценивает CPC по доступным данным;
- кластеризует ключи и строит структуру;
- готовит минус-слова, цели, объявления и стратегию торгов;
- создаёт поддерживаемые сущности в черновике;
- собирает медиаплан и файлы для ручной загрузки.
Человек:
- подтверждает бриф, маски, прогноз, структуру, минус-слова, цели, объявления и стратегию;
- устанавливает счётчик Метрики и коллтрекинг;
- добавляет изображения и недоступные через MCP настройки;
- передаёт токены доступа;
- проверяет кампанию и вручную активирует показы.
Ограничения
- Пакет не ведёт и не оптимизирует работающие кампании.
- Он не выбирает рекламный канал и не разрабатывает стратегию бренда.
- Он не проводит исследование конкурентов, не строит портреты аудитории и не проверяет посадочную страницу как отдельную задачу.
- Без доступа к Вордстату данные о частотности помечаются как непроверенные.
- Визуалы РСЯ и комбинаторных объявлений готовятся в виде технического задания.
- Стратегию торгов, привязку целей Метрики, быстрые ссылки, уточнения и часть форматов может потребоваться завершить вручную — это зависит от подключённого MCP-сервера.
- Офлайн-конверсии из CRM и коллтрекинга требуют отдельной интеграции.
- Скилл работает на русском языке.
Требования
Обязательно:
- ИИ-агент, который умеет работать с файлами проекта;
- аккаунт в Яндекс Директе.
Для вспомогательных скриптов нужен Python 3.9 или новее.
Необязательно:
- ключ Yandex Cloud Search API для автоматического сбора семантики;
- OAuth-токен Яндекс Директа для загрузки через API;
- OAuth-токен Яндекс Метрики для создания целей;
- MCP-сервер
yandex-direct-mcp.
Без ключей пакет сохраняет готовые файлы для ручной работы через Директ Коммандер и интерфейс Директа.
Установка
Клонирование
git clone https://github.com/ai-hub-open/yandex-direct-manager.git
cd yandex-direct-manager
python install.py
install.py проверит версию Python, поставит зависимости и прогонит самопроверку модулей; при проблеме скажет, что именно чинить. Альтернативы: готовый архив yandex-direct-manager.skill из релизов (распакуйте и запустите python install.py внутри) или Code → Download ZIP.
В пакете один файл SKILL.md — в корне. subagents/semantics.md — вспомогательная инструкция; не переименовывайте её в SKILL.md.
Claude Code
# macOS / Linux
cp -r yandex-direct-manager ~/.claude/skills/
# Windows PowerShell
Copy-Item -Recurse yandex-direct-manager "$env:USERPROFILE\.claude\skills\"
После перезапуска агента напишите: «Сделай рекламную кампанию в Яндекс Директе».
Среда с загрузкой скиллов
- Упакуйте папку
yandex-direct-manager в ZIP.
- Загрузите архив в разделе скиллов.
- Убедитесь, что пакет включён.
Среда без отдельной функции скиллов
Добавьте содержимое SKILL.md в инструкции проекта и загрузите файлы из references/ и assets/. Если среда не может запускать локальные скрипты, выполняйте предложенные команды вручную и возвращайте результат в диалог.
Ключи и доступы
Создайте .env из шаблона:
cp .env.example .env
| Переменная | Назначение |
|---|
WORDSTAT_API_KEY | доступ к Yandex Cloud Search API |
WORDSTAT_FOLDER_ID | идентификатор каталога Yandex Cloud |
YANDEX_DIRECT_TOKEN | доступ к API Яндекс Директа |
Файл .env находится в .gitignore. Не добавляйте его в репозиторий и не передавайте вместе с результатами кампании.
Проверка подключения к Вордстату:
python -m scripts.wordstat_api --check
Необязательные зависимости
Ставятся автоматически при python install.py; вручную:
pip install -r requirements.txt
- без
openpyxl таблица объявлений сохраняется в CSV;
- без
python-docx медиаплан сохраняется в Markdown.
Безопасность
- секреты хранятся только в
.env или переменных окружения;
- рабочая папка
direct-campaigns/ исключена из Git;
- начинайте проверку API в песочнице;
- перед запуском проверьте сайт, Метрику, коллтрекинг, бюджет и маркировку рекламы;
- активация кампании выполняется только вручную.
Частые вопросы
Нужны ли Python и API-ключи?
Нет. Без них пакет работает в ручном режиме и готовит файлы для загрузки через Директ Коммандер.
Почему кампания не запустилась после загрузки?
Так задумано: она остаётся выключенной. Проверьте настройки и активируйте её вручную.
Агент не видит файл из references/.
В среде с доступом к папке он прочитает файл сам. В другой среде загрузите справочники в проект или передайте нужный файл в диалог.