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

🎯 Yandex Direct Skill — AI Agent for PPC Management

The first open-source skill for managing Yandex Direct via AI agents.

v2.0 (October 2026): updated for Unified Performance Campaigns (ЕПК), combinatorial ads, weekly budgets and the current API. See Changelog.

Audit, create, optimize, and report on Yandex Direct campaigns — all through natural language commands. Built for OpenClaw and compatible AI agent frameworks.

Authors: Nick Serebrov & Kobe 🐍

✨ Features

🔍 Audit System

55 checks across 6 categories:

• Conversions & Metrika (25%) — tracking setup, goals, attribution
• Wasted Spend / Negatives (20%) — negative keywords, search query analysis
• Account Structure (15%) — campaign organization, naming, geo split
• Keywords & Autotargeting (15%) — operators, autotargeting categories, CTR vs account median
• Ads & Extensions (15%) — moderation, combinatorial ads, images, sitelinks, callouts, ad marking
• Settings & Targeting (10%) — geo, bidding strategy, bid modifiers

Scoring: weighted algorithm → 0-100 score → grade A through F.

📦 What’s Inside

├── SKILL.md                          # Main skill file (agent instructions)
├── references/
│   ├── yandex-audit.md               # 55 audit checks (YD01-YD55) with data sources
│   ├── scoring-system.md             # Weighted scoring algorithm
│   ├── benchmarks.md                 # How to compare metrics + rough market references
│   ├── bidding-strategies.md         # ЕПК strategies ↔ API, weekly budgets, bid modifiers
│   ├── compliance.md                 # FZ-38, ad marking, Russian language rules
│   └── image-specs.md                # Images and video for combinatorial ads
├── scripts/
│   ├── yd-api.sh                     # API v5/v501 wrapper (Client-Login, auto v501 routing)
│   ├── yd-report.sh                  # Reports: presets, Metrika goals, offline polling
│   └── yd-audit.sh                   # Audit data collection (chunked, paginated, 4 reports)
└── agents/
    └── audit-yandex.md               # Audit subagent instructions

🚀 Quick Start

1. Get API Access

Apply for Yandex Direct API access at direct.yandex.ru → API settings.

2. Get OAuth Token

https://oauth.yandex.ru/authorize?response_type=token&client_id=YOUR_CLIENT_ID

3. Save Credentials

cat > ~/.secrets/yandex-direct.json << 'EOF'
{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "oauth_token": "your_oauth_token",
  "client_login": "optional: client login for agency accounts"
}
EOF
chmod 600 ~/.secrets/yandex-direct.json

4. Install Skill

Clone the repository into your agent’s skills directory (requires bash, curl, jq):

# OpenClaw
git clone https://github.com/Silverov/yandex-direct-skill ~/clawd/skills/direct

# Claude Code
git clone https://github.com/Silverov/yandex-direct-skill ~/.claude/skills/direct

5. Run Audit

Tell your agent: "Run a Yandex Direct audit" — and watch the magic happen.

📊 Russian Market Benchmarks

Rough references for the Russian PPC market (no official source — the audit compares with the account’s own medians first):

Benchmarks vary by industry — see references/benchmarks.md for full data.

📝 Changelog

v2.0.2 — October 2026

• Fixed: yd-audit.sh read campaigns and ad groups from v5, where a Unified campaign looks like TEXT_CAMPAIGN without its settings — now v501 (yd-api.sh also routes such get requests there).
• Fixed: Reports API error 56 (one request per 10 s): pause between audit reports, offline reports polled every ≥ 10 s, error 56 retried.
• Fixed: sitelinks.get in the audit was rejected (error 4004: Sitelinks in FieldNames together with SitelinkFieldNames).
• Docs: the auto-generated ERIR ad description of combinatorial ads is not available in the API — check it in the web interface.

v2.0.1 — October 2026

• Clear hint when the Direct API answers an empty HTTP 204 (API turned off on Yandex’s side, e.g. the special mode after the October 2026 data-center incident) in yd-api.sh and yd-report.sh.
• yd-audit.sh suggests --include-archived when every campaign is archived.
• Mapping of the old strategy labels in the campaigns grid («Оптимизация кликов / конверсий») to API strategy types.

v2.0 — October 2026

• Fixed: yd-api.sh appended an extra } to every params argument (${3:-{}}), so no request with parameters could run.
• Fixed: audit requests rejected by the API: AdExtensionIds in TextAdFieldNames, empty SelectionCriteria for sitelinks and negative keyword sets, more than 10 CampaignIds per request; no pagination.
• Fixed: reports were not polled (retryIn is an HTTP header) and got a new name on every retry; conversions were summed over all Metrika goals — now priority goals and attribution are passed.
• New: Unified Performance Campaigns (UnifiedCampaignFieldNames, v501 routing), combinatorial ads (ResponsiveAdFieldNames), autotargeting settings, bid modifiers, callouts; Client-Login; summary.json.
• Updated: audit checklist (search/YAN split is no longer Critical, no Google-style Quality Score, combinatorial ads, Yandex Business profile instead of vCard, weekly budgets), current strategies (multi-goal, «Максимум прибыли»), bid modifier ranges, image specs, Russian language rules from 01.03.2026.
• Safety: write operations only after the user approves the exact change.

🏗 Origin Story

This skill was born in one evening. We needed to set up Yandex Direct campaigns for stepback.ru. After creating campaigns via API in 3 minutes, we found claude-ads — a great skill for Google/Meta/LinkedIn ads, but with zero Yandex support. So we built our own, ran an audit on our account (Grade D → C+), and fixed the issues on the spot.

📄 License

MIT — use it, fork it, improve it.

🎯 Яндекс Директ Скилл — AI-агент для управления рекламой

Первый open-source скилл для управления Яндекс Директом через AI-агентов.

v2.0 (октябрь 2026): обновлён под Единую перфоманс-кампанию (ЕПК), комбинаторные объявления, недельные бюджеты и текущий API. См. историю изменений.

Аудит, создание, оптимизация и отчёты по кампаниям Яндекс Директа — всё через команды на естественном языке. Создан для OpenClaw и совместимых AI-агентных фреймворков.

Авторы: Ник Серебров & Коби 🐍

✨ Возможности

🔍 Система аудита

55 проверок по 6 категориям:

• Конверсии и Метрика (25%) — настройка целей, атрибуция, трекинг
• Слив бюджета / минус-слова (20%) — минус-слова, анализ поисковых запросов
• Структура аккаунта (15%) — организация кампаний, именование, гео
• Ключевые фразы и автотаргетинг (15%) — операторы, категории автотаргетинга, CTR против медианы аккаунта
• Объявления и расширения (15%) — модерация, комбинаторные объявления, изображения, быстрые ссылки, уточнения, маркировка
• Настройки и таргетинг (10%) — гео, стратегии ставок, корректировки

Оценка: взвешенный алгоритм → балл 0-100 → грейд от A до F.

🚀 Быстрый старт

1. Получите доступ к API

Подайте заявку на доступ к API Яндекс Директа: direct.yandex.ru → Настройки API.

2. Получите OAuth-токен

https://oauth.yandex.ru/authorize?response_type=token&client_id=ВАШ_CLIENT_ID

3. Сохраните credentials

cat > ~/.secrets/yandex-direct.json << 'EOF'
{
  "client_id": "ваш_client_id",
  "client_secret": "ваш_client_secret",
  "oauth_token": "ваш_oauth_token",
  "client_login": "необязательно: логин клиента для агентского аккаунта"
}
EOF
chmod 600 ~/.secrets/yandex-direct.json

4. Установите скилл

Склонируйте репозиторий в директорию скиллов агента (нужны bash, curl, jq):

# OpenClaw
git clone https://github.com/Silverov/yandex-direct-skill ~/clawd/skills/direct

# Claude Code
git clone https://github.com/Silverov/yandex-direct-skill ~/.claude/skills/direct

5. Запустите аудит

Скажите агенту: «Проведи аудит Яндекс Директа» — и наблюдайте.

📝 История изменений

v2.0.2 — октябрь 2026

• Исправлено: yd-audit.sh читал кампании и группы через v5, где ЕПК выглядит как TEXT_CAMPAIGN без своих настроек, — теперь через v501 (yd-api.sh тоже отправляет такие get-запросы на v501).
• Исправлено: ошибка 56 Reports API (не чаще 1 запроса в 10 с): пауза между отчётами аудита, офлайн-отчёты опрашиваются не чаще раза в 10 с, при ошибке 56 запрос повторяется.
• Исправлено: sitelinks.get в аудите отклонялся (ошибка 4004: Sitelinks в FieldNames вместе с SitelinkFieldNames).
• Документация: автоописание для ЕРИР у комбинаторных объявлений через API не читается — проверять в интерфейсе.

v2.0.1 — октябрь 2026

• Понятная подсказка, когда API Директа отвечает пустым HTTP 204 (API отключён на стороне Яндекса, например в спецрежиме после сбоя дата-центров в октябре 2026) — в yd-api.sh и yd-report.sh.
• yd-audit.sh подсказывает --include-archived, если все кампании в архиве.
• Соответствие старых подписей стратегий в таблице кампаний («Оптимизация кликов / конверсий») типам стратегий в API.

v2.0 — октябрь 2026

• Исправлено: yd-api.sh дописывал лишнюю } к любым параметрам (${3:-{}}) — ни один запрос с параметрами не выполнялся.
• Исправлено: запросы аудита, которые отклонял API: AdExtensionIds в TextAdFieldNames, пустой SelectionCriteria у быстрых ссылок и наборов минус-фраз, больше 10 CampaignIds в запросе; не было постраничной выборки.
• Исправлено: отчёты не дожидались готовности (retryIn — HTTP-заголовок) и при повторе получали новое имя; конверсии суммировались по всем целям Метрики — теперь передаются приоритетные цели и модель атрибуции.
• Добавлено: ЕПК (UnifiedCampaignFieldNames, маршрутизация на v501), комбинаторные объявления (ResponsiveAdFieldNames), настройки автотаргетинга, корректировки ставок, уточнения; Client-Login; summary.json.
• Обновлено: чеклист аудита (разделение Поиск/РСЯ больше не Critical, нет «показателя качества» как в Google, комбинаторные объявления, профиль организации вместо визитки, недельные бюджеты), актуальные стратегии (по нескольким целям, «Максимум прибыли»), диапазоны корректировок, требования к изображениям, правила о русском языке с 01.03.2026.
• Безопасность: изменения в кабинете — только после подтверждения конкретного изменения пользователем.

🏗 История создания

Этот скилл родился за один вечер. Нам нужно было настроить кампании в Яндекс Директе для stepback.ru. После создания кампаний через API за 3 минуты мы нашли claude-ads — отличный скилл для Google/Meta/LinkedIn, но без поддержки Яндекса. Поэтому мы создали свой, прогнали аудит на своём аккаунте (Грейд D → C+) и исправили проблемы на месте.

📄 Лицензия

MIT — используйте, форкайте, улучшайте.