yandex-analytics

Informational skill — unified Yandex analytics hub with single config and cross-service workflows.

Config

Single config file for all Yandex services: config/.env

# === OAuth Token (Webmaster + Metrika + Direct + Wordstat) ===
# One token with all scopes — see config/README.md for setup
YANDEX_OAUTH_TOKEN=y0_your_token

# === Metrika ===
# Counter ID is PER-PROJECT — pass via --counter flag when running metrika scripts
# Set here only as default if you mostly work with one site:
# YANDEX_METRIKA_COUNTER=12345678

# === Yandex Cloud Search API v2 ===
YANDEX_SEARCH_API_KEY=your_api_key
YANDEX_CLOUD_FOLDER_ID=your_folder_id

# === Optional: Direct sandbox ===
# YANDEX_DIRECT_SANDBOX=true
# YANDEX_DIRECT_LOGIN=agency_client_login

# === Semantic Drift ===
# No API keys needed — uses local sentence-transformers model

Note: Metrika counter ID varies per project. All metrika scripts accept --counter ID flag.

Run bash scripts/check.sh to verify which services are configured.

Architecture

This skill is an orchestrator over individual Yandex skills:

yandex-analytics/          <- unified entry point
  config/.env              <- SINGLE config for all services
  scripts/
    check.sh               <- verify all connections
    sync-config.sh         <- propagate config to individual skills
    dashboard.sh           <- quick status of all services
  SKILL.md                 <- this file

yandex-webmaster/          <- indexing, queries, diagnostics
yandex-metrika/            <- traffic, behavior, conversions
yandex-wordstat/           <- search demand, semantics
yandex-direct/             <- ad campaigns, statistics
yandex-search/             <- SERP positions, competitors
seo-audit/                 <- comprehensive SEO audit orchestrator
semantic-drift/            <- topical drift analysis

Setup (one-time)

Step 1: Configure tokens

cp config/.env.example config/.env
# Edit config/.env with your tokens

Step 2: Sync config to all skills

bash scripts/sync-config.sh

This propagates the unified config to individual skill config directories.

Step 3: Verify connections

bash scripts/check.sh

Quick Reference

What do I need for...?

Token Scopes Required

All four use the same OAuth token if you add all scopes when creating the app.

Нюансы регистрации

Wordstat API

• Использует OAuth-токен (тот же, что Вебмастер/Метрика), но требует отдельное одобрение доступа к API
• Ошибка без одобрения: 403 Forbidden
• Как получить доступ: отправить запрос через поддержку Яндекс Директа с логином и ClientId из OAuth-приложения
• Одобрение Wordstat и Direct — отдельные процессы, одно может быть одобрено без другого
• После одобрения существующий OAuth-токен сразу работает — новый токен получать не нужно

Direct API

• Использует тот же OAuth-токен, тоже требует отдельное одобрение доступа к API
• Ошибка без одобрения: код 58 «Незавершенная регистрация»
• Как получить доступ:
  1. Зайти на direct.yandex.ru → Настройки (шестерёнка) → Настройки API
  2. Вкладка «Мои заявки» → «Новая заявка»
  3. Прямая ссылка: https://direct.yandex.ru/registered/main.pl?cmd=apiSettings
  4. Указать ClientId из OAuth-приложения, описать назначение
  5. Ждать от 1 часа до 3 рабочих дней (рассмотрение пн-пт 10:00-19:00 МСК)
• Одна заявка на приложение — покрывает всех пользователей этого приложения

Search API v2 (Yandex Cloud)

• Не использует OAuth — полностью отдельная авторизация через Yandex Cloud
• Старый XML API (xml.yandex.ru) мёртв с ~2025 года (ошибка 4002)
• Шаги настройки:
  1. Зарегистрироваться в console.yandex.cloud
  2. Создать сервисный аккаунт
  3. Назначить роли: search-api.executor + search-api.webSearch.user (обе обязательны)
  4. Создать API-ключ для сервисного аккаунта
  5. Скопировать folder ID из консоли Cloud (выпадающий список слева вверху → копировать ID)
• Частая ошибка: неправильный folder ID. Каталог должен быть в том же облаке, где у сервисного аккаунта назначены роли
• API асинхронный: POST для отправки запроса → опрос endpoint операций → получение XML в base64
• Тарификация: оплата за запрос (бесплатного лимита, как у старого XML API, нет)

Общие советы

• Создавайте одно OAuth-приложение со всеми скоупами на oauth.yandex.ru/client/new — экономит время
• Скоупы для включения: Вебмастер, Метрика, Директ, Вордстат (4 галочки)
• После создания OAuth-приложения всё равно нужно отдельно подать заявки на доступ к API Директа и Вордстата
• Search API использует совершенно другую авторизацию (API-ключ Yandex Cloud, не OAuth)

Workflow Examples

"How's the site doing?" (quick dashboard)

bash scripts/dashboard.sh --host https://example.com

Runs: Metrika overview + Webmaster summary + SQI. Shows combined metrics.

"Full SEO audit"

Invoke the seo-auditing skill — it will use data from all configured services.

"Semantic drift analysis"

# Resolve skills root (default ~/.claude/skills, override via SKILLS_ROOT env)
SKILLS_ROOT="${SKILLS_ROOT:-$HOME/.claude/skills}"

# 1. Collect data
bash "$SKILLS_ROOT"/yandex-webmaster/scripts/search_queries.sh \
  --host https://example.com --limit 500 --csv /tmp/queries.csv

# 2. Analyze
python "$SKILLS_ROOT"/semantic-drift/scripts/analyze.py \
  --queries /tmp/queries.csv --output /tmp/drift.html

"Research keyword + check position + see traffic"

# 1. Demand in Wordstat
bash "$SKILLS_ROOT"/yandex-wordstat/scripts/top_requests.sh \
  --phrase "купить кирпич" --regions 213

# 2. Current position
bash "$SKILLS_ROOT"/yandex-search/scripts/positions.sh \
  --domain example.com --query "купить кирпич" --region 213

# 3. Current traffic to related pages (pass counter ID for the project)
bash "$SKILLS_ROOT"/yandex-metrika/scripts/pages.sh --counter 12345678 --url "/kirpich/"

Limits Summary