account-onboarding

Account Onboarding

Interactive assistant for setting up a new Facebook Ads account.

Your tasks

Guide the user through information collection (~20 questions)
Validate data at each step
Show a summary and request confirmation
Create configuration files
Check the API connection

What is created as a result

.claude/ads-agent/config/
├── ad_accounts.md          ← Добавляется запись аккаунта
└── briefs/
    └── {account_name}.md   ← Создаётся новый бриф

Workflow (8 steps)

Step 0: Greeting

Output the message:

👋 Привет! Это онбординг нового рекламного аккаунта.

Я задам ~20 вопросов о бизнесе клиента:
• Базовая информация (4)
• Бизнес-параметры (5)
• Цель рекламы (1)
• Технические ID (2-5 в зависимости от цели)
• Направления/кампании (по 5 на каждое)

В конце создам:
- Запись в ad_accounts.md
- Бриф briefs/{name}.md

Готов начать?

Wait for confirmation.

Step 1: Basic information (4 questions)

MANDATORY — all 4.

1. Название бизнеса:
   > (например: Bas Dent, FitLife, TechStore)

2. Facebook Ads Account ID:
   > act_XXXXXXXXX
   (найти в Business Manager → Ad Accounts)

3. Часовой пояс:
   > UTC+5 (Алматы) / UTC+3 (Москва) / UTC+6 (Астана) / другой

4. Ниша бизнеса:
   > E-commerce / Услуги / SaaS / Образование / Медицина / другая

Validation:

Account ID must start with act_
Time zone — format UTC+X

Default: Currency is always USD.

Step 2: Business parameters (5 questions)

MANDATORY: 1-3. OPTIONAL: 4-5.

1. Что продаёте / какие услуги:
   > (краткое описание основных продуктов/услуг)

2. Регион работы:
   > Казахстан / Россия / СНГ / Весь мир / конкретные города

3. Целевая аудитория:
   > Возраст: 25-45
   > Пол: все / жен / муж
   > Интересы: (ключевые)

4. Боли клиентов (для копирайтинга) [опционально]:
   > Какие проблемы решаете? Что волнует клиентов?

5. Конкурентные преимущества [опционально]:
   > Почему должны выбрать вас?

After receiving the region — find the geo ID:

Read the reference guide config/knowledge/geo_locations.md
Find the specified cities/countries in the tables

If the city is NOT found in the reference guide — call MCP:

search_geo_locations(query="{город}", location_types=["city"])

Save for the brief:
- city_key — city ID
- region_id — region ID (if any)
- country_code — country code
- radius — default radius (25 km for KZ cities, 40 km for RU)

Step 3: Ad objective (1 question)

MANDATORY.

Выбери цель рекламы:

1. WhatsApp — сообщения в WhatsApp (оптимизация на начало переписки)
2. Instagram Трафик — клики на профиль Instagram
3. Site Leads — лиды на сайте (с Pixel)
4. Lead-формы — мгновенные формы Facebook/Instagram

> (1 / 2 / 3 / 4)

Technical parameters by objective:

Objective	Campaign Objective	Optimization Goal	Destination Type
WhatsApp	OUTCOME_ENGAGEMENT	CONVERSATIONS	WHATSAPP
Instagram Traffic	OUTCOME_TRAFFIC	LINK_CLICKS	—
Site Leads	OUTCOME_LEADS	OFFSITE_CONVERSIONS	WEBSITE
Lead forms	OUTCOME_LEADS	LEAD_GENERATION	ON_AD

Step 4: Technical IDs (dynamic)

Depending on the objective (from Step 3), collect the required technical data.

ALWAYS MANDATORY:

1. Facebook Page ID:
   > (число, например: 123456789012345)
   (найти в Business Suite → Страницы → О странице)

2. Есть ли Instagram аккаунт? (да/нет)
   Если да:
   > Instagram Account ID: (число)
   (найти в Business Suite → Instagram аккаунты)

DEPENDING ON THE OBJECTIVE:

If objective = "WhatsApp":

3. WhatsApp Business номер телефона:
   > +7XXXXXXXXXX (формат с кодом страны)
   (должен быть подключен к Business Manager)

If objective = "Lead forms":

3. Lead Form ID [если уже есть]:
   > (число) или "создать новую"
   (найти в Meta Business Suite → Формы)

4. Какие поля в форме нужны:
   > Имя / Телефон / Email / Город / другие

If objective = "Site Leads":

3. URL сайта/лендинга:
   > https://example.com

4. Facebook Pixel ID:
   > (число, например: 123456789012345)
   (найти в Events Manager → Data Sources)

5. Есть ли настроенные события? (да/нет)
   Если да, какие:
   > Purchase / Lead / AddToCart / ViewContent / другие

If objective = "Instagram Traffic":

(Дополнительных ID не требуется, только Page ID и Instagram ID)

Validation:

Page ID — digits only, 15-16 characters
Instagram ID — digits only
WhatsApp — format +XXXXXXXXXXX (E.164)
Lead Form ID — digits only or "create new"
Pixel ID — digits only, 15-16 characters
URL — valid URL with https://

Step 5: Ad sets/campaigns (interactive)

Сколько направлений/кампаний в аккаунте?
> (1-10)

For EACH ad set ask:

Направление {N}:
1. Название: (например: Импланты, Виниры, Курсы)
2. Целевой CPL: $X (стоимость лида в USD)
3. Дневной бюджет: $X
4. Приоритет: высокий / средний / низкий
5. Campaign ID [если уже есть]: или "создать новую"

Validation:

CPL must be a number > 0
Budget must be a number >= 5

Step 6: ROAS (e-commerce only)

Ask only if niche = E-commerce.

Целевой ROAS:

ROAS (Return on Ad Spend) — сколько долларов выручки приносит $1 рекламных расходов.

Пример расчёта:
• Потратили на рекламу: $100
• Получили выручки: $300
• ROAS = $300 / $100 = 3x

Формула: ROAS = Выручка / Расходы на рекламу

Типичные значения:
• 2x — минимально приемлемый
• 3x-4x — хороший результат
• 5x+ — отличный результат

> Целевой ROAS: Xх (например: 3x) или "не отслеживаю"

Step 7: Validation

Output ALL collected information in a structured form:

📋 СВОДКА ОНБОРДИНГА

## Базовая информация
- Название: {business_name}
- Account ID: {account_id}
- Валюта: USD
- Часовой пояс: {timezone}
- Ниша: {niche}

## Бизнес
- Продукт: {product}
- Регион: {region}
- ЦА: {target_audience}
- Боли: {pains}
- Преимущества: {advantages}

## Цель рекламы
- Цель: {goal} ({objective} / {optimization_goal})
- ROAS: {roas} (если e-commerce)

## Технические ID
- Page ID: {page_id}
- Instagram ID: {instagram_id} (или "нет")
- WhatsApp: {whatsapp_phone} (если WhatsApp)
- Lead Form ID: {lead_form_id} (если Lead-формы)
- Pixel ID: {pixel_id} (если Site Leads)
- Сайт: {website_url} (если Site Leads)

## Направления ({count})
| Название | Целевой CPL | Бюджет | Приоритет | Campaign ID |
|----------|-------------|--------|-----------|-------------|
{directions_rows}

---

Всё верно? (да / нет, изменить)

If "no" — ask what to change and update the data.

Step 8: File generation

After confirmation, create the files:

1. Add an entry to ad_accounts.md

Read .claude/ads-agent/config/ad_accounts.md, find the last account number and add to the end (before "Example format"):

---

## Аккаунт {N}: {business_name}

- **Account ID**: {account_id}
- **Page ID**: {page_id}
- **Instagram ID**: {instagram_id}
- **Название**: {business_name}
- **Бриф**: [briefs/{filename}.md](briefs/{filename}.md)
- **Статус**: активен
- **Валюта**: USD
- **Часовой пояс**: {timezone}
- **Цель рекламы**: {goal}
- **Заметки**: {niche}. {short_description}

---

2. Create briefs/{filename}.md

# {business_name} - Бриф

> Создан через /account-onboarding {date}

---

## Бизнес

- **Ниша**: {niche}
- **Продукт**: {product}
- **Регион**: {region}
- **Целевая аудитория**: {target_audience}
- **Сайт/Landing**: {website}

### Для копирайтинга
- **Боли клиентов**: {pains}
- **Преимущества**: {advantages}

---

## Цель рекламы

- **Цель**: {goal}
- **Campaign Objective**: {objective}
- **Optimization Goal**: {optimization_goal}
- **Destination Type**: {destination_type}
- **Целевой ROAS**: {roas}

---

## Технические ID (для API)

### Обязательные
- **Facebook Page ID**: `{page_id}`
- **Instagram Account ID**: `{instagram_id}` <!-- или "нет" -->

### В зависимости от цели

<!-- Заполняется в зависимости от goal -->

#### Для WhatsApp:
- **WhatsApp номер**: `{whatsapp_phone}`

#### Для Lead-форм:
- **Lead Form ID**: `{lead_form_id}`
- **Поля формы**: {form_fields}

#### Для Site Leads:
- **URL сайта**: {website_url}
- **Pixel ID**: `{pixel_id}`
- **Настроенные события**: {pixel_events}

### Гео-локации

| Город/Страна | Тип | Key/Code | Region ID | Радиус |
|--------------|-----|----------|-----------|--------|
| {city_name} | city | {city_key} | {region_id} | {radius} km |
| {country_name} | country | {country_code} | — | — |

---

## Правила оптимизации (дефолты)

### Пороговые значения
- **Минимум impressions для решений**: 1000
- **Минимум конверсий для решений**: 3
- **Минимум дней до агрессивных действий**: 2
- **Ad-eater порог**: CPL > target × 3

### Бюджетные лимиты
- **Максимальное увеличение за раз**: 30%
- **Максимальное уменьшение за раз**: 50%

### Временные ограничения
- **Часовой пояс**: {timezone}
- **Не создавать adsets после**: 18:00

### CPL диапазоны
- **Normal**: target × 1.0-1.5
- **High**: target × 1.5-2.0
- **Ad-eater**: target × 3.0+

---

## Активные кампании/направления

| Название | Campaign ID | Цель CPL | Дневной бюджет | Приоритет | Статус |
|----------|-------------|----------|----------------|-----------|--------|
{directions_rows}

---

## Заметки

- Создан: {date}
- Онбординг провёл: Claude (skill: account-onboarding)

---

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

| Дата | Изменение |
|------|-----------|
| {date} | Создан бриф через /account-onboarding |

Step 9: Connection test

After creating the files, check API access:

# Проверка доступа
campaigns = get_campaigns(account_id="{account_id}", limit=5)

Output the result:

✅ Онбординг завершён!

Созданные файлы:
1. .claude/ads-agent/config/ad_accounts.md — запись добавлена
2. .claude/ads-agent/config/briefs/{filename}.md — бриф создан

API проверка:
- Доступ к аккаунту: ✅
- Найдено кампаний: {count}

Теперь можно использовать:
- /ads-optimizer — оптимизация
- /ads-reporter — отчёты
- /campaign-manager — управление кампаниями

If the API returned an error:

⚠️ Файлы созданы, но API недоступен!

Ошибка: {error_message}

Проверьте:
1. Account ID правильный?
2. MCP токен имеет доступ к аккаунту?
3. Аккаунт активен в Business Manager?

Файлы сохранены, можно исправить Account ID в briefs/{filename}.md

Default values

currency: USD

optimization_rules:
  min_impressions: 1000
  min_conversions: 3
  min_days: 2
  max_budget_increase: 30
  max_budget_decrease: 50
  no_create_after: "18:00"
  ad_eater_multiplier: 3

cpl_ranges:
  normal_multiplier: 1.5
  high_multiplier: 2.0
  ad_eater_multiplier: 3.0

budget_defaults:
  adset_min: 5

Goals and their parameters

Goal	objective	optimization_goal	destination_type	billing_event
WhatsApp	OUTCOME_ENGAGEMENT	CONVERSATIONS	WHATSAPP	IMPRESSIONS
Instagram Traffic	OUTCOME_TRAFFIC	LINK_CLICKS	—	IMPRESSIONS
Site Leads	OUTCOME_LEADS	OFFSITE_CONVERSIONS	WEBSITE	IMPRESSIONS
Lead forms	OUTCOME_LEADS	LEAD_GENERATION	ON_AD	IMPRESSIONS

Data validation

Field	Check
account_id	Starts with `act_`, digits only after
page_id	Digits only, 15-16 characters
instagram_id	Digits only or "no"
whatsapp_phone	Format +XXXXXXXXXXX (E.164)
lead_form_id	Digits only or "create new"
pixel_id	Digits only, 15-16 characters
website_url	Valid URL with https://
timezone	Format UTC+X or UTC-X
target_cpl	Number > 0
roas	Number > 1 or "not tracking"
budget	Numbers > 0, min >= 5

Filename generation

filename = business_name.lower()
           .replace(" ", "_")
           .replace("-", "_")
           .replace(/[^a-z0-9_]/g, "")

Примеры:
- "Bas Dent" → "bas_dent"
- "FitLife Studio" → "fitlife_studio"
- "ИП Иванов" → "ip_ivanov" (транслит)

After onboarding

Readiness checklist:

Brief created in briefs/{name}.md
Account added to ad_accounts.md
API access checked
Ready for /ads-optimizer

Common errors

Error	Solution
Account ID without `act_`	Add the prefix `act_`
API access error	Check the token in MCP, add the account to Business Manager
File already exists	Ask: update or create with a suffix?

About this skill

Your tasks

What is created as a result

Workflow (8 steps)

Step 0: Greeting

Step 1: Basic information (4 questions)

Step 2: Business parameters (5 questions)

Step 3: Ad objective (1 question)

Step 4: Technical IDs (dynamic)

Step 5: Ad sets/campaigns (interactive)

Step 6: ROAS (e-commerce only)

Step 7: Validation

Step 8: File generation

1. Add an entry to ad_accounts.md

2. Create briefs/{filename}.md

Step 9: Connection test

Default values

Goals and their parameters

Data validation

Filename generation

After onboarding

Common errors