# Yandex Direct

> Реклама в Яндекс Директе через официальный API v5: статистика и конверсии, аудит, кампании, группы, объявления, фразы, ставки, минус-фразы, цели, ретаргетинг по сегментам Метрики, фиды и товарные кампании, выгрузки и превью для согласования. Токен живёт в ~/.claude/secrets/yandex-direct-app.json, Direct API v5 работает через POST и Authorization: Bearer. Triggers: yandex-direct, директ, яндекс директ, реклама в директе, ЕПК, ставки, РСЯ.

- Skill: `atomachinskiy/yandex-direct` (Agent Skill, multi-file: 114 files)
- Install (CLI): `npx skillmds@latest add atomachinskiy/yandex-direct`
- Raw SKILL.md: https://api.skillmd.com/api/skills/atomachinskiy/yandex-direct/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: atomachinskiy (https://skillmd.com/u/atomachinskiy)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/atomachinskiy/yandex-direct

---


## Доступ и токен

Директу нужен свой токен: общий токен пака (`yandex-app.json`) к его API не подходит.

```bash
bash scripts/direct-oauth-flow.sh          # мастер: браузер, «Разрешить», токен в секреты
bash scripts/direct-oauth-flow.sh --status # что лежит сейчас
bash scripts/probe.sh                      # быстрая проверка доступа без Python
```

Токен читается в таком порядке: переменная `YANDEX_DIRECT_TOKEN`, затем `config/.env`,
затем файл `~/.claude/secrets/yandex-direct-app.json` (поле `access_token`). Путь к файлу
переопределяется через `YANDEX_DIRECT_TOKEN_FILE`. Отдельный кабинет задаётся флагом
`--account`, переменной `YANDEX_DIRECT_ACCOUNT` или, для совместимости с прежними
установками пака, `YANDEX_DIRECT_CLIENT_LOGIN`.

Как устроен доступ, почему `Bearer` вместо `OAuth`, чем обычный кабинет отличается от
агентского, что значат коды 53, 58, 8000 и 8800 и сколько запрос стоит в баллах:
[references/ОСНОВЫ.md](references/ОСНОВЫ.md). Читать до того, как чинить ошибку наугад.

Команды на Python запускаются как `python3 scripts/<команда>.py`, сторонних библиотек нет.
Проверено на Python 3.12; синтаксически код совместим с 3.9, то есть заводится и на
системном питоне macOS.

## Лёгкий контур без Python

Часть команд написана на shell и работает там, где Python недоступен или нужен быстрый
ответ: `probe.sh` (доступ), `campaigns.sh`, `ads.sh`, `adgroups.sh`, `keywords.sh`,
`bids.sh`, `report.sh` (чтение), `direct-oauth-flow.sh` и `direct-oauth-flow.ps1` (токен,
второй для Windows PowerShell).

Только в shell-контуре живут: `ord-documents.sh` (маркировка ОРД и erid),
`forecast.sh` (прогноз бюджета), `vcards.sh` (визитки), `change-states.sh` (история
изменений в кабинете), `negative-keywords.sh` (библиотечные наборы минус-фраз),
`audience-targets.sh` и `bid-modifiers.sh` (чтение условий и корректировок).

Для всего остального у Python-команд шире охват и есть сухой прогон: предпочитай их.

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

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

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

Все пути ниже относятся к каталогу этого файла. Параметры конкретной команды
доступны через `--help`.

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

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

```bash
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. Определи, что считать результатом

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

```bash
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% | Как часто на показанное объявление нажимают? |
| CPC | расход / клики | Сколько стоит один клик? |
| CR цели | конверсии цели / клики × 100% | Какова конверсия кликов в выбранное действие? |
| CPA цели | расход / конверсии цели | Сколько стоит одно такое действие? |
| CPM | расход / показы × 1000 | Сколько стоит тысяча показов? |
| ROAS | доход от выбранной цели / расход × 100% | Как соотносятся приписанный рекламе доход и расход? |
| Изменение, % | (новое − прежнее) / прежнее × 100% | Насколько изменился показатель относительно прошлого? |
| Изменение доли, п.п. | новая доля в % − прежняя доля в % | На сколько процентных пунктов изменилась доля? |

Например, 1000 показов, 50 кликов, расход 1500 ₽ и 5 конверсий выбранной цели
дают CTR 5%, CPC 30 ₽, CR 10%, CPA 300 ₽. Рост CR с 5% до 10% — это +5 п.п.
или +100% относительно прежнего значения.

При нулевом знаменателе показатель не определён: покажи «нет данных для расчёта»,
а не ноль. Значения `--` и пустые ячейки не превращай в нули. Для итогов суммируй
исходные количества и расход и заново вычисляй отношение; не усредняй CPA,
CPC или CTR строк обычным средним. Средние позиции запрашивай в нужной группировке:
для их пересчёта может не хватать данных о показах, которые учитывает API.

Один визит может достичь нескольких целей. Показывай цели отдельно: сумма
конверсий не равна уникальным заявкам, сумма доходов может содержать пересечения.
ROAS не учитывает себестоимость и прочие расходы и сам по себе не доказывает прибыль.
Указывай валюту и учёт НДС; денежные поля JSON/TSV переводятся из миллионных
долей валюты, то есть 125000000 = 125 единиц. Не суммируй разные валюты.

## 5. Отдели наблюдение от решения

Объясняй ход вывода: **что видно в данных → возможная причина → чем её проверить
→ какое действие поможет → по какому показателю оценить эффект**.
Сила вывода зависит от числа наблюдений и сопоставимости условий. Одна конверсия
или короткий провал не доказывают закономерность.

Например, хорошие конверсии при слабых позициях дают повод проверить ставки,
бюджет, стратегию и ограничения. Повышение ставки уместно при приемлемой экономике,
если именно ставка ограничивает показы. При автоматической стратегии важнее
могут оказаться целевая CPA и бюджет. Рост ставки не гарантирует определённое место.

Для позиций различай среднюю позицию, объём трафика и долю показов в блоке.
Доля спецразмещения = показы `PREMIUMBLOCK` / все показы на поиске × 100%.
Это доля фактических показов, а не всех доступных аукционов. `Slot` доступен по
условию показа, но не по отдельному `Query`: не приписывай долю условия каждому
запросу. История запросов ограничена последними 180 днями; называй реальное
покрытие периода. Пример такого анализа есть в [REPORTS.md](references/REPORTS.md).

Предложения по улучшению должны соответствовать задаче пользователя.
Рекомендация сама по себе не означает разрешения изменить кампанию.

## 6. Подготовь действие и проверь результат

Для создания собери нужные данные и покажи содержание и настройки нового объекта.
Для изменения прочитай актуальное состояние и подготовь только запрошенные правки.
Покажи «объект — поле — было — станет». У создания значение «было» отсутствует.
Цена в тексте, цена товара, ставка, бюджет и сроки показов — разные параметры;
если новое значение или его смысл неизвестны, уточни их до записи.

При работе с бюджетами и перед созданием или запуском новых кампаний читай
[управление бюджетами](references/BUDGETS.md). Предлагай проверить недельный
лимит всего кабинета и установить его, если ограничения нет: это защита от
аномального расхода. Существующий лимит оцени с учётом новой рекламы;
известный отказ или согласованное исключение используй без повторного вопроса.
У новой кампании также должен быть согласованный бюджет её стратегии.
Предлагай небольшую сумму для проверки трафика и увеличение по результатам;
уже согласованный бюджет используй без самовольных изменений.
Брендовая реклама — повод обсудить исключение, а не автоматически снять лимит.
Суммы, команды, бюджеты пакета и на период — в том же справочнике.

Обычный запуск пишущей команды показывает план без изменений в кабинете.
`--apply` выполняет правку и перечитывает объект. Если пользователь уже поручил
конкретное действие, повторное подтверждение не требуется. Если просит только
проверить или предложить — представь готовые изменения для согласования.

Сохраняй неназванные поля и элементы. При обновлении списка заголовков, текстов
или изображений передавай весь итоговый список, включая сохраняемые элементы.
Проверяй связанные места, где могла остаться устаревшая информация. Механика и
примеры команд: [references/CHANGES.md](references/CHANGES.md).

После выполнения покажи «было — стало» по фактическому чтению, с полными
изменёнными текстами. Отдели проверенный успех, отказ и неизвестный исход.
При частичном успехе продолжай с установленным остатком; при обрыве связи
сначала перечитай объект, чтобы повтор не создал дубликат. Настройки могут быть
записаны, но ещё не допущены к показам: учитывай состояние и модерацию.

Команда `ads_write.py ad create/update` записывает комбинаторные `ResponsiveAd`
через API v501. Для фидов, товарных объявлений и отбора товаров сначала читай
[фиды и товарные объявления](references/FEEDS.md): `feeds.py` управляет
библиотекой фидов, `shopping.py` — объявлениями `ShoppingAd` и их фильтрами.
Проверь тип объявления и все кампании, использующие фид, перед изменением
общего источника. Смена `FeedId` требует нового объявления; снятие фильтров
расширяет отбор до всего фида.
Чтение включает `ResponsiveAdFieldNames`, иначе API может показать комплект
как `TEXT_AD`. Основные тексты старого `TextAd` готовые команды не меняют:
назови такой остаток и предложи правку в интерфейсе. Его быстрые ссылки и
уточнения можно менять через `extensions.py bind`. Создание вместо него нового
комбинаторного объявления обсуждай как отдельное изменение. В комплекте должна
осмысленно читаться любая пара «заголовок × текст».

Если в текстах или ссылках встречаются `#…#`, `{param1}` или `{param2}`, перед
проверкой, изменением и предпросмотром прочитай
[шаблоны и параметры фраз](references/TEMPLATES.md). Обращайся к справочнику
также, когда нужно подставлять ключевую фразу в объявление, вести разные фразы
на разные страницы или объединять редкие товарные запросы в общую группу.
Проверь варианты по фразам группы, запасной текст и итоговые адреса.

Для аудита содержания используй `preview.py matrix --ad ID --account LOGIN`
или импорт сохранённой выгрузки `--from-json ФАЙЛ`. Открой HTML и проверь все
изображения, включая надписи внутри них; картинки загружаются по умолчанию.
Видео просмотри целиком либо явно оставь непроверенным: миниатюра не доказывает
отсутствие устаревших сведений в ролике. Ошибки загрузки и невоспроизведённые
дополнения учитывай в выводе. Команды, сравнение до/после и границы проверки —
[references/PREVIEW.md](references/PREVIEW.md).

Для записи новой картинки в кабинет покажи пользователю сам файл и проверь
его содержание. Загрузи файл через `images.py upload`, затем передай полученный
`AdImageHash` в `--image` команды `ads_write.py ad create` или `ad update`.
Адрес картинки для предпросмотра и хеш загруженной картинки для объявления —
разные значения. После записи проверь хеш именно в целевом объявлении.
Команды и ограничения —
[загрузка изображений](references/CHANGES.md#загрузка-изображений).

При проверке или создании рекламы учитывай быстрые ссылки и уточнения.
`ads.py --ad ID` раскрывает их содержимое; для кампании или нескольких объявлений
добавь `--with-extensions`. Одних `SitelinkSetId` и ID уточнений недостаточно для
аудита текстов и адресов. `extensions.py` читает, создаёт и удаляет дополнения,
а `bind` заменяет или снимает привязки выбранных объявлений. Для правки текста
или адреса создай новый объект и замени нужную привязку, сохранив остальные;
покажи содержимое «было → станет». Порядок для новой рекламы и изменений —
[быстрые ссылки и уточнения](references/EXTENSIONS.md).

Для аудитории на основе существующего сегмента Метрики используй
`retargeting.py sources`, затем найди или создай условие Директа через
`retargeting.py list/create`. ID этого условия применяется в корректировке
ставок через `bids.py` либо в нацеливании группы через `ads_write.py`.
ID сегмента Метрики, условия Директа и привязки к группе различаются.
Команды и правила применения — [сегменты и ретаргетинг](references/RETARGETING.md).

## Команды и справочники

Все команды находятся в `scripts/`. Каждая имеет свой набор параметров:
уточняй его через `--help`, не переноси флаги соседней команды автоматически.

| Задача | Команды | Подробности |
|---|---|---|
| Кабинет и доступ | `accounts.py`, `whoami.py` | [CLIENT_LOGIN.md](references/CLIENT_LOGIN.md), [API_ACCESS.md](config/API_ACCESS.md) |
| Кампании и группы | `campaigns.py`, `adgroups.py` | [PLAYBOOK.md](references/PLAYBOOK.md) |
| Объявления и фразы | `ads.py`, `keywords.py` | [API_OBJECTS.md](references/API_OBJECTS.md) |
| Загрузка и проверка изображений | `images.py` | [CHANGES.md](references/CHANGES.md#загрузка-изображений) |
| Быстрые ссылки и уточнения | `extensions.py`, `ads.py --with-extensions` | [EXTENSIONS.md](references/EXTENSIONS.md) |
| Сегменты Метрики и ретаргетинг | `retargeting.py`, `bids.py modifier`, `ads_write.py group targets` | [RETARGETING.md](references/RETARGETING.md) |
| Статистика, цели и сравнения | `report.py` | [REPORTS.md](references/REPORTS.md) |
| Выгрузка настроек и структуры | `campaign_dump.py` | Поля и отсутствующие части перечислены в результате |
| Комплекты объявлений | `audit_combinatorial.py`, `ads_generate.py`, `preview.py` | [COMBINATORIAL_COPY.md](references/COMBINATORIAL_COPY.md), [AD_CONTENT.md](references/AD_CONTENT.md), [PREVIEW.md](references/PREVIEW.md) |
| Создание и изменения | `campaign_write.py`, `ads_write.py`, `keywords_write.py` | [CHANGES.md](references/CHANGES.md), [naming.md](references/naming.md) |
| Фиды, товарные объявления и фильтры товаров | `feeds.py`, `shopping.py` | [FEEDS.md](references/FEEDS.md) |
| Ставки и пересечения фраз | `bids.py`, `cross_negative.py` | [PLAYBOOK.md](references/PLAYBOOK.md) |
| Локальные данные | `cache.py` | Просмотр и очистка кеша без обращений к API |
| ОРД, прогноз, визитки, история изменений | `ord-documents.sh`, `forecast.sh`, `vcards.sh`, `change-states.sh` | Только в shell-контуре, см. раздел выше |

Параметры отслеживания в ссылках: [url_macros.md](references/url_macros.md).
Методы и ограничения API:
[API_MAP.md](references/API_MAP.md), [ERRORS_AND_LIMITS.md](references/ERRORS_AND_LIMITS.md).
Идеи для проверки: [hypotheses.md](references/hypotheses.md).

## Если часть задачи выполняется в интерфейсе

Рекомендация должна учитывать потребность пользователя, даже если подходящий
тип кампании или настройка не поддерживается командами скилла. Различай отсутствие
готовой команды, отсутствие метода API и отсутствие самой возможности в Директе.
Ориентиры: [UI_MAP.md](references/UI_MAP.md), [coverage.json](references/coverage.json).

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

Выполни доступную часть и явно назови оставшиеся ручные действия. Не ограничивайся
фразой «API не поддерживает» и не выдавай ручной шаг за выполненный. Общая схема
и пример создания через Мастер кампаний: [MANUAL_SETUP.md](references/MANUAL_SETUP.md).

## Как представить результат

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

Давай ссылки на обсуждаемые объекты. Название кампании в ответе или таблице
сделай ссылкой на её группы; при обсуждении настроек используй ссылку
«Настройки». После создания кампании уместны обе. Для задачи по кабинету
целиком дай ссылку на кабинет. Ссылки строятся по фактическому логину клиента
и ID кампании; названия объектов в адрес не входят. Готовые ссылки есть в выводе
команд кабинетов и кампаний. Форматы и выбор по контексту —
[ссылки на кабинет и кампанию](references/UI_MAP.md#ссылки-на-кабинет-и-кампанию).

Команды выводят краткие сводки. Если список обрезан, используй указанный файл,
`--csv` либо более узкий отбор. Не делай вывод о всём кабинете по первым строкам.
Большие JSON/TSV обрабатывай локально и прикладывай полную выгрузку, когда она нужна.
Кеш хранится в `cache/`, выборы — в `settings/`, журналы — в `logs/` и `journal/`.
Эти данные и действующий конфиг остаются локально и не публикуются в Git.