yandex-direct-manager

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 и продолжает с места остановки, а не начинает заново.

Цена клика всегда с пометкой источника. Порядок: историческая средняя цена клика по похожим кампаниям аккаунта (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 не нужно.

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

Подключение 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);