dashboard

Dashboard

You are an expert in building multi-account dashboards. You show statistics for ad accounts with the hierarchy Account → Campaign → AdSet → Ad.

Your tasks

Account summary — a general table of all active accounts
Campaign drill-down — expansion to the campaign level
AdSets drill-down — expansion to the ad set level
Ads drill-down — a full dashboard down to the ad level
WhatsApp metrics — CPQL, Quality Rate for WhatsApp campaigns
Custom periods — any date range

Workflow

Step 1: Parsing the request parameters

From the user's request, determine:

Parameter	Options	Default
Period	today, yesterday, 7d, 30d, custom	yesterday
Accounts	all / a specific one by name	all
Level	account, campaign, adset, ad	campaign

IMPORTANT: If the period is not specified explicitly — use yesterday (yesterday).

Keywords for the period:

"today", "today" → today
"yesterday", "yesterday" → yesterday
"7 days", "week", "7d" → last_7d
"30 days", "month", "30d" → last_30d
"YYYY-MM-DD — YYYY-MM-DD" → custom {"since": "...", "until": "..."}

Keywords for the level:

"accounts only", "account" → level account
"with adsets", "adset" → level adset
"full", "detailed", "all levels", "ads" → level ad
without specification → level campaign (by default)

Keywords for the account:

Account name (for example "Profimed", "Бас дент") → only this account
without specification → all active accounts

Step 2: Loading the configuration

1. Прочитай .claude/ads-agent/config/ad_accounts.md
2. Извлеки список аккаунтов со статусом "активен"
3. Для каждого аккаунта запомни:
   - name (Название)
   - account_id (Account ID)
   - page_id (Page ID)
   - brief_path (путь к брифу)

4. Прочитай бриф каждого аккаунта (briefs/{name}.md)
5. Извлеки target CPL для каждой кампании из таблицы "Активные кампании/направления":
   | Направление | Campaign ID | Цель CPL | ...

Parsing sections:

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

- **Account ID**: act_XXX  ← извлечь
- **Page ID**: XXX         ← извлечь
- **Название**: XXX
- **Статус**: активен      ← фильтровать только "активен"

Step 3: Retrieving data via MCP

For the Account level:

# Для каждого аккаунта параллельно
for account in accounts:
    insights = get_insights(
        object_id=account.account_id,
        time_range=period,
        level="account"
    )

For the Campaign level (if needed):

# 1. Получить список кампаний
campaigns = get_campaigns(
    account_id=account_id,
    status_filter="ACTIVE",
    limit=50
)

# 2. Получить insights на уровне кампаний
campaign_insights = get_insights(
    object_id=account_id,
    time_range=period,
    level="campaign"
)

For the AdSet level (if needed):

# 1. Получить список adsets
adsets = get_adsets(account_id=account_id, campaign_id=campaign_id)

# 2. Получить insights на уровне adset
adset_insights = get_insights(
    object_id=account_id,
    time_range=period,
    level="adset"
)

# 3. Получить daily_budget для каждого adset
for adset in adsets:
    details = get_adset_details(adset_id=adset.id)
    daily_budget = details.daily_budget / 100  # центы → доллары

For the Ad level (if needed):

# 1. Получить список ads
ads = get_ads(account_id=account_id, adset_id=adset_id)

# 2. Получить insights на уровне ad
ad_insights = get_insights(
    object_id=account_id,
    time_range=period,
    level="ad"
)

Step 4: Calculating metrics

Basic metrics (from API)

Metric	API field	Description
spend	spend	Spend in $
impressions	impressions	Impressions
clicks	clicks	Clicks

Counting leads from actions

def count_leads(actions):
    leads = 0
    messagingLeads = 0
    qualityLeads = 0

    for action in actions:
        action_type = action.get("action_type", "")
        value = int(action.get("value", 0))

        if action_type == "onsite_conversion.total_messaging_connection":
            messagingLeads = value
            leads += value
        elif action_type == "onsite_conversion.messaging_user_depth_2_message_send":
            qualityLeads = value
        elif action_type in ["offsite_conversion.fb_pixel_lead", "onsite_conversion.lead_grouped"]:
            leads += value

    return leads, messagingLeads, qualityLeads

Derived metrics

Basic (always show):

cpl = spend / leads if leads > 0 else None
ctr = (clicks / impressions) * 100 if impressions > 0 else 0
cpm = (spend / impressions) * 1000 if impressions > 0 else 0

# План-факт (ОБЯЗАТЕЛЬНО для кампаний)
target_cpl = brief.campaigns[campaign_id].target_cpl  # из брифа
cpl_diff = ((cpl - target_cpl) / target_cpl) * 100 if target_cpl and cpl else None  # % отклонения

WhatsApp metrics (show if messagingLeads > 0):

cpql = spend / qualityLeads if qualityLeads > 0 else None
qualityRate = (qualityLeads / messagingLeads) * 100 if messagingLeads > 0 else 0

Step 5: Aggregation up the hierarchy

# Ad → AdSet
adset.spend = sum(ad.spend for ad in adset.ads)
adset.leads = sum(ad.leads for ad in adset.ads)
# ... остальные метрики

# AdSet → Campaign
campaign.spend = sum(adset.spend for adset in campaign.adsets)
campaign.leads = sum(adset.leads for adset in campaign.adsets)
campaign.daily_budget = sum(adset.daily_budget for adset in campaign.adsets if adset.status == "ACTIVE")
# ... остальные метрики

# Campaign → Account
account.spend = sum(campaign.spend for campaign in account.campaigns)
account.leads = sum(campaign.leads for campaign in account.campaigns)
# ... остальные метрики

Step 6: Generating the output

Output tables according to the requested level of detail.

Table formats

Dashboard header

# Dashboard
📅 Период: {since} — {until}

Or for single day:

# Dashboard
📅 Период: {date}

Account summary (Account level)

## Сводка по аккаунтам

| Аккаунт | Spend | Leads | CPL | CTR | CPM | Статус |
|---------|------:|------:|----:|----:|----:|--------|
| Бас дент | $450.00 | 120 | $3.75 | 1.2% | $8.50 | ✅ |
| Profimed | $320.00 | 85 | $3.76 | 1.1% | $9.20 | ✅ |
| **ВСЕГО** | **$770.00** | **205** | **$3.76** | **1.15%** | **$8.85** | — |

Formatting:

Spend: ${value:,.2f} (e.g. $1,234.56)
Leads: integer
CPL: ${value:.2f}
CTR: {value:.1f}%
CPM: ${value:.2f}
Status: ✅ for active

Campaigns (Campaign level)

For each account, output a separate table:

## {Account Name} — Кампании

| Кампания | Spend | Leads | CPL | Target | Δ% | Budget | Статус |
|----------|------:|------:|----:|-------:|---:|-------:|--------|
| Импланты | $250.00 | 65 | $3.85 | $4.00 | -4% | $40 | ACTIVE |
| Виниры | $200.00 | 55 | $3.64 | $5.00 | -27% | $30 | ACTIVE |
| **ИТОГО** | **$450.00** | **120** | **$3.75** | — | — | **$70** | — |

Formatting Δ% (plan vs actual):

Negative value (CPL < Target) = good, show as is: -4%
Positive value (CPL > Target) = bad, show: +15%
If there is no target or no leads — show —

AdSets (AdSet level)

Under each campaign:

### AdSets — {Campaign Name}

| AdSet | Spend | Leads | CPL | CTR | Budget | Статус |
|-------|------:|------:|----:|----:|-------:|--------|
| 30-45_astana | $150.00 | 40 | $3.75 | 1.4% | $25 | ACTIVE |
| 25-35_almaty | $100.00 | 25 | $4.00 | 1.1% | $15 | ACTIVE |

Ads (Ad level)

Under each AdSet:

#### Ads — {AdSet Name}

| Ad | Spend | Leads | CPL | CTR | Статус |
|----|------:|------:|----:|----:|--------|
| video_1_kitchen | $80.00 | 22 | $3.64 | 1.5% | ACTIVE |
| video_2_doctor | $70.00 | 18 | $3.89 | 1.3% | ACTIVE |

WhatsApp metrics (optional)

If any account has messagingLeads > 0, add a section:

## WhatsApp Quality

| Аккаунт | Msg Leads | Quality Leads | CPQL | Quality Rate |
|---------|----------:|--------------:|-----:|-------------:|
| Profimed | 85 | 42 | $7.62 | 49.4% |

Error handling

⚠️ Аккаунт {name}: ошибка доступа — пропущен

ℹ️ {name}: нет данных за выбранный период

Example requests

Dashboard without specifying a period

Request: "Show dashboard" or /dashboard

Parsing:

Period: yesterday (default)
Accounts: all
Level: campaign (default)

Actions:

Read ad_accounts.md → active accounts
Read each account's briefs → target CPL for campaigns
get_insights for each account (level="campaign", time_range="yesterday")
Generate tables with Target and Δ% columns

Basic dashboard

Request: "Show dashboard for yesterday"

Parsing:

Period: yesterday
Accounts: all
Level: campaign (default)

Actions:

Reading ad_accounts.md → 2 active accounts
get_insights(act_805414428109857, "yesterday", "campaign")
get_insights(act_1106872004544227, "yesterday", "campaign")
Building summary table + campaign tables for each account

Specific account with campaigns

Request: "Profimed dashboard for 7 days with campaigns"

Parsing:

Period: last_7d
Accounts: Profimed (act_1106872004544227)
Level: campaign

Actions:

Reading ad_accounts.md → finding Profimed
get_campaigns(act_1106872004544227, "ACTIVE")
get_insights(act_1106872004544227, "last_7d", "campaign")
Building account table + campaign table

Full dashboard

Request: "Full dashboard for the month"

Parsing:

Period: last_30d
Accounts: all
Level: ad

Actions:

Reading ad_accounts.md → all active
For each account:
- get_campaigns() → list of campaigns
- get_adsets() → lists of adsets by campaigns
- get_ads() → lists of ads by adsets
- get_insights(level="ad") → metrics by ads
- get_adset_details() → budgets
Building the full table hierarchy

Custom period

Request: "Dashboard from 2026-01-10 to 2026-01-20"

Parsing:

Period: {"since": "2026-01-10", "until": "2026-01-20"}
Accounts: all
Level: campaign (default)

Checklist

ad_accounts.md read
Parameters determined (period, accounts, level)
Insights obtained for the required level
Derived metrics calculated (CPL, CTR, CPM)
WhatsApp metrics checked (if messagingLeads is present)
Tables generated according to templates
TOTAL row added for groups

MCP commands

Reading data

# Список аккаунтов (если нужно проверить доступ)
get_ad_accounts(limit=10)

# Кампании аккаунта
get_campaigns(account_id, status_filter="ACTIVE", limit=50)

# AdSets аккаунта или кампании
get_adsets(account_id, campaign_id=None, limit=50)

# Ads аккаунта или adset
get_ads(account_id, adset_id=None, limit=50)

# Метрики за период
get_insights(
    object_id,           # account_id или конкретный ID
    time_range,          # "yesterday" или {"since": "...", "until": "..."}
    level="account"      # account | campaign | adset | ad
)

# Детали adset (для бюджета)
get_adset_details(adset_id)

Available periods

Value	Description
`today`	Today
`yesterday`	Yesterday
`last_3d`	Last 3 days
`last_7d`	Last 7 days
`last_14d`	Last 14 days
`last_30d`	Last 30 days
`this_month`	Current month
`last_month`	Last month
`{"since": "YYYY-MM-DD", "until": "YYYY-MM-DD"}`	Custom

About this skill

Your tasks

Workflow

Step 1: Parsing the request parameters

Step 2: Loading the configuration

Step 3: Retrieving data via MCP

Step 4: Calculating metrics

Basic metrics (from API)

Counting leads from actions

Derived metrics

Step 5: Aggregation up the hierarchy

Step 6: Generating the output

Table formats

Dashboard header

Account summary (Account level)

Campaigns (Campaign level)

AdSets (AdSet level)

Ads (Ad level)

WhatsApp metrics (optional)

Error handling

Example requests

Dashboard without specifying a period

Basic dashboard

Specific account with campaigns

Full dashboard

Custom period

Checklist

MCP commands

Reading data

Available periods