growth-report

SEO Performance Report Skill

Generates a comprehensive 3-month SEO performance HTML report using live DataForSEO data. The report covers traffic trends, keyword rankings, top content clusters, competitive positioning, strategic priorities, and an executive summary — all in a dark-theme executive-ready HTML file.

STEP 0 — COLLECT ALL INPUTS BEFORE DOING ANYTHING

All four inputs are mandatory. Do not make any API calls until all four are confirmed.

Collect them in a single message using this exact format — ask for everything at once, never ask for inputs one at a time:

If the user has NOT provided all four inputs, ask:

To generate the report I need 4 things:

1. Target domain — the site to report on, e.g. firefly.ai

2. Competitor domains — up to 5–6 competitors, e.g. spacelift.io, env0.com, terraform.io

3. Date range — start and end date for the 3-month window (default: Feb 20 → May 20, 2026)

4. Location — country for search data (default: United States)

Which of these do you want to change from the defaults?

If the user has already provided the target domain and competitors (e.g. "generate SEO report for firefly.ai vs spacelift.io, env0.com"), confirm the two optional inputs:

Got it — I'll generate the report for firefly.ai vs spacelift.io, env0.com.

Just confirming the defaults:

- Date range: Feb 20 → May 20, 2026

- Location: United States

OK to proceed with these, or would you like to change either?

Input parsing rules:

| Input | Rules | |---|---| | TARGET_DOMAIN | Strip https://, http://, www., and trailing slashes. Store bare domain only (e.g. firefly.ai) | | COMPETITORS | Strip same prefixes from each. Accept comma-separated or space-separated list. Min 2, max 6 competitors. | | START_DATE | Parse any human date format → YYYY-MM-DD. Default: 2026-02-20 | | END_DATE | Parse any human date format → YYYY-MM-DD. Default: 2026-05-20 | | LOCATION | Accept country name. Default: United States. Must be a valid DataForSEO location_name (full country name only, never city or region). |

After confirmation, echo back the resolved inputs clearly before proceeding:

✓ Target: firefly.ai

✓ Competitors: spacelift.io, env0.com, controlmonkey.io, scalr.com, terraform.io

✓ Date range: Feb 20, 2026 → May 20, 2026

✓ Location: United States

Fetching data now...

CRITICAL API SETTINGS

Always use ignore_synonyms: false on every DataForSEO call. Using the default ignore_synonyms: true underreports traffic and keyword counts by 30–50%. This is the single most important parameter to get right — never omit it.

STEP 1 — Baseline Metrics

Call dataforseo_labs_google_historical_rank_overview with:

target:          TARGET_DOMAIN
location_name:   LOCATION
language_code:   en
ignore_synonyms: false

From the returned monthly array, find the snapshot closest to START_DATE (match by year+month). Extract and store:

• baseline_traffic = metrics.organic.etv
• baseline_keywords = metrics.organic.count
• baseline_top3 = metrics.organic.pos_1 + metrics.organic.pos_2_3

⚠️ There is NO pos_1_3 field in DataForSEO. Always compute Top 3 as pos_1 + pos_2_3.

Also extract all monthly snapshots between START_DATE and END_DATE for the traffic trend bars in the report (typically 3–4 data points):

• For each snapshot store: month_label (e.g. "Feb 2026"), etv, year, month
• Sort ascending by date
• These become TREND_LABEL_1..4, TREND_ETV_1..4 in the HTML template

STEP 2 — Current Metrics

Call dataforseo_labs_google_domain_rank_overview with:

target:          TARGET_DOMAIN
location_name:   LOCATION
language_code:   en
ignore_synonyms: false

Extract from metrics.organic:

• current_traffic = etv
• current_keywords = count
• current_top3 = pos_1 + pos_2_3
• current_pos_1 = pos_1
• current_pos_2_3 = pos_2_3
• current_pos_4_10 = pos_4_10
• current_pos_11_20 = pos_11_20
• current_pos_21_100 = sum of pos_21_30 + pos_31_40 + pos_41_50 + pos_51_60 + pos_61_70 + pos_71_80 + pos_81_90 + pos_91_100

Calculate all deltas:

traffic_growth_pct  = ((current_traffic - baseline_traffic) / baseline_traffic) * 100
keywords_change     = current_keywords - baseline_keywords
keywords_change_pct = (keywords_change / baseline_keywords) * 100
top3_growth_pct     = ((current_top3 - baseline_top3) / baseline_top3) * 100

Format rules:

• Prefix + for positive values, - is automatic for negative
• Round all percentages to 1 decimal place
• Add pos CSS class for positive deltas, neg for negative

STEP 3 — Competitive Landscape

3a — Current Traffic Snapshot

Call dataforseo_labs_bulk_traffic_estimation with:

targets:         [TARGET_DOMAIN, ...COMPETITORS]   ← all domains in a single API call
location_name:   LOCATION
language_code:   en
item_types:      ["organic"]
ignore_synonyms: false

For each domain returned, extract: etv, count.

Sort all domains descending by etv. Assign rank 1 = highest traffic. Determine:

• competitive_rank = rank position of TARGET_DOMAIN (1 = #1)
• total_domains = total count of all domains in the table
• domain_above = domain ranked one position above TARGET_DOMAIN (if any)
• domain_below = domain ranked one position below TARGET_DOMAIN (if any)
• gap_to_next_above = etv of domain_above − current_traffic (0 if TARGET_DOMAIN is #1)
• lead_over_next_below = current_traffic − etv of domain_below (0 if TARGET_DOMAIN is last)

3b — Competitor Trend Signals (Historical, Option 1)

For each competitor (not the target domain), call dataforseo_labs_google_historical_rank_overview:

target:          COMPETITOR_DOMAIN
location_name:   LOCATION
language_code:   en
ignore_synonyms: false

From the returned monthly array:

• Find the snapshot closest to START_DATE → extract comp_baseline_etv
• Find the snapshot closest to END_DATE → extract comp_current_etv
• Calculate: comp_trend_pct = ((comp_current_etv - comp_baseline_etv) / comp_baseline_etv) * 100

Trend badge assignment rules (±5% stability threshold):

| Condition | Badge | CSS class | |---|---|---| | comp_trend_pct > +5% | ↑ +X.X% | trend-up (green) | | comp_trend_pct < -5% | ↓ -X.X% | trend-down (red) | | -5% ≤ comp_trend_pct ≤ +5% | → Stable (X.X%) | trend-stable (gray) |

TARGET_DOMAIN trend for the competitive table must also use the same START_DATE → END_DATE window for consistency. The historical data fetched in Step 1 already contains this:

• target_table_trend_pct = ((end_date_snapshot_etv - baseline_traffic) / baseline_traffic) * 100

Where end_date_snapshot_etv is the ETV from the Step 1 historical array snapshot closest to END_DATE (not current_traffic from Step 2, which is a live figure).

Apply the same ±5% threshold rules to derive the target's trend badge.

⚠️ traffic_growth_pct from Step 2 (baseline → live) is used for the timeline cards,

delta badges, and executive summary — but NOT for the competitive table trend column.

The competitive table trend column uses target_table_trend_pct (START_DATE → END_DATE)

for all domains including the target, ensuring a consistent apples-to-apples comparison.

⚠️ Never default any competitor to "Stable" without running this calculation.

Every trend badge in the competitive table must be derived from real historical ETV data.

STEP 4 — Top Content Clusters

Call dataforseo_labs_google_relevant_pages with:

target:          TARGET_DOMAIN
location_name:   LOCATION
language_code:   en
order_by:        ["metrics.organic.etv,desc"]
limit:           3
ignore_synonyms: false

For each of the top 3 pages extract:

• page_address — shorten display URL: remove `https