---
name: serp-monitor
description: "Мониторинг позиций в Яндексе: проверка позиций по ключевым, анализ конкурентов, отслеживание динамики. Используй при запросах 'позиции в выдаче', 'SERP', 'конкуренты', 'реклама конкурентов', 'где я показываюсь', 'проверь позицию'."
---

# Мониторинг позиций в Яндексе (SERP Monitor)

Скилл для мониторинга рекламных и органических позиций в поисковой выдаче Яндекса через Yandex XML API.

**Зачем:** Позиции в выдаче напрямую влияют на CTR и стоимость клика. Падение позиций = рост CPA. Мониторинг позволяет вовремя реагировать: скорректировать ставки, обновить объявления, пересмотреть стратегию.

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

### search.sh — поиск в Яндексе (основной)
```bash
scripts/search.sh --query "доставка цветов москва"
scripts/search.sh --query "доставка цветов" --region 2          # Санкт-Петербург
scripts/search.sh --query "купить цветы" --domain mysite.ru     # другой домен
```
Выдаёт таблицу результатов с позициями, доменами, заголовками. Помечает ваш домен звёздочкой.

**Важно:** В бесплатном тарифе Yandex XML не разделяет рекламу и органику. На коммерческих запросах позиции 1-4 обычно рекламные (premium), 5-8 — гарантированные показы. Учитывай это при анализе.

### track_position.sh — отслеживание динамики
```bash
scripts/track_position.sh --query "доставка цветов москва"
scripts/track_position.sh --query "доставка цветов" --region 2
```
Проверяет текущую позицию и сохраняет в CSV-историю (`data/serp-history/`). При 7+ замерах показывает тренд.

### search_region.sh — справочник регионов
```bash
scripts/search_region.sh                    # все регионы
scripts/search_region.sh --search "Петер"   # поиск по имени
```

### iam_token.sh — IAM-токен Yandex Cloud
```bash
scripts/iam_token.sh    # получить/обновить IAM-токен (кешируется на 11 часов)
```
Нужен только если используется Yandex Cloud Search API вместо бесплатного XML.

## Workflow: анализ конкурентов

Анализ конкурентов не требует отдельного скрипта — Codex анализирует выдачу из `search.sh`.

### Шаги:

1. **Собрать выдачу** — запустить `search.sh` для 5-10 ключевых запросов кампании
2. **Codex анализирует рекламные тексты** конкурентов из результатов:
   - Какие УТП используют (цена, доставка, гарантия, опыт)
   - Какие CTA в заголовках ("Заказать", "Купить", "Узнать цену", "Рассчитать")
   - Есть ли быстрые ссылки, уточнения, цены в объявлениях
   - Какие домены стабильно в топ-4 (= активно рекламируются)
3. **Рекомендации по объявлениям:**
   - "60% конкурентов указывают цену — протестируйте добавление цены"
   - "3 из 5 конкурентов пишут про бесплатную доставку — добавьте УТП доставки"
   - "Никто не использует CTA 'Получить скидку' — возможность выделиться"

### Пример запроса пользователя:
> "Проанализируй конкурентов по запросу доставка цветов москва"

Действия:
1. `scripts/search.sh --query "доставка цветов москва"`
2. Проанализировать заголовки и сниппеты конкурентов в топ-8
3. Выделить паттерны в УТП и CTA
4. Сравнить с текущими объявлениями кампании (из MCP `get_ads`)
5. Дать конкретные рекомендации по улучшению текстов

## Интеграция с MCP `yandex-direct`

Для расхода и статистики кампаний используй MCP `yandex-direct`:
- `get_campaign_stats` — расход, клики, показы, конверсии (attribution: LYDC)
- `get_campaigns` / `update_campaign` — проверка и изменение бюджета
- `get_ads` — текущие тексты объявлений для сравнения с конкурентами
- `metrika_get_direct_report` — визиты и отказы из Метрики

## Кросс-ссылки и интеграция

| Ситуация | Действие |
|----------|----------|
| Высокий CPA в Метрике | Проверить позиции — возможно, упали и CTR снизился |
| Позиция упала с #2 на #5 | Проверить бюджет через MCP `get_campaign_stats` — возможно, конкуренты подняли ставки |
| Конкуренты в топ-4, мы на #7 | Рассмотреть повышение ставок или смену стратегии |
| Позиция стабильна, но CPA растёт | Проблема не в позиции — проверить лендинг, отказы в Метрике |
| Новая кампания запущена | Через 3-5 дней начать отслеживание позиций |

### Связка с другими скиллами:

- **yandex-metrika** → если позиция упала, проверить CPA и конверсии через MCP `metrika_get_direct_report`
- **yandex-direct** → управление кампаниями, ставками, объявлениями
- **demand-research** → если конкурентов стало больше, исследовать новые ниши через анализ спроса

## Обновление файлов кампаний

После проверки позиций обнови файл `campaigns/<utm>.md`:

1. Добавь результаты в секцию мониторинга:
```markdown
### Позиции в выдаче
| Дата | Запрос | Позиция | Тренд |
|------|--------|---------|-------|
| 2026-03-15 | доставка цветов москва | #3 | стабильно |
```

2. Обнови «Где сейчас» если позиция значительно изменилась

## Рекомендуемая частота проверок

- **Еженедельно** (понедельник) — проверить позиции по основным 5-10 запросам каждой кампании
- **После изменений** — через 2-3 дня после смены ставок/стратегии/текстов проверить позиции
- **При росте CPA** — немедленно проверить, не упали ли позиции
- **Ежемесячно** — полный анализ конкурентов по всем ключевым запросам

## Настройка

- **YANDEX_XML_USER** и **YANDEX_XML_KEY** — из `tokens.env` (см. `config/README.md`)
- **SITE_DOMAIN** — из `tokens.env`, можно переопределить через `--domain`
- **Квота** — бесплатно 10 запросов/день, экономьте: проверяйте 5-10 ключевых запросов, а не все