Community Скиллы Российские сервисы

Менеджер Яндекс Директа

Универсальное

Установка

git clone (см. README)

Описание

yandex-direct-manager — скилл полного цикла для Яндекс Директа: старт — бриф с целями и бюджетом, семантика — подбор и кластеризация запросов, минус-слова — чистка нецелевого трафика, объявления и структура кампании — готовый черновик для переноса в кабинет Директа. Ведёт кампанию от формулировки задачи до состояния «осталось нажать запуск». Для маркетологов и владельцев бизнеса, осваивающих контекстную рекламу с ИИ.

Что умеет:
— собирать семантику и минус-слова;
— строить структуру кампании;
— писать объявления под Директ;
— готовить черновик к запуску.

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

yandex-direct-manager

Скилл превращает ИИ-агента в директолога: агент собирает ключевые слова, подбирает минус-слова, пишет объявления, задаёт стратегию торгов и ставку по реальному аукциону, а затем создаёт кампанию в кабинете Яндекс Директа.

Термины, которые дальше используются как рабочие:

скилл — папка с инструкциями и скриптами, по которым агент выполняет работу маркетолога; агентная среда подключает её к себе и исполняет по шагам;
агентная среда — программа, в которой работает агент: Claude Code, Claude Desktop, Cursor, ChatGPT и другие;
MCP — подключение агента к API рекламной системы. Через MCP скилл проверяет частотность в Вордстате, читает счётчик и заводит цели в Метрике и создаёт кампанию в Директе.

Факты и числа в этом файле сверены с релизом 0.17.1 от 06.10.2026; состав шагов и артефактов до версии 1.0 может меняться (см. CHANGELOG.md).

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

Что делает: маршрут этапов

Скилл создаёт рабочую папку direct-campaigns/<slug>/. Каждый шаг пишет в неё артефакт, и этот артефакт становится входом следующего шага — поэтому маршрут переживает обрыв сессии: агент читает _state.json и продолжает с места остановки, а не начинает заново.

Шаг	Что делает агент	Артефакты
0. Бриф	11 вопросов одним блоком (имя проекта скилл придумывает сам): продукт, целевая аудитория, посадочная страница, регион, бюджет, каналы, УТП и сужающие слова, цель в Метрике, целевая стоимость обращения, лицензируемая тематика. Стоп-поля (что рекламируем, посадочная, регион, бюджет, цель, тематика) скилл не подставляет сам: переспрашивает, а без ответа ставит блокер	`00_brief.md`
0.5. Разведка аккаунта	Три подпункта подряд, одна сводка и один гейт в конце. Кабинет: `accounts_get` на всех серверах Директа, выбранный логин подставляется в каждый вызов. Метрика: счётчик ищется от кампаний кабинета (`CounterIds`) на всех серверах Метрики, связка «кабинет ↔ счётчик» (🟢/🟡/🔴) проверяется до отчётов; данные сайта — реальные поисковые фразы, CPC/CPA прошлой рекламы, гео и устройства с конверсией. История каналов: что прошлая реклама реально дала по каналам и типам кампаний — файл от `yandex-direct-audit` или со слов клиента; черновики без показов — с вопросом «почему не запустили»; выводы всегда с числами и порогами	`_channel_history.md`, `_state.json`
1. Маски	Две колонки — сужающие слова × общие и товарозаменители; частотность масок одним пакетным вызовом Вордстата	`01_masks_matrix.md`, `01_masks.json`
2. Прогноз	Необходимая частотность под бюджет в трёх сценариях и оценка цены клика	`02_frequency.md`, `02_frequency.json`
3. Семантика	Расширение ядра и пакетная проверка частотностей; выполняется в отдельном субагенте, чтобы тысячи фраз не вытеснили из контекста решения шагов 0–2	`03_semantics_raw.csv`
4. Кластеризация	Пороги НЧ < 350, СЧ 350–750, ВЧ > 750 показов в месяц и распределение по Поиску и РСЯ	`04_keys_*.csv`
5. Структура	Один угол, сегмент или лендинг — одна кампания ЕПК: Поиск, РСЯ, Галерея и Карты обслуживает одна кампания. Здесь же осознанно задаются категории и бренды автотаргетинга — при заливке MCP применяет их сам	`05_campaign_structure.json`
6. Минус-слова	Три уровня минус-слов и матрица кросс-минусации — чтобы кампании не перекупали друг у друга один и тот же запрос	`06_*.csv`, `06_negative_keywords.json`
7. Цели Метрики	Аудит целей по факту срабатываний за 30 дней (мёртвые, мусорные, пригодные + конверсий в неделю), план целей и сегментов, предпросмотр `dry_run`, создание через MCP Метрики; фолбек — Management API или инструкция для интерфейса	`07_metrika_goals.json`
8. Объявления	Комбинаторное объявление: 3–7 заголовков (≤ 56 символов), 2–3 текста (≤ 81), быстрые ссылки, уточнения, отображаемая ссылка; проверка лимитов до загрузки	`08_creatives.json`, `ads.xlsx`
8.5. Визуалы	Сначала приём файлов или публичных ссылок от маркетолога, затем генерация; ассеты проверяются под техтребования Директа	`assets/images/*`, `assets/validation_report.json`
9. Стратегия торгов	Три фазы с триггерами переключения; каждая фаза описана параметрами API, а не прозой	`09_bidding_strategy.json`
10. Создание кампании	Финальная проверка (кабинет, кампания, посадочная, бюджет, цель Метрики, минус-слова, юридические риски на лендинге), предпросмотр `dry_run` и только после «ОК» — создание кампании, группы, объявления, ключей, ставок и корректировок в статусе черновика; медиаплан и итоговый отчёт: что сделано самим скиллом, на каких данных, что проверить руками	`10_launch_log.md`, `media_plan.docx`

Цена клика всегда с пометкой источника. Порядок: историческая средняя цена клика по похожим кампаниям аккаунта (report_campaign) → фактический CPA по типу кампании из истории каналов → фактические CPC/CPA прошлой рекламы из Метрики → живой аукцион по ключам аккаунта (keywordbids_get) → прогноз по маскам (forecast_bids) → справочник цены клика по нишам → значение от маркетолога. Берётся первый доступный источник, и он записывается в 02_frequency.json полями cpc_source и cpc_source_details. Сам агент цену клика у маркетолога не спрашивает и не прикидывает: непробитая частотность помечается frequency: n/a, а не заполняется правдоподобным числом.

Картинки РСЯ попадают в объявление автоматически — с версии 0.13.0. Локальный файл публикуется во временном хранилище, Директ скачивает его по публичной ссылке (adimages_add с image_url) и возвращает хеш, хеш уходит в объявление. Ссылка живёт не дольше двух часов, и это не мешает: Директ сохраняет картинку у себя в момент вызова. Картинку, которую маркетолог дал публичной ссылкой сразу, хранилище не трогает. Нет ни хранилища, ни запуска кода — объявление создаётся без картинок, а они уходят в список ручной работы.

Откуда берутся картинки (с 0.20.1): свои картинки маркетолога → инструмент create_ad_image, если он есть в среде (так на платформе AI Hub: по картинке за вызов, сразу в формате Директа, без текста на изображении, ключ не нужен) → скрипт через OpenAI с ключом → ТЗ дизайнеру. Где adimages_add принимает путь к файлу (платформа), картинка уходит в Директ по пути, без хранилища и токена click.ru. Если create_ad_image дважды вернул ошибку, агент называет причину и предлагает только варианты про картинки.

Чего агент не делает — и говорит об этом прямо (с 0.20.2). Удалить, запустить, снять с паузы, отправить на модерацию, изменить кабинет, который вы не выбрали, — на такую просьбу агент отвечает «нет, у меня нет прав на …», говорит, где это сделать руками, предлагает замену, если она есть, и ждёт вашего ответа. К прежнему плану сам не возвращается.

Точки контроля. Бриф, семантика, структура, минус-слова, объявления, ставки и само создание кампании в кабинете. На каждой агент показывает решение и ждёт явного подтверждения. Шаг, выполненный без необязательной способности среды, получает пометку о пропуске — что не добрано и как это добрать, — и все такие пометки сводятся в 10_launch_log.md одним списком.

Установка

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

В сессии Claude Code:

/plugin marketplace add ai-hub-open/claude-plugins
/plugin install yandex-direct-manager@ai-hub-open

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

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

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

git clone https://github.com/ai-hub-open/yandex-direct-manager.git
cd yandex-direct-manager
python install.py

install.py проверяет версию Python, ставит зависимости из requirements.txt и прогоняет импорт модулей; запускать повторно безопасно. Альтернативы: архив yandex-direct-manager.skill из релизов — распаковать и запустить python install.py внутри — или Code → Download ZIP.

Дальше папка кладётся туда, где среда ищет скиллы:

# Claude Code, macOS / Linux
cp -r yandex-direct-manager ~/.claude/skills/

# Claude Code, Windows PowerShell
Copy-Item -Recurse yandex-direct-manager "$env:USERPROFILE\.claude\skills\"

Среда с загрузкой скиллов архивом: упаковать папку в ZIP (./package.sh соберёт .skill — это тот же ZIP), загрузить в разделе скиллов, включить в списке. Среда без отдельной функции скиллов: содержимое SKILL.md идёт в инструкции проекта, файлы references/ и assets/ загружаются рядом; если среда не запускает локальные скрипты, агент отдаёт команды текстом и работает с присланным выводом.

В пакете один SKILL.md — в корне. subagents/semantics.md — вспомогательная инструкция для субагента, переименовывать её в SKILL.md не нужно.

Путь	Содержимое
`SKILL.md`	маршрут: 10 шагов, точки контроля, матрица способностей среды
`references/`	20 справочников: пороги, формулы, лимиты площадки, контракты MCP
`subagents/`	отдельный поток сбора и кластеризации семантики
`scripts/`	сбор семантики, оценка цены клика, проверка лимитов, генерация материалов и таблиц
`docs/`	подключение MCP и хранилища картинок

Справочники открываются целиком до установки — по ним видно, на каких порогах и формулах работает маршрут.

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

Скиллу нужны подключения к Яндекс Директу, Вордстату и Метрике. Все открывает один API-токен из профиля click.ru (https://click.ru/userinfo.html → «API Token»); аккаунт Директа должен быть подключён в click.ru, аккаунт Яндекса с Метрикой — в интеграциях click.ru (https://help.click.ru/97#connect-yandex-metrica).

python -m scripts.setup_yandex_direct_mcp --token <CLICK_RU_TOKEN> --target all

Установщик дописывает блоки mcpServers в конфиги Cursor, Claude Code и Claude Desktop (через mcp-remote), сохраняя уже прописанные серверы, и ничего не запускает. Флаги: --target (cursor, cursor-project, claude-code, claude-desktop, all; по умолчанию cursor), --dry-run, --remove, --server.

Формы адреса:

Токена достаточно. По умолчанию (--server all) прописываются три сервера: yandex-direct, yandex-wordstat и хранилище картинок KeepImage. Токен идёт заголовком, а не в пути URL: путь попадает в логи прокси и в историю.
--client-login необязателен. Без него вызовы уходят в кабинет по умолчанию, а их на одном токене бывает несколько. Логин закрепляет за подключением один кабинет; если он не задан, выбор кабинета делается на шаге 0.5 диалогом.
Токен click.ru покрывает только кабинеты, подключённые в click.ru. Для внешнего аккаунта нужен OAuth-токен Яндекса и свой инстанс сервера в прямом режиме — там же, в отличие от режима click.ru, работает forecast_bids и доступна песочница.

Метрика установщиком пока не прописывается — её добавляют коннектором по адресу (в Claude Desktop / claude.ai: «Настройки → Коннекторы → Добавить свой коннектор»). Токен — в самом адресе:

https://metrika-mcp.aihub.click.ru/c/<API-токен click.ru> — через click.ru, все подключённые аккаунты Яндекса с Метрикой;
https://metrika-mcp.aihub.click.ru/c/<API-токен click.ru>/<аккаунт> — через click.ru, один аккаунт (логин или ID интеграции Метрики в click.ru);
https://metrika-mcp.aihub.click.ru/y/<OAuth-токен Яндекса> — напрямую в Яндекс, без click.ru.

Адрес с токеном равносилен паролю: не публикуйте его. Без MCP Метрики скилл работает, но номер счётчика спросит у маркетолога, а цели предложит завести вручную.

Токен отзывается в профиле click.ru в любой момент; в артефакты рабочей папки агент его не пишет — хранилище ключей лежит вне её, в ~/.yandex-direct-manager.

Проверка после подключения: перезапустить клиента и позвать accounts_get({}) — он покажет режим подключения и список кабинетов. Частотность проверяется просьбой пробить любую фразу: агент должен позвать wordstat_shows_batch. Детали заголовков, URL и форматов конфигов — в docs/hosted-mcp-setup.md, контракты инструментов — в references/yandex-direct-mcp.md.

Подключение необязательно. Без него скилл доходит до конца по ветке без живых данных: частотность — через scripts/wordstat_api.py (ключ Yandex Cloud Search API) или браузерным пробивом, цена клика — из справочника по нишам, кампания — файлами для импорта в Директ Коммандер. Каждый такой обход помечается в артефакте шага.

Запуск

Подготовьте продукт и адрес сайта, регион, бюджет, УТП и слова отстройки, цель в Метрике и целевую стоимость обращения. Затем в строке чата:

/yandex-direct-manager Собери кампанию в Яндекс Директе для <продукт>, сайт <адрес>.

Агент задаст бриф одним блоком, параллельно изучит сайт и пойдёт по этапам, останавливаясь на точках контроля. Чтобы вернуться к прерванной работе, скажите, что продолжаете эту же кампанию: агент найдёт direct-campaigns/*/, прочитает _state.json и продолжит с места остановки.

Что на выходе

Кампания в кабинете. Кампания, группа, ключевые слова, объявление, быстрые ссылки, уточнения, ставки и корректировки — созданы через MCP. Кампания остаётся черновиком: показы и расход включает маркетолог в интерфейсе Директа.
Файлы с ключевыми словами. Ключи, разложенные по частотности и каналам Поиск и РСЯ, с пометкой, почему выбраны именно эти слова.
Файл для импорта и медиаплан. ads.xlsx и keywords.xlsx для загрузки через Директ Коммандер, media_plan.docx для рекламодателя. Нет openpyxl — таблицы сохраняются в CSV, нет python-docx — медиаплан в Markdown.
Обоснование каждого шага. Матрица кросс-минусации, план целей Метрики, стратегия торгов по фазам с триггерами, источник цены клика.
10_launch_log.md. Что создано, с какими ID, что не удалось создать и что осталось доделать руками — вместе с разделом «Пропущено из-за среды». Этот файл читается до активации кампании: по нему видно, на каких данных кампания построена, а на каких нет.

Требования

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

Остальное необязательно, и у каждого пункта есть ветка «если нет»:

Что	Где нужно	Если нет
Python 3.9 или новее	скрипты шагов 1, 2, 3, 8, 10	команды выполняются вручную, вывод возвращается в диалог; теряется машинная проверка лимитов перед загрузкой
Подключения MCP к Директу и Вордстату	шаги 0.5, 1, 2, 3, 5, 8, 10	справочник цены клика, браузерный пробив частотностей, импорт через Директ Коммандер
Субагенты или форк контекста	шаги 3–4	шаги выполняются в основном контексте; тысячи ключей вытесняют решения предыдущих шагов
Чтение веб-страниц	шаг 0 (сайт), шаг 7 (счётчик Метрики)	данные со слов маркетолога, с соответствующей пометкой
Загрузка картинок в хранилище	шаг 10 (не нужна, где загрузка принимает путь к файлу)	объявление создаётся без картинок, они уходят в список ручной работы
Инструмент `create_ad_image`	шаг 8.5	картинки рисует скрипт с ключом OpenAI
Ключ генерации изображений	шаг 8.5 (если нет `create_ad_image`)	агент собирает техническое задание дизайнеру
OAuth-токен Метрики с правом записи	шаг 7	план целей готовится, цели маркетолог заводит руками

Аккаунт в Яндекс Директе нужен в любом случае. Счётчик Метрики на сайте проверяется на шаге 7: если его нет, агент останавливает маршрут и просит установить счётчик — без него автостратегиям не на чем учиться.

Ограничения

Что не заводится через API и уходит в список ручной работы. Список сверен с MCP Директа 0.5.0 (API v501, 51 инструмент), прогон живьём 14.09.2026:

Библиотека минус-фраз — общие минус-листы аккаунта не создаются, минус-слова схлопываются в минус-фразы каждой кампании;
пакетные стратегии — общий пул обучения на несколько кампаний заводится только в интерфейсе;
временной таргетинг — расписание показов и почасовые коэффициенты;
элементы объявления: кнопка действия, цена, промоакция, карусель — полей нет; скилл их проектирует на шаге 8, добавляются вручную;
видео — ads_add_responsive принимает идентификаторы видеодополнений, но создать само видео нечем, поэтому скилл видео и не генерирует: ролики маркетолога загружаются через интерфейс;
условия ретаргетинга — корректировки работают только с условиями, созданными в кабинете;
профили организаций, Турбо-страницы, товарные фиды, смарт-креативы — не создаются, готовые идентификаторы принимаются.

Границы режима click.ru. forecast_bids в этом режиме недоступен — прогноз идёт через живой аукцион или справочник. Песочницы нет: подключение всегда ведёт в production-кабинет, поэтому шаг 10 начинается с предпросмотра dry_run, который выполняет все проверки, ничего не создавая. 19-значные идентификаторы объектов приходят от коннектора округлёнными, поэтому состояние повторной загрузки сверяется через campaigns_get, а не по записанному идентификатору.

Границы площадки. В сетях ручные ставки не принимаются — Яндекс отключил ручное управление ставками в РСЯ и в кампаниях «поиск + РСЯ» в 2024 году. В ЕПК на поиске и в РСЯ стратегия задаётся на поиске, а сеть идёт за ней (NETWORK_DEFAULT); своя автостратегия в сети — только у варианта «только РСЯ», где поиск выключен. Ручные ставки на поиске выключают РСЯ. Базовая единица бюджета — неделя, минимум 300 ₽; дневной бюджет применяется только при ручных ставках на Поиске и тоже от 300 ₽.

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

Не ведёт запущенные кампании: чистка площадок РСЯ и поисковых запросов, переключение фаз стратегии — за пределами маршрута.
Не выбирает рекламный канал и не разрабатывает стратегию бренда.
Не исследует конкурентов, не строит портреты аудитории и не проверяет посадочную страницу как отдельную задачу.
Не подтягивает офлайн-конверсии из CRM и коллтрекинга — это отдельная интеграция.
Не заменяет директолога: отстройку, структуру, объявления и ставки подтверждает маркетолог.
Маршрут рассчитан на русскоязычные кампании.

Лицензируемые и запрещённые тематики проверяются на шаге 0 по факт-таблице references/ad-legal-topics.md: маршрут останавливается до сбора семантики, а не обходит проверку.

Разработка и участие

Тесты в сеть не ходят: OpenAI, KeepImage и Директ подменяются моками, реальные ключи из ~/.yandex-direct-manager не читаются.

pip install -r requirements-dev.txt
pytest

Новый скрипт в scripts/ — новый файл tests/test_<module>.py по образцу test_preflight.py: проверяется бизнес-правило, а не формулировка сообщения. Секреты живут в .env или переменных окружения; .env и рабочая папка direct-campaigns/ исключены из Git.

Вопросы и ошибки — в Issues. Лицензия — Apache-2.0.