traffic-agent

name

traffic-agent

description

Use to evaluate ROI on a used-machinery dealer's web presence — both their own site and the paid marketplace listings (equipt, machinepoint, surplusrecord, etc.) they're spending on. Pulls Google Analytics 4 sessions / leads and Ahrefs traffic + keyword data, divides by each channel's monthly cost, and surfaces which paid listings are actually paying for themselves and which are dead weight. Triggers on "check my traffic", "is equipt worth it", "GA report", "Ahrefs check", "which dealer site is wasting money", "lead ROI report", "where are my leads coming from", "should I keep paying for [marketplace]", "traffic vs cost", or any "is this listing fee worth it?" question. NOT for SEO content optimization (different scope — use a GEO/SEO skill if you have one).

Sales Lead Traffic Agent

The "is this $300/month listing fee actually working?" tool. Pulls real numbers from Google Analytics 4 and Ahrefs, divides by what each channel costs the dealer, and ranks paid placements by leads-per-dollar. Output: a clean "keep / cut / renegotiate" recommendation per channel.

When this fires

• "How's traffic looking this month?"
• "Is equipt worth what we're paying?"
• "Run the lead ROI report"
• "Which of my listings is dead weight?"
• "Should I renew machinepoint?"
• "Where are my leads coming from in Q1?"
• "Compare my own site to my paid listings"

First-run setup

If /mnt/user-data/uploads/.dealer_traffic_config.json doesn't exist, run setup:

1. Google Analytics 4 property — ask for the property ID (looks like properties/123456789). Tell the dealer to grant the same service account from sales-agent (claude-sheets@...) the Viewer role on the GA4 property.
2. Ahrefs API token — generate at https://app.ahrefs.com/api-keys. Paste the token; it gets cached locally (never logged or transmitted elsewhere).
3. Paid channels inventory — list every marketplace and dealer-directory the dealer is currently paying for, with:
   • Channel name (matches the marketing-agent registry where possible)
   • Monthly cost ($)
   • Referral URL or domain (equipt.com, machinepoint.com, etc.) — used for GA referral matching
   • Whether the dealer has a public store URL there
4. Lead conversion events in GA4 — which GA4 events count as a lead? Defaults: form_submit, phone_click, email_click, request_quote. The dealer can edit.

{
  "ga4_property_id": "properties/123456789",
  "ahrefs_token": "AHREFS_TOKEN_HERE",
  "own_domain": "premier-equipment.example",
  "lead_events": ["form_submit", "phone_click", "email_click", "request_quote"],
  "channels": [
    {"id": "equipt", "domain": "equipt.com", "monthly_cost_usd": 295, "store_url": "https://equipt.com/companies/..."},
    {"id": "machinepoint", "domain": "machinepoint.com", "monthly_cost_usd": 
         
         
         
           
  
   
    
    
    
  

Per-request flow

1. Date range — default last 30 days. Dealer can say "last quarter" / "last 90 days" / "year-to-date".
2. Pull GA4 numbers — scripts/ga4_client.py:
   • Sessions by sessionSource (groups referrals from equipt.com, machinepoint.com, etc.)
   • Lead events by source
   • Top landing pages
   • Direct vs. organic vs. referral split
3. Pull Ahrefs — scripts/ahrefs_client.py:
   • Organic traffic estimate for own_domain over the window
   • Keyword positions for the dealer's target keyword list
   • Backlink count delta if window > 30 days
4. Compute ROI — scripts/lead_roi.py:
   • For each paid channel: leads_attributed / monthly_cost = leads_per_dollar
   • For each paid channel: sessions_referred / monthly_cost = sessions_per_dollar
   • Compare against the dealer's own site organic baseline
   • Flag channels with zero referrals in the window (dead weight)
   • Flag channels with high session count but zero leads (driving the wrong audience)
5. Recommendation per channel:
   • Keep — leads_per_dollar above own-site baseline OR brand-awareness role and low cost
   • Renegotiate — middling performance + high cost (over $200/mo with <5 leads)
   • Cut — zero referrals in the last 90 days OR cost > 3× leads_value
6. Output — a branded PDF report (matching the past-sales-agent aesthetic) + a plain summary in chat. PDF goes to /mnt/user-data/outputs/traffic_roi_<YYYY-MM>.pdf.

Lead valuation

Default lead value: dealer-provided number ("a qualified buyer lead is worth ~$X to me"). Without that, use gross_margin_per_sale × close_rate from past-sales-agent data:

• Average margin per sale (from report_metrics.aggregate())
• Close rate estimate (default 8% for cold inbound — tunable)
• → lead_value_usd = avg_margin × close_rate

So if average margin is $7,500 and close rate is 8%, each qualified lead is worth ~$600. A $295/mo equipt subscription would need to deliver ~1 qualified lead every two months to break even on direct attribution — but most paid listings also produce value through brand presence, which the recommendation engine weights.

Anti-patterns

• ❌ Recommending "cut" on a channel based on a single bad month — always look at minimum a 90-day window before cut suggestions.
• ❌ Treating last-click attribution as truth — many marketplace leads come via direct/branded organic after seeing the listing. Always report assisted attribution if GA4 has it.
• ❌ Reporting Ahrefs traffic estimates as actual visits — they're modeled, not measured. Label clearly.
• ❌ Ignoring "no-cost" channels (Exapro free tier, LinkedIn, eBay free listings) — they're often the highest leads-per-dollar simply because the denominator is zero. Flag separately as "free-tier wins."
• ❌ Storing the Ahrefs token in version control. It lives in the cache file, never in scripts.

File map

• scripts/ga4_client.py — Google Analytics Data API v1 wrapper
• scripts/ahrefs_client.py — Ahrefs API v3 wrapper
• scripts/lead_roi.py — pulls both, computes per-channel ROI, returns dicts
• scripts/build_traffic_report.py — branded PDF generator
• references/ga4_setup.md — service account → GA4 property step-by-step
• references/ahrefs_endpoints.md — which Ahrefs endpoints the skill uses

Companion skills

• past-sales-agent — provides margin + close-rate inputs for lead valuation
• marketing-agent — channels list overlaps; both pull from .dealer_marketing_config.json where possible