/yandex-direct

name: yandex-direct
description: |
  Работа с рекламой в Яндекс Директе через официальный API: анализ статистики,
  конверсий и поисковых запросов, аудит, создание и изменение кампаний,
  объявлений, фраз, ставок, условий ретаргетинга и настроек, выгрузки и предпросмотр.
  Используй для задач о рекламе Директа, ЕПК, расходах, эффективности,
  позициях в поиске, модерации, минус-фразах и управлении рекламным кабинетом.

Яндекс Директ

Скилл помогает исследовать рекламу, объяснять её результаты, готовить материалы и управлять рекламным кабинетом. Выбирай команды по задаче пользователя. Один и тот же порядок подходит для отдельного объявления, кампании и кабинета:

**Задача → нужные данные → расчёт и объяснение → действие → проверка результата.**

Все пути ниже относятся к каталогу этого файла. Запуск: `uv run scripts/…`. Также подходит `python3 scripts/…` с Python 3.11 и новее; сторонних библиотек нет. Параметры конкретной команды доступны через `--help`.

1. Определи задачу и объекты

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

uv run scripts/accounts.py --search "название или домен"
uv run scripts/accounts.py --use "логин"
uv run scripts/campaigns.py --account "логин"

Если подходят несколько объектов, покажи названия и ID и попроси выбрать. В командах указывай `--account`: это сохраняет выбранного рекламодателя при параллельной работе. Уже выбранный кабинет повторно не уточняй.

При проблемах с доступом запусти `uv run scripts/whoami.py --account "логин"`. Без `--account` эта команда проверяет кабинет из конфигурации. Команды сами читают `config/.env`; не открывай и не выводи токен в диалог. Подключение нового кабинета: [config/README.md](config/README.md).

2. Определи, что считать результатом

Для оценки конверсий сначала получи доступные цели:

uv run scripts/report.py --account "логин" --campaign 123 --list-goals

Покажи названия и ID и спроси, какие действия ценны для бизнеса. Можно выбрать одну или несколько целей. Дождись выбора перед расчётом конверсий, CPA и выводов об эффективности. Цель стратегии, первая цель в списке и показатель «все конверсии» не заменяют решение пользователя.

Передавай выбранные цели явно через `--goals ID,ID`. Если пользователь уже выбрал их для этой задачи, используй ответ без повторного вопроса. Не переноси цели другого кабинета и не заменяй недоступную цель другой молча. До выбора можно собрать показы, клики и расход с `--traffic-only`.

Для экономических рекомендаций используй известные бизнес-ограничения: допустимую стоимость результата, бюджет, маржу, регион, сроки и предложение. Если нужного ограничения нет, обозначь вывод как предварительный или уточни его. Для простого чтения настроек или правки текста выбирать конверсионные цели не нужно.

Для добавления целей в кампанию или изменения целей оптимизации читай [цели кампаний](references/GOALS.md). Цели отчёта не меняют настройки кампании. В `campaign_write.py strategy` обычные `--goal` заменяют весь список; для сохранения прежних целей используй `--add-goals`. Проверь также тип стратегии и её `GoalId`: один список целей ещё не задаёт способ оптимизации. В доступных целях часто много мусора: автособытия, промежуточные клики и дубли. Не выбирай все цели для оптимизации по умолчанию; согласуй действия, ценные для бизнеса, и проверь состав даже у режима «все ключевые цели».

3. Собери данные нужного уровня

Выбирай детализацию по вопросу. Кампания показывает общий результат; группы и объявления помогают сравнить предложения; условия показа и поисковые запросы — спрос и соответствие рекламе; площадки, устройства и периоды — различия условий.

Отчёты, поля и команды: [references/REPORTS.md](references/REPORTS.md). Настройки, статусы, стратегии и причины проблем: [references/PLAYBOOK.md](references/PLAYBOOK.md). При анализе показов, создании или перестройке групп прочитай [разбор «Мало показов»](references/PLAYBOOK.md#мало-показов-и-недостаточно-данных). Сам выявляй редкие показы и риск раздробить спрос по слишком узким группам; объясняй их пользователю, даже если он не спрашивал о статусах.

По умолчанию используй автоматическую атрибуцию `AUTO`: команда `report.py` выбирает её, если `--attribution` не задан. Если в кампании или стратегии стоит другая модель, например `LC`, объясни расхождение и предложи выбрать: отчёт по `AUTO`, по модели кампании или сравнение обеих. Уже известный выбор пользователя используй без повторного вопроса; называй модель в ответе.

Если пользователь предпочитает `AUTO`, а кампания работает по `LC`, можно отдельно предложить сменить настройку кампании. Выбор модели отчёта сам по себе не меняет кампанию и не означает поручения её изменить. Подготовь «было → станет» и действуй по обычному порядку изменений; подробности — [в практиках по атрибуции](references/PLAYBOOK.md#автоматическая-модель-атрибуции).

Для сравнения сохраняй одинаковые цели, атрибуцию, валюту, учёт НДС и отбор. Отделяй поиск от сетей и полный период от ещё не завершённого. Учитывай задержку конверсий, изменение спроса и недостаток наблюдений. Объекты без текущей статистики не теряй при сопоставлении с историей.

Команды используют локальный кеш. Если задача требует актуальных данных, добавь `--no-cache` там, где он поддерживается. Перед записью команды всегда читают свежие значения.

4. Рассчитай и объясни показатели

Для каждой выбранной цели используй её собственное число конверсий. Под «конверсиями» понимай показатель Директа для этой цели и модели атрибуции, а не число уникальных покупателей и не сумму всех действий посетителей.

| Показатель | Формула | На какой вопрос отвечает | |---|---|---| | CTR | клики / показы × 100% | Как часто