atomachinskiy Доступ и токен
Директу нужен свой токен: общий токен пака (yandex-app.json) к его API не подходит.
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. Читать до того, как чинить ошибку наугад.
Команды на 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. Определи задачу и объекты
Выясни из запроса и предыдущих ответов, что нужно получить: сведения, оценку, предложения, новые материалы или изменения. Найди рекламодателя и нужные кампании, группы, объявления либо фразы. Для анализа задай период, для сравнения — два сопоставимых периода. Спрашивай только то, без чего нельзя правильно продолжить; разумное допущение о периоде или отборе явно назови.
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.
2. Определи, что считать результатом
Для оценки конверсий сначала получи доступные цели:
uv run scripts/report.py --account "логин" --campaign 123 --list-goals
Покажи названия и ID и спроси, какие действия ценны для бизнеса. Можно выбрать одну или несколько целей. Дождись выбора перед расчётом конверсий, CPA и выводов об эффективности. Цель стратегии, первая цель в списке и показатель «все конверсии» не заменяют решение пользователя.
Передавай выбранные цели явно через --goals ID,ID. Если пользователь уже
выбрал их для этой задачи, используй ответ без повторного вопроса. Не переноси
цели другого кабинета и не заменяй недоступную цель другой молча.
До выбора можно собрать показы, клики и расход с --traffic-only.
Для экономических рекомендаций используй известные бизнес-ограничения: допустимую стоимость результата, бюджет, маржу, регион, сроки и предложение. Если нужного ограничения нет, обозначь вывод как предварительный или уточни его. Для простого чтения настроек или правки текста выбирать конверсионные цели не нужно.
Для добавления целей в кампанию или изменения целей оптимизации читай
цели кампаний. Цели отчёта не меняют настройки кампании.
В campaign_write.py strategy обычные --goal заменяют весь список;
для сохранения прежних целей используй --add-goals. Проверь также тип
стратегии и её GoalId: один список целей ещё не задаёт способ оптимизации.
В доступных целях часто много мусора: автособытия, промежуточные клики и
дубли. Не выбирай все цели для оптимизации по умолчанию; согласуй действия,
ценные для бизнеса, и проверь состав даже у режима «все ключевые цели».
3. Собери данные нужного уровня
Выбирай детализацию по вопросу. Кампания показывает общий результат; группы и объявления помогают сравнить предложения; условия показа и поисковые запросы — спрос и соответствие рекламе; площадки, устройства и периоды — различия условий.
Отчёты, поля и команды: references/REPORTS.md. Настройки, статусы, стратегии и причины проблем: references/PLAYBOOK.md. При анализе показов, создании или перестройке групп прочитай разбор «Мало показов». Сам выявляй редкие показы и риск раздробить спрос по слишком узким группам; объясняй их пользователю, даже если он не спрашивал о статусах.
По умолчанию используй автоматическую атрибуцию AUTO: команда report.py
выбирает её, если --attribution не задан. Если в кампании или стратегии стоит
другая модель, например LC, объясни расхождение и предложи выбрать: отчёт по
AUTO, по модели кампании или сравнение обеих. Уже известный выбор пользователя
используй без повторного вопроса; называй модель в ответе.
Если пользователь предпочитает AUTO, а кампания работает по LC, можно
отдельно предложить сменить настройку кампании. Выбор модели отчёта сам по себе
не меняет кампанию и не означает поручения её изменить. Подготовь «было → станет»
и действуй по обычному порядку изменений; подробности —
в практиках по атрибуции.
Для сравнения сохраняй одинаковые цели, атрибуцию, валюту, учёт НДС и отбор. Отделяй поиск от сетей и полный период от ещё не завершённого. Учитывай задержку конверсий, изменение спроса и недостаток наблюдений. Объекты без текущей статистики не теряй при сопоставлении с историей.
Команды используют локальный кеш. Если задача требует актуальных данных,
добавь --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.
Предложения по улучшению должны соответствовать задаче пользователя. Рекомендация сама по себе не означает разрешения изменить кампанию.
6. Подготовь действие и проверь результат
Для создания собери нужные данные и покажи содержание и настройки нового объекта. Для изменения прочитай актуальное состояние и подготовь только запрошенные правки. Покажи «объект — поле — было — станет». У создания значение «было» отсутствует. Цена в тексте, цена товара, ставка, бюджет и сроки показов — разные параметры; если новое значение или его смысл неизвестны, уточни их до записи.
При работе с бюджетами и перед созданием или запуском новых кампаний читай управление бюджетами. Предлагай проверить недельный лимит всего кабинета и установить его, если ограничения нет: это защита от аномального расхода. Существующий лимит оцени с учётом новой рекламы; известный отказ или согласованное исключение используй без повторного вопроса. У новой кампании также должен быть согласованный бюджет её стратегии. Предлагай небольшую сумму для проверки трафика и увеличение по результатам; уже согласованный бюджет используй без самовольных изменений. Брендовая реклама — повод обсудить исключение, а не автоматически снять лимит. Суммы, команды, бюджеты пакета и на период — в том же справочнике.
Обычный запуск пишущей команды показывает план без изменений в кабинете.
--apply выполняет правку и перечитывает объект. Если пользователь уже поручил
конкретное действие, повторное подтверждение не требуется. Если просит только
проверить или предложить — представь готовые изменения для согласования.
Сохраняй неназванные поля и элементы. При обновлении списка заголовков, текстов или изображений передавай весь итоговый список, включая сохраняемые элементы. Проверяй связанные места, где могла остаться устаревшая информация. Механика и примеры команд: references/CHANGES.md.
После выполнения покажи «было — стало» по фактическому чтению, с полными изменёнными текстами. Отдели проверенный успех, отказ и неизвестный исход. При частичном успехе продолжай с установленным остатком; при обрыве связи сначала перечитай объект, чтобы повтор не создал дубликат. Настройки могут быть записаны, но ещё не допущены к показам: учитывай состояние и модерацию.
Команда ads_write.py ad create/update записывает комбинаторные ResponsiveAd
через API v501. Для фидов, товарных объявлений и отбора товаров сначала читай
фиды и товарные объявления: feeds.py управляет
библиотекой фидов, shopping.py — объявлениями ShoppingAd и их фильтрами.
Проверь тип объявления и все кампании, использующие фид, перед изменением
общего источника. Смена FeedId требует нового объявления; снятие фильтров
расширяет отбор до всего фида.
Чтение включает ResponsiveAdFieldNames, иначе API может показать комплект
как TEXT_AD. Основные тексты старого TextAd готовые команды не меняют:
назови такой остаток и предложи правку в интерфейсе. Его быстрые ссылки и
уточнения можно менять через extensions.py bind. Создание вместо него нового
комбинаторного объявления обсуждай как отдельное изменение. В комплекте должна
осмысленно читаться любая пара «заголовок × текст».
Если в текстах или ссылках встречаются #…#, {param1} или {param2}, перед
проверкой, изменением и предпросмотром прочитай
шаблоны и параметры фраз. Обращайся к справочнику
также, когда нужно подставлять ключевую фразу в объявление, вести разные фразы
на разные страницы или объединять редкие товарные запросы в общую группу.
Проверь варианты по фразам группы, запасной текст и итоговые адреса.
Для аудита содержания используй preview.py matrix --ad ID --account LOGIN
или импорт сохранённой выгрузки --from-json ФАЙЛ. Открой HTML и проверь все
изображения, включая надписи внутри них; картинки загружаются по умолчанию.
Видео просмотри целиком либо явно оставь непроверенным: миниатюра не доказывает
отсутствие устаревших сведений в ролике. Ошибки загрузки и невоспроизведённые
дополнения учитывай в выводе. Команды, сравнение до/после и границы проверки —
references/PREVIEW.md.
Для записи новой картинки в кабинет покажи пользователю сам файл и проверь
его содержание. Загрузи файл через images.py upload, затем передай полученный
AdImageHash в --image команды ads_write.py ad create или ad update.
Адрес картинки для предпросмотра и хеш загруженной картинки для объявления —
разные значения. После записи проверь хеш именно в целевом объявлении.
Команды и ограничения —
загрузка изображений.
При проверке или создании рекламы учитывай быстрые ссылки и уточнения.
ads.py --ad ID раскрывает их содержимое; для кампании или нескольких объявлений
добавь --with-extensions. Одних SitelinkSetId и ID уточнений недостаточно для
аудита текстов и адресов. extensions.py читает, создаёт и удаляет дополнения,
а bind заменяет или снимает привязки выбранных объявлений. Для правки текста
или адреса создай новый объект и замени нужную привязку, сохранив остальные;
покажи содержимое «было → станет». Порядок для новой рекламы и изменений —
быстрые ссылки и уточнения.
Для аудитории на основе существующего сегмента Метрики используй
retargeting.py sources, затем найди или создай условие Директа через
retargeting.py list/create. ID этого условия применяется в корректировке
ставок через bids.py либо в нацеливании группы через ads_write.py.
ID сегмента Метрики, условия Директа и привязки к группе различаются.
Команды и правила применения — сегменты и ретаргетинг.
Команды и справочники
Все команды находятся в scripts/. Каждая имеет свой набор параметров:
уточняй его через --help, не переноси флаги соседней команды автоматически.
| Задача | Команды | Подробности |
|---|---|---|
| Кабинет и доступ | accounts.py, whoami.py |
CLIENT_LOGIN.md, API_ACCESS.md |
| Кампании и группы | campaigns.py, adgroups.py |
PLAYBOOK.md |
| Объявления и фразы | ads.py, keywords.py |
API_OBJECTS.md |
| Загрузка и проверка изображений | images.py |
CHANGES.md |
| Быстрые ссылки и уточнения | extensions.py, ads.py --with-extensions |
EXTENSIONS.md |
| Сегменты Метрики и ретаргетинг | retargeting.py, bids.py modifier, ads_write.py group targets |
RETARGETING.md |
| Статистика, цели и сравнения | report.py |
REPORTS.md |
| Выгрузка настроек и структуры | campaign_dump.py |
Поля и отсутствующие части перечислены в результате |
| Комплекты объявлений | audit_combinatorial.py, ads_generate.py, preview.py |
COMBINATORIAL_COPY.md, AD_CONTENT.md, PREVIEW.md |
| Создание и изменения | campaign_write.py, ads_write.py, keywords_write.py |
CHANGES.md, naming.md |
| Фиды, товарные объявления и фильтры товаров | feeds.py, shopping.py |
FEEDS.md |
| Ставки и пересечения фраз | bids.py, cross_negative.py |
PLAYBOOK.md |
| Локальные данные | cache.py |
Просмотр и очистка кеша без обращений к API |
| ОРД, прогноз, визитки, история изменений | ord-documents.sh, forecast.sh, vcards.sh, change-states.sh |
Только в shell-контуре, см. раздел выше |
Параметры отслеживания в ссылках: url_macros.md. Методы и ограничения API: API_MAP.md, ERRORS_AND_LIMITS.md. Идеи для проверки: hypotheses.md.
Если часть задачи выполняется в интерфейсе
Рекомендация должна учитывать потребность пользователя, даже если подходящий тип кампании или настройка не поддерживается командами скилла. Различай отсутствие готовой команды, отсутствие метода API и отсутствие самой возможности в Директе. Ориентиры: UI_MAP.md, coverage.json.
Если рекомендуешь такой вариант, подготовь самостоятельную пошаговую инструкцию: куда перейти, что создать, какие данные ввести, какие ценные цели выбрать или настроить в Метрике, какой бюджет/ограничения задать и как проверить результат. Приложи готовые тексты и значения, известные из задачи. Для неизвестных значений объясни, как их определить; не подставляй случайные цели и суммы.
Выполни доступную часть и явно назови оставшиеся ручные действия. Не ограничивайся фразой «API не поддерживает» и не выдавай ручной шаг за выполненный. Общая схема и пример создания через Мастер кампаний: MANUAL_SETUP.md.
Как представить результат
Начни с ответа на вопрос пользователя. Затем дай нужные цифры или изменения, объясни основание вывода и существенное ограничение. Для отчёта назови кабинет, период, цели, атрибуцию и единицы денег. Для записи покажи до/после и фактическое состояние. Объём объяснения выбирай по сложности задачи и опыту пользователя.
Давай ссылки на обсуждаемые объекты. Название кампании в ответе или таблице сделай ссылкой на её группы; при обсуждении настроек используй ссылку «Настройки». После создания кампании уместны обе. Для задачи по кабинету целиком дай ссылку на кабинет. Ссылки строятся по фактическому логину клиента и ID кампании; названия объектов в адрес не входят. Готовые ссылки есть в выводе команд кабинетов и кампаний. Форматы и выбор по контексту — ссылки на кабинет и кампанию.
Команды выводят краткие сводки. Если список обрезан, используй указанный файл,
--csv либо более узкий отбор. Не делай вывод о всём кабинете по первым строкам.
Большие JSON/TSV обрабатывай локально и прикладывай полную выгрузку, когда она нужна.
Кеш хранится в cache/, выборы — в settings/, журналы — в logs/ и journal/.
Эти данные и действующий конфиг остаются локально и не публикуются в Git.