Полная документация ниже — автоматически из репозитория slikti/skill_for_claude_code_yandex_direct (ветка main). Оригинальные материалы проекта распространяются на условиях его лицензии.

🚀 Yandex.Direct Skill для Claude Code

Skill, который превращает Claude в твоего директолога: создаёт кампании, пишет
объявления, тянет лидов из Метрики и оптимизирует ставки/бюджеты, чтобы выводить
рекламу в плюс. Может работать в связке с внешним API или MCP-сервисом для
генерации фото/баннеров под Яндекс.Директ. Работает по официальному API
Яндекс.Директа v5. Без сторонних зависимостей — только Python (stdlib).

Установка (30 секунд)

Скопируй папку yandex-direct/ в .claude/skills/ своего проекта (или в
~/.claude/skills/ глобально):

cp -r yandex-direct ~/.claude/skills/

Claude увидит skill автоматически.

Настройка (один раз, ~15 мин)

Полный гайд: references/setup-guide.md. Кратко:

1. Получи OAuth-токен Директа (права direct:api + metrika:read).
2. Подготовь сервис генерации креативов: API-ключ/токен или MCP-коннектор
   для фото/баннеров.
3. Заведи счётчик Метрики и цель (что считаем лидом).
4. При первом вызове skill агент должен сначала спросить:
   • токен Яндекс.Директа/Метрики;
   • sandbox/prod, counter_id, goal_id;
   • токен/ключ и API или MCP-сервис для создания рекламных креативов.

5. cd yandex-direct/scripts
   cp config.example.json config.json
   # впиши token, counter_id, primary_goal_id, target_cpa
   python direct_api.py ping     # должно вернуть OK [SANDBOX] ...
   

По умолчанию sandbox: true — реальные деньги не тратятся, пока сам не
переключишь на боевой кабинет.

Как пользоваться

Просто говори Claude по-русски:

• «Собери кампанию в Директе под доставку цветов в Москве, бюджет 2000/день»
• «Собери семантику из сидов: цветы, букеты + купить, доставка, недорого»
• «Сгенерь 3 варианта объявлений для группы 222»
• «Покажи слив за 2 недели и добавь минус-слова»
• «Снизь CPA по кампании 111 — что предлагаешь?»
• «Залей продажи из CRM, переведи на ROI-стратегию»
• «Запусти автопилот по кампании 111 и дай отчёт»

Claude сам читает SKILL.md, зовёт нужные скрипты и показывает результат.
Денежные изменения — сначала dry-run, потом подтверждение. Повторные запуски
не плодят дубли (локальный state.json), любой залив можно откатить
(rollback.py).

Что внутри

yandex-direct/
├── SKILL.md                  # мозг скилла: 8 сценариев работы
├── README.md                 # этот файл
├── references/               # гайды: setup, API, тексты, оптимизация
├── tests/                    # оффлайн юнит-тесты (без токена)
├── scripts/                  # Python CLI поверх API v5 (stdlib only)
│   ├── direct_api.py         # ядро: клиент, батч-ошибки, cost guard
│   ├── build.py state.py     # оркестратор blueprint + идемпотентность/аудит
│   ├── campaigns.py adgroups.py ads.py extensions.py
│   ├── keywords.py research.py negatives.py adjustments.py image_ads.py
│   ├── reports.py metrica.py crm_upload.py
│   ├── optimize.py abtest.py anomalies.py autopilot.py rollback.py
│   └── config.example.json
└── assets/                   # бриф + исполняемый blueprint кампании

Что умеет (фишки)

• Один blueprint → вся кампания идемпотентно (build.py), без дублей.
• Сбор семантики с проверкой спроса (research.py).
• Работа в паре с генератором креативов через API или MCP для фото/баннеров.
• Реальный ROI: заливка продаж из CRM (crm_upload.py) → оптимизация по
  выручке, а не по «заявкам».
• Автопилот недельного цикла + дневные алерты аномалий бюджета.
• A/B креативов с z-тестом, авто-отключение лузеров.
• Корректировки ставок (моб/демография), общие минус-наборы, ставки по аукциону.
• Безопасность: cost guard, аудит-лог, откат.

Безопасность

• Токен и config.json — в .gitignore, не коммитятся.
• Боевые изменения требуют подтверждения; массовые правки — только через явный --apply.
• Тестируй в песочнице (sandbox: true), переключай на боевой осознанно.

Новый пайплайн креативов

Для визуалов теперь есть два режима:

• creative_provider.mode = "api": skill реально шлёт JSON в внешний сервис
  генерации, получает картинки (base64 или url) и сохраняет их локально.
• creative_provider.mode = "mcp": skill генерирует mcp_manifest.json с
  готовыми prompt-ами и структурой запроса для любого агента/MCP-инструмента.

Базовый поток:

cd yandex-direct/scripts
python generate_creatives.py --brief brief.json
python image_ads.py upload-dir --dir generated/brief
python creative_to_image_manifest.py --input uploads.json --mode uploads \
  --href "https://example.com" --title "Заголовок" --text "Текст" > ads_manifest.json
python image_ads.py create-bulk --group 222 --manifest ads_manifest.json

Для api-режима внешний сервис должен вернуть JSON вида:

{
  "assets": [
    {
      "filename": "banner1.png",
      "mime_type": "image/png",
      "base64": "<base64-bytes>"
    }
  ]
}

Либо вместо base64 можно вернуть url.

Требования

• Python 3.8+ (любой системный, без pip install).
• Аккаунт Яндекс.Директа + Метрики.

Не аффилирован с Яндексом. Использует публичный API Яндекс.Директа v5.