@roilab/crm-cli 0.1.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/CHANGELOG.md +195 -25
  2. package/SKILL.md +256 -7
  3. package/SURFACE.txt +237 -69
  4. package/dist/bin/crm.js +28 -2
  5. package/dist/bin/crm.js.map +1 -1
  6. package/dist/src/commands/access.js +104 -0
  7. package/dist/src/commands/access.js.map +1 -0
  8. package/dist/src/commands/brief.js +52 -0
  9. package/dist/src/commands/brief.js.map +1 -0
  10. package/dist/src/commands/chat.js +220 -0
  11. package/dist/src/commands/chat.js.map +1 -0
  12. package/dist/src/commands/commands.js +89 -0
  13. package/dist/src/commands/commands.js.map +1 -0
  14. package/dist/src/commands/comment.js +1 -0
  15. package/dist/src/commands/comment.js.map +1 -1
  16. package/dist/src/commands/generic.js +335 -5
  17. package/dist/src/commands/generic.js.map +1 -1
  18. package/dist/src/commands/integrations.js +236 -0
  19. package/dist/src/commands/integrations.js.map +1 -0
  20. package/dist/src/commands/mention.js +139 -0
  21. package/dist/src/commands/mention.js.map +1 -0
  22. package/dist/src/commands/options.js +21 -1
  23. package/dist/src/commands/options.js.map +1 -1
  24. package/dist/src/commands/rank.js +300 -0
  25. package/dist/src/commands/rank.js.map +1 -0
  26. package/dist/src/commands/report.js +209 -0
  27. package/dist/src/commands/report.js.map +1 -0
  28. package/dist/src/commands/review.js +136 -0
  29. package/dist/src/commands/review.js.map +1 -1
  30. package/dist/src/commands/skill.js +1005 -0
  31. package/dist/src/commands/skill.js.map +1 -0
  32. package/dist/src/commands/task.js +298 -4
  33. package/dist/src/commands/task.js.map +1 -1
  34. package/dist/src/commands/time.js +242 -0
  35. package/dist/src/commands/time.js.map +1 -0
  36. package/dist/src/lib/skillBundles.js +84 -0
  37. package/dist/src/lib/skillBundles.js.map +1 -0
  38. package/dist/src/lib/skillManifest.js +77 -0
  39. package/dist/src/lib/skillManifest.js.map +1 -0
  40. package/dist/src/lib/skillSidecar.js +69 -0
  41. package/dist/src/lib/skillSidecar.js.map +1 -0
  42. package/dist/src/lib/skillWriter.js +162 -0
  43. package/dist/src/lib/skillWriter.js.map +1 -0
  44. package/dist/src/transport/envelope.js +12 -2
  45. package/dist/src/transport/envelope.js.map +1 -1
  46. package/dist/src/transport/http.js +27 -0
  47. package/dist/src/transport/http.js.map +1 -1
  48. package/dist/src/transport/run.js +6 -0
  49. package/dist/src/transport/run.js.map +1 -1
  50. package/dist/src/types.js.map +1 -1
  51. package/dist/src/utils/server-nudge.js +57 -0
  52. package/dist/src/utils/server-nudge.js.map +1 -0
  53. package/dist/src/utils/version-check.js +68 -0
  54. package/dist/src/utils/version-check.js.map +1 -1
  55. package/package.json +58 -57
  56. package/skill-bundles/tools/ahrefs-tool/SKILL.md +134 -0
  57. package/skill-bundles/tools/brightlocal-tool/SKILL.md +154 -0
  58. package/skill-bundles/tools/dataforseo-tool/SKILL.md +118 -0
  59. package/skill-bundles/tools/google-analytics-tool/SKILL.md +143 -0
  60. package/skill-bundles/tools/google-search-console-tool/SKILL.md +133 -0
  61. package/skill-bundles/tools/local-falcon-tool/SKILL.md +142 -0
  62. package/skill-bundles/tools/localseodata-tool/SKILL.md +388 -0
  63. package/skill-bundles/tools/lsa-spy-tool/SKILL.md +113 -0
  64. package/skill-bundles/tools/screaming-frog-tool/SKILL.md +166 -0
  65. package/skill-bundles/tools/semrush-tool/SKILL.md +121 -0
  66. package/skill-bundles/tools/serpapi-tool/SKILL.md +148 -0
  67. package/skill-bundles/tools/task-preflight/SKILL.md +149 -0
  68. package/skill-bundles/tools/tool-routing/SKILL.md +59 -0
  69. package/skill-bundles/tools/whitespark-tool/SKILL.md +129 -0
@@ -0,0 +1,134 @@
1
+ ---
2
+ name: ahrefs-tool
3
+ description: When the user wants backlink analysis, link gap analysis, competitor link profiles, referring domain data, or link building research. Trigger on "backlinks," "who links to," "link profile," "referring domains," "link gap," "Ahrefs," "link building research," or "why do they outrank me" (often a link authority issue).
4
+ ---
5
+
6
+ # Ahrefs Tool
7
+
8
+ > **Note:** LocalSEOData (`localseodata-tool`) now has `backlink_summary` and `backlink_gap` endpoints. Use LocalSEOData for quick backlink overviews and gap analysis. Ahrefs remains the preferred tool for deep link analysis — anchor text profiles, lost/new links, referring domain details, and content gap analysis.
9
+
10
+ Ahrefs has an official MCP server. When connected, use it for backlink analysis and link-focused competitive intelligence. Ahrefs has the largest backlink index — it's the authoritative source for link data.
11
+
12
+ ## When to Use Ahrefs vs Other Tools
13
+
14
+ | You Need | Use Ahrefs | Use Instead |
15
+ |----------|-----------|-------------|
16
+ | Backlink profile for a domain | ✅ Best backlink database | — |
17
+ | Referring domains count/list | ✅ | — |
18
+ | Link gap (who links to competitor but not you) | ✅ Best for this | — |
19
+ | Lost/broken backlinks | ✅ | — |
20
+ | Anchor text analysis | ✅ | — |
21
+ | Keyword search volume | ⚠️ Can do it | Semrush (better keyword tool) |
22
+ | Keyword gap analysis | ⚠️ Can do it | Semrush (preferred for keywords) |
23
+ | Content Explorer (find linkable content) | ✅ Unique to Ahrefs | — |
24
+ | Technical site audit | ⚠️ Has one | Screaming Frog (more detailed) |
25
+ | SERP data | ❌ | SerpAPI |
26
+ | Local pack rankings | ❌ | Local Falcon |
27
+ | Citation data | ❌ | BrightLocal |
28
+
29
+ ## Core Workflows
30
+
31
+ ### Analyze a Business's Link Profile
32
+
33
+ **When:** User asks "why aren't we ranking?" or needs to understand link authority.
34
+
35
+ **What to pull:**
36
+ 1. **Domain Rating (DR)**: Overall link authority score (0-100)
37
+ 2. **Referring Domains**: Unique domains linking to the site (more important than total backlinks)
38
+ 3. **Backlink list**: Individual backlinks with source, anchor text, follow/nofollow, first seen date
39
+ 4. **Referring domains by DR**: Quality distribution of linking domains
40
+
41
+ **How to interpret for local:**
42
+ - DR 20-40: Typical for local businesses
43
+ - DR 40-60: Strong local site, likely has press or industry links
44
+ - DR 60+: Very strong, probably a brand or large multi-location
45
+ - Referring domains matter more than total backlinks (10 links from 10 domains > 50 links from 2 domains)
46
+ - Local relevance matters: 1 link from a local news site > 10 links from random blogs
47
+
48
+ **Red flags:**
49
+ - Sudden spike in referring domains (could be spam or negative SEO)
50
+ - Mostly nofollow links (limited authority transfer)
51
+ - Anchor text heavily keyword-stuffed (penalty risk)
52
+ - Links from irrelevant or low-quality sites
53
+
54
+ ### Link Gap Analysis (Competitor vs You)
55
+
56
+ **When:** User wants to find link building opportunities from competitor profiles.
57
+
58
+ **What to pull:**
59
+ 1. **Link Intersect**: Domains that link to competitors but NOT to user's site
60
+ 2. Filter by DR 20+ (skip low-quality)
61
+ 3. Filter by dofollow links
62
+ 4. Sort by referring domain authority
63
+
64
+ **What to look for:**
65
+ - Local directories linking to competitors but not you → citation opportunity
66
+ - Local news/media sites → PR opportunity
67
+ - Industry associations or organizations → membership/sponsorship opportunity
68
+ - Local blogs or community sites → content/relationship opportunity
69
+ - .edu or .gov sites → high authority, worth extra effort
70
+
71
+ **How to prioritize opportunities:**
72
+ 1. Local relevance (local site > random site)
73
+ 2. Domain authority (DR 30+ preferred)
74
+ 3. Dofollow status (dofollow > nofollow for SEO, but nofollow still has value)
75
+ 4. Achievability (directory listings are easy, editorial links take effort)
76
+
77
+ ### Lost Link Recovery
78
+
79
+ **When:** Rankings dropped and you suspect link loss, or routine maintenance.
80
+
81
+ **What to pull:**
82
+ 1. **Lost backlinks** (filtered by recent timeframe)
83
+ 2. Filter by referring domain DR 20+
84
+ 3. Check if the linking page is gone (404) or the link was removed
85
+
86
+ **What to do:**
87
+ - Page 404'd → Reach out and ask to update the link
88
+ - Link removed → Understand why (content changed? contact changed?)
89
+ - Domain expired → Check if link was valuable enough to pursue alternative
90
+ - High-DR losses → Priority recovery targets
91
+
92
+ ### Anchor Text Analysis
93
+
94
+ **When:** Checking for over-optimization or understanding link profile health.
95
+
96
+ **What healthy local anchor text looks like:**
97
+ - Brand name (40-60%): "Smith Plumbing," "smithplumbing.com"
98
+ - Generic (15-25%): "click here," "website," "learn more"
99
+ - Location-based (10-20%): "plumber in Buffalo," "Buffalo NY plumbing"
100
+ - Exact match keywords (under 10%): "emergency plumber" — too much of this is a penalty risk
101
+
102
+ ### Content Explorer (Find Linkable Content Ideas)
103
+
104
+ **When:** User needs content ideas that attract links.
105
+
106
+ - Search for topics in your industry + location
107
+ - Find content that got the most links in your space
108
+ - Analyze what made it linkable (data, tools, guides, local research)
109
+ - Create something better for your market
110
+
111
+ ## Key Metrics and What They Mean
112
+
113
+ | Metric | What It Is | Local SEO Context |
114
+ |--------|-----------|-------------------|
115
+ | Domain Rating (DR) | Ahrefs' authority score (0-100) | Compare to local competitors, not national brands |
116
+ | Referring Domains | Unique domains linking to you | The #1 link metric — more unique domains = more authority |
117
+ | URL Rating (UR) | Authority of a specific page | Useful for comparing location page authority |
118
+ | Dofollow % | Percentage of links passing authority | Below 50% dofollow is weak |
119
+ | Anchor text distribution | What text is used in links | Over-optimized anchors can trigger penalties |
120
+ | Link velocity | Rate of new links acquired | Steady growth is healthy, spikes are suspicious |
121
+
122
+ ## What to Do Next
123
+
124
+ | What You Found | Next Action | Skill |
125
+ |----------------|-------------|-------|
126
+ | Competitor has 3x more referring domains | Build a link acquisition strategy | `local-link-building` |
127
+ | Found link gap opportunities (directories) | These are citation opportunities | `local-citations` |
128
+ | Found link gap opportunities (editorial/media) | Build targeted outreach campaigns | `local-link-building` |
129
+ | Anchor text over-optimized | Diversify with brand and generic anchors going forward | `local-link-building` |
130
+ | Lost high-value links | Outreach to recover, then build replacements | `local-link-building` |
131
+ | Link profile is fine but still not ranking locally | Links aren't the issue — check GBP, reviews, proximity | `geogrid-analysis`, `gbp-optimization` |
132
+ | Need this data in a client report | Include link profile comparison in deliverables | `client-deliverables` |
133
+
134
+ **Default next step:** Link analysis always raises the question "is this a link problem or something else?" If the link profile is comparable to competitors, the issue is likely GBP, reviews, or relevance — not links.
@@ -0,0 +1,154 @@
1
+ ---
2
+ name: brightlocal-tool
3
+ description: When the user wants citation audits, citation building, review monitoring across platforms, GBP audit scoring, or white-label local SEO reports. Trigger on "citation audit," "check my citations," "NAP consistency," "where am I listed," "BrightLocal," "directory listings," "review monitoring," or "client report."
4
+ ---
5
+
6
+ # BrightLocal Tool
7
+
8
+ > **Note:** LocalSEOData (`localseodata-tool`) now covers citation audits (`citation_audit`), multi-platform reviews (`multi_platform_reviews`), and reputation auditing (`reputation_audit`). Use LocalSEOData as default for data pulls. BrightLocal remains useful for citation building/submission and review monitoring dashboards.
9
+
10
+ BrightLocal has an official MCP server. When connected, use it for citation management, review aggregation, GBP auditing, and client reporting. This is your primary citation intelligence tool.
11
+
12
+ ## When to Use BrightLocal vs Other Tools
13
+
14
+ | You Need | Use BrightLocal | Use Instead |
15
+ |----------|----------------|-------------|
16
+ | Citation audit (where is this business listed?) | ✅ Best for this | — |
17
+ | NAP consistency check across directories | ✅ Best for this | — |
18
+ | Citation building (submit to directories) | ✅ Managed service | Whitespark (alternative) |
19
+ | Review monitoring across multiple platforms | ✅ | — |
20
+ | GBP profile audit/scoring | ✅ | — |
21
+ | White-label client reports | ✅ | — |
22
+ | Keyword search volume | ❌ | Semrush, Ahrefs |
23
+ | Backlink analysis | ❌ | Ahrefs |
24
+ | Geogrid rankings | ❌ | Local Falcon |
25
+ | Live SERP data | ❌ | SerpAPI |
26
+ | Technical site audit | ❌ | Screaming Frog |
27
+
28
+ ## Core Workflows
29
+
30
+ ### Citation Audit
31
+
32
+ **When:** User asks "where am I listed?" or "are my citations consistent?" or this is part of a local SEO audit.
33
+
34
+ **What to pull:**
35
+ 1. **Citation Tracker**: All found citations for the business
36
+ 2. **Accuracy scores**: NAP match percentage per directory
37
+ 3. **Directory coverage**: Which directories have listings vs which don't
38
+ 4. **Duplicate detection**: Multiple listings on the same directory
39
+
40
+ **How to interpret:**
41
+ - Accuracy score above 90%: Good — minor fixes needed
42
+ - Accuracy score 70-90%: Moderate issues — old phone numbers, address variations
43
+ - Accuracy score below 70%: Serious problems — inconsistent data confusing Google
44
+ - Missing from major directories (Google, Yelp, Facebook, Apple Maps, Bing): Critical gaps
45
+ - Duplicates on same directory: Splitting ranking signals — need to merge or remove
46
+
47
+ **Priority directories to check:**
48
+ 1. Google Business Profile (the #1 citation)
49
+ 2. Apple Maps / Apple Business Connect
50
+ 3. Bing Places
51
+ 4. Yelp
52
+ 5. Facebook
53
+ 6. Industry-specific directories (Healthgrades, Avvo, Angi, etc.)
54
+ 7. Data aggregators (Data Axle, Neustar/Localeze, Foursquare)
55
+
56
+ ### Citation Building
57
+
58
+ **When:** Audit reveals missing directories or user needs new citations built.
59
+
60
+ BrightLocal offers managed citation building — they submit to directories on your behalf.
61
+
62
+ **What to specify:**
63
+ - Business NAP (must be exactly consistent with GBP)
64
+ - Categories
65
+ - Description
66
+ - Photos
67
+ - Target directories (or let BrightLocal recommend based on industry)
68
+
69
+ **Timeline:** Most submissions process in 2-4 weeks. Some directories take longer.
70
+
71
+ **After building:** Re-audit in 6-8 weeks to verify submissions were accepted and data is accurate.
72
+
73
+ ### Review Monitoring
74
+
75
+ **When:** User wants to track reviews across Google, Yelp, Facebook, and industry platforms.
76
+
77
+ **What to pull:**
78
+ 1. **Review feed**: All reviews across connected platforms
79
+ 2. **Review count and rating per platform**
80
+ 3. **New review alerts**: Recent reviews needing responses
81
+ 4. **Sentiment trends**: Rating direction over time
82
+
83
+ **What to look for:**
84
+ - Platforms where reviews are accumulating but no one is responding
85
+ - Rating discrepancies between platforms (4.8 on Google but 3.2 on Yelp — investigate)
86
+ - Review velocity compared to competitors
87
+ - Negative review patterns (recurring complaints = operational issue)
88
+
89
+ ### GBP Audit
90
+
91
+ **When:** Need a quick health check on the Google Business Profile.
92
+
93
+ **What BrightLocal checks:**
94
+ - Profile completeness (photos, description, hours, categories, attributes)
95
+ - NAP consistency with website and citations
96
+ - Review response rate
97
+ - Post activity
98
+ - Category accuracy
99
+
100
+ **Scoring:** BrightLocal generates an audit score. Use this as a starting point, then apply `gbp-optimization` skill for the detailed playbook.
101
+
102
+ ### Client Reporting
103
+
104
+ **When:** Need to generate a client-facing report.
105
+
106
+ **What to include:**
107
+ - Citation health score and changes
108
+ - Review summary (count, rating, new reviews)
109
+ - GBP audit score
110
+ - Ranking data (if using BrightLocal's rank tracker)
111
+
112
+ **Note:** BrightLocal reports are white-labelable. For agencies, brand them before sending.
113
+
114
+ ## Interpreting Citation Data
115
+
116
+ ### NAP Consistency Scoring
117
+
118
+ | Score | Status | Action |
119
+ |-------|--------|--------|
120
+ | 95-100% | Excellent | Monitor quarterly |
121
+ | 85-94% | Good | Fix remaining inconsistencies |
122
+ | 70-84% | Needs work | Prioritize top directories, fix data aggregators |
123
+ | Below 70% | Critical | Full citation cleanup needed before other optimization |
124
+
125
+ ### Common Citation Issues
126
+
127
+ | Issue | What Causes It | How to Fix |
128
+ |-------|---------------|-----------|
129
+ | Old phone number | Business changed numbers, aggregators have old data | Update aggregators first (Data Axle, Neustar, Foursquare), then individual directories |
130
+ | Old address | Business moved, aggregators propagated old address | Same — fix at aggregator level |
131
+ | Name variations | "Smith Plumbing" vs "Smith Plumbing LLC" vs "Smith's Plumbing" | Standardize to match GBP exactly |
132
+ | Duplicate listings | Multiple submissions over time, or auto-generated listings | Claim and merge or request removal |
133
+ | Wrong category | Directory auto-assigned category | Manually update on each directory |
134
+
135
+ ### Aggregator Priority
136
+
137
+ Fix data aggregators FIRST — they feed data to hundreds of downstream directories:
138
+ 1. **Data Axle** (formerly Infogroup) — feeds the most directories
139
+ 2. **Neustar/Localeze** — second-largest aggregator
140
+ 3. **Foursquare** — feeds Apple Maps and many apps
141
+ 4. **Yelp** — both a directory and a data source for Apple Maps
142
+
143
+ ## What to Do Next
144
+
145
+ | What You Found | Next Action | Skill |
146
+ |----------------|-------------|-------|
147
+ | NAP inconsistencies across directories | Fix aggregators first, then individual directories | `local-citations` |
148
+ | Missing from key directories | Build citations on missing directories | `local-citations` |
149
+ | Low review count on Google | Build review generation strategy | `review-management` |
150
+ | GBP audit shows incomplete profile | Optimize the profile | `gbp-optimization` |
151
+ | Citations clean but still not ranking | Citations aren't the issue — check other factors | `geogrid-analysis`, `local-seo-audit` |
152
+ | Need to present findings to client | Package citation report with recommendations | `client-deliverables` |
153
+
154
+ **Default next step:** Citation cleanup is a slow process (4-8 weeks for aggregator changes to propagate). Start the cleanup, then work on other optimization while waiting.
@@ -0,0 +1,118 @@
1
+ ---
2
+ name: dataforseo-tool
3
+ description: When the user needs bulk SERP data, local pack data at scale, keyword volumes for hundreds of terms at once, Google Maps business data programmatically, or is building custom local SEO tools/dashboards. Trigger on "bulk keyword data," "SERP data at scale," "DataForSEO," "Google Maps API data," "business data API," or when any other keyword/SERP tool would be too slow for the volume needed.
4
+ ---
5
+
6
+ # DataForSEO Tool
7
+
8
+ > **Note:** LocalSEOData (`localseodata-tool`) is built on DataForSEO and provides a simplified, pre-assembled layer for most local SEO data needs. Use LocalSEOData as default. DataForSEO is still the right choice for massive bulk operations (1000+ queries) or custom pipeline builds that need raw API access.
9
+
10
+ DataForSEO has an official MCP server. When connected, use it for bulk SEO data operations — SERP results, keyword volumes, business data, and backlinks at scale. This is your bulk data and custom tooling API.
11
+
12
+ ## When to Use DataForSEO vs Other Tools
13
+
14
+ | You Need | Use DataForSEO | Use Instead |
15
+ |----------|---------------|-------------|
16
+ | Keyword volume for 500+ terms at once | ✅ Best for bulk | Semrush (for smaller batches) |
17
+ | SERP results for many keyword+location combos | ✅ Best for scale | SerpAPI (for individual queries) |
18
+ | Google Maps business data programmatically | ✅ | — |
19
+ | Google reviews for a business via API | ✅ | — |
20
+ | Local pack monitoring at scale (custom build) | ✅ | Local Falcon (turnkey solution) |
21
+ | Backlink data | ⚠️ Has it, smaller index | Ahrefs (preferred) |
22
+ | Single keyword research | ❌ Overkill | Semrush |
23
+ | Single SERP check | ❌ Overkill | SerpAPI |
24
+ | Citation audit | ❌ | BrightLocal |
25
+ | Geogrid ranking visualization | ❌ | Local Falcon |
26
+
27
+ ## When DataForSEO Is the Right Choice
28
+
29
+ DataForSEO is the right tool when:
30
+ - **Volume**: You need data for 100+ keywords, 50+ locations, or 20+ competitors at once
31
+ - **Custom builds**: You're building a dashboard, tool, or automated system
32
+ - **Programmatic access**: You need structured data for processing, not human reading
33
+ - **Cost efficiency at scale**: Pay-per-task pricing beats subscription tools for bulk operations
34
+
35
+ DataForSEO is NOT the right tool when:
36
+ - You need one quick answer (use SerpAPI or Semrush)
37
+ - You need a turnkey product with visualizations (use Local Falcon, BrightLocal)
38
+ - You need editorial link analysis (use Ahrefs)
39
+
40
+ ## Core Workflows
41
+
42
+ ### Bulk Local Keyword Volume
43
+
44
+ **When:** Have a large keyword list and need volume data for all of them.
45
+
46
+ **Endpoints:**
47
+ - `keywords_data/google_ads/search_volume` — volume, CPC, competition for keyword list
48
+ - `keywords_data/google_ads/keywords_for_site` — keywords a domain gets traffic for
49
+
50
+ **Use case:** You've generated 200 service+city keyword combinations from `local-keyword-research`. Instead of checking each one in Semrush, batch them through DataForSEO.
51
+
52
+ **What you get:** Volume, CPC, competition level, monthly trends for each keyword.
53
+
54
+ ### Bulk SERP Data
55
+
56
+ **When:** Need to check local pack presence across many keywords or locations.
57
+
58
+ **Endpoints:**
59
+ - `serp/google/organic/live` — full SERP with local pack
60
+ - `serp/google/maps/live` — Google Maps results
61
+ - `serp/google/local_finder/live` — local finder specifically
62
+
63
+ **Use case:** Check 50 keywords across 10 cities to see which trigger local packs and who appears in them. That's 500 SERP checks — impossible manually, trivial via DataForSEO.
64
+
65
+ **What to extract:**
66
+ - Does a local pack appear? (local intent confirmation)
67
+ - Who's in the local pack? (competitor identification)
68
+ - Are ads present? (commercial value)
69
+ - AI Overview present? (content optimization signal)
70
+
71
+ ### Google Business Data
72
+
73
+ **When:** Need GBP information about competitors or a market programmatically.
74
+
75
+ **Endpoints:**
76
+ - `business_data/google/my_business_info` — GBP details (name, address, categories, hours, photos, etc.)
77
+ - `business_data/google/reviews` — Google reviews with text, rating, date
78
+
79
+ **Use case:**
80
+ - Pull GBP data for top 20 competitors in a market to compare categories, review counts, ratings
81
+ - Extract reviews for sentiment analysis
82
+ - Monitor competitor GBP changes over time
83
+
84
+ ### Custom Local Rank Monitoring
85
+
86
+ **When:** Building a custom ranking tool or dashboard instead of using Local Falcon.
87
+
88
+ **Approach:**
89
+ 1. Define grid of coordinates for the service area
90
+ 2. For each coordinate, run `serp/google/maps/live` with target keyword
91
+ 3. Parse results to find target business position at each point
92
+ 4. Aggregate into ARP/SoLV-style metrics
93
+ 5. Schedule to run weekly/monthly
94
+
95
+ **When to build custom vs use Local Falcon:**
96
+ - Local Falcon: Turnkey, visual, campaign management, client-shareable reports
97
+ - DataForSEO custom: Full control, custom metrics, integrates into your own systems, cheaper at very high volume
98
+
99
+ ## Pricing Awareness
100
+
101
+ - Pay-per-task model — each API call costs credits
102
+ - SERP tasks: ~$0.002-0.005 per result
103
+ - Keyword data: ~$0.05 per batch of keywords
104
+ - Business data: ~$0.005 per result
105
+ - Always estimate total cost before running bulk operations
106
+ - Use async endpoints for large batches (submit tasks, poll for results)
107
+
108
+ ## What to Do Next
109
+
110
+ | What You Got | Next Action | Skill |
111
+ |--------------|-------------|-------|
112
+ | Bulk keyword volumes | Group by service, map to pages, prioritize by volume × intent | `local-keyword-research` |
113
+ | SERP data showing local pack presence | Focus GBP optimization on keywords with local packs | `gbp-optimization` |
114
+ | Competitor GBP data | Analyze category usage, review benchmarks, service coverage | `local-competitor-analysis` |
115
+ | Competitor reviews extracted | Analyze for sentiment themes, common complaints/praise | `review-management` |
116
+ | Custom ranking data | Interpret using geogrid analysis framework | `geogrid-analysis` |
117
+
118
+ **Default next step:** DataForSEO gives you raw data. Always pair it with an analysis skill to turn data into decisions.
@@ -0,0 +1,143 @@
1
+ ---
2
+ name: google-analytics-tool
3
+ description: When the user wants traffic data, conversion tracking, user behavior on location pages, GBP traffic attribution, or geographic traffic patterns. Trigger on "Google Analytics," "GA4," "traffic," "conversions," "how many leads," "phone calls," "form submissions," "where is my traffic coming from," or "is my website converting."
4
+ ---
5
+
6
+ # Google Analytics (GA4) Tool
7
+
8
+ GA4 has an official MCP server from Google. When connected, use it for website traffic analysis, conversion attribution, and user behavior data. GA4 answers "what happens AFTER someone finds you."
9
+
10
+ ## When to Use GA4 vs Other Tools
11
+
12
+ | You Need | Use GA4 | Use Instead |
13
+ |----------|--------|-------------|
14
+ | Traffic to location pages | ✅ | — |
15
+ | Conversion tracking (calls, forms, bookings) | ✅ | — |
16
+ | Traffic source attribution (organic vs paid vs GBP) | ✅ | — |
17
+ | Geographic traffic patterns | ✅ | — |
18
+ | User behavior (bounce rate, engagement, time on page) | ✅ | — |
19
+ | GBP-specific traffic (via UTM) | ✅ | — |
20
+ | What keywords people searched to find you | ❌ Very limited | GSC (query data) |
21
+ | Search rankings | ❌ | Local Falcon, Semrush |
22
+ | Backlinks | ❌ | Ahrefs |
23
+ | SERP features | ❌ | SerpAPI |
24
+
25
+ ## Critical Distinction
26
+
27
+ GA4 shows what happens ON YOUR WEBSITE. It does NOT show:
28
+ - GBP interactions that don't reach your website (calls from GBP, directions from GBP, map views)
29
+ - Map pack clicks that go to the GBP profile, not the website
30
+ - Local Falcon/ranking data
31
+
32
+ For complete local performance: GA4 (website) + GSC (organic queries) + GBP Insights (profile interactions) + Local Falcon (map rankings).
33
+
34
+ ## Core Workflows
35
+
36
+ ### Location Page Traffic Analysis
37
+
38
+ **When:** User asks "how are my location pages performing?" or "which locations get the most traffic?"
39
+
40
+ **What to pull:**
41
+ 1. Landing page report filtered to location page URLs
42
+ 2. Metrics: Sessions, users, engaged sessions, engagement rate, conversions
43
+ 3. Compare across location pages
44
+
45
+ **How to interpret:**
46
+ - Location page with high traffic but low engagement: Content doesn't match what visitors expect — check title alignment
47
+ - Location page with high engagement but low conversions: Missing or weak CTA (call button, form, booking link)
48
+ - Location page with no traffic: Not indexed (check GSC) or no keyword targeting (check `local-keyword-research`)
49
+ - Big traffic differences between location pages: Might reflect market size, or some pages are better optimized
50
+
51
+ ### Conversion Tracking
52
+
53
+ **When:** User asks "how many leads am I getting?" or wants to measure ROI.
54
+
55
+ **Key local conversions to track:**
56
+ | Conversion Event | How to Track | Setup Required |
57
+ |-----------------|-------------|----------------|
58
+ | Phone calls (click-to-call) | Event on `tel:` link clicks | Yes — event must be configured |
59
+ | Form submissions | Event on form submit/thank-you page | Yes — event or thank-you page trigger |
60
+ | Direction requests | Event on directions link clicks | Yes — event on link |
61
+ | Booking/scheduling | Event on booking completion | Yes — depends on booking system |
62
+ | Chat initiated | Event on chat widget open | Yes — event on widget |
63
+
64
+ **If conversions aren't set up:** Tell the user. GA4 doesn't track conversions automatically. Without configured events, you can only report traffic, not leads.
65
+
66
+ **What to look for:**
67
+ - Conversion rate per traffic source (organic vs paid vs direct vs referral)
68
+ - Conversion rate per location page
69
+ - Which pages generate the most conversions (not just traffic)
70
+ - Conversion trends over time (improving or declining?)
71
+
72
+ ### GBP Traffic Attribution
73
+
74
+ **When:** User wants to know how much traffic comes specifically from their Google Business Profile.
75
+
76
+ **How it works:** GBP website links should include UTM parameters. Common patterns:
77
+ - `utm_source=google&utm_medium=organic&utm_campaign=gbp`
78
+ - `utm_source=gmb` (older convention)
79
+
80
+ **What to pull:**
81
+ 1. Filter by source/medium matching GBP UTM parameters
82
+ 2. Sessions, users, conversions from GBP specifically
83
+ 3. Compare GBP traffic to overall organic traffic
84
+
85
+ **If no UTM tracking:** Most businesses don't set this up. Recommend adding UTM parameters to the GBP website URL so future data can be attributed.
86
+
87
+ ### Geographic Traffic Analysis
88
+
89
+ **When:** User wants to know where their website visitors are located.
90
+
91
+ **What to pull:**
92
+ 1. Geographic report by city/region
93
+ 2. Filter to organic traffic only
94
+ 3. Compare against service area
95
+
96
+ **How to interpret for local:**
97
+ - Traffic concentrated in one city but business serves a wider area: Need service area pages for other cities
98
+ - Traffic from cities outside service area: Content attracting non-local visitors (may or may not be useful)
99
+ - No traffic from a city in the service area: No content targeting that area, or not ranking there
100
+
101
+ ### Traffic Source Comparison
102
+
103
+ **When:** User wants to understand their traffic mix.
104
+
105
+ **Pull traffic by source/medium:**
106
+ - Organic search (Google/Bing) → SEO working
107
+ - Direct → Brand awareness / repeat visitors
108
+ - Referral → Links from other sites sending traffic
109
+ - Paid search → Google Ads / PPC
110
+ - Social → Social media channels
111
+
112
+ **Healthy local business traffic mix:**
113
+ - Organic: 40-60% (should be the largest source)
114
+ - Direct: 20-30% (brand recognition)
115
+ - Referral: 5-15% (healthy backlink profile)
116
+ - Paid: varies by budget
117
+ - If organic is under 30%, SEO needs work
118
+
119
+ ## Key Metrics and What They Mean
120
+
121
+ | Metric | What It Is | Local SEO Context |
122
+ |--------|-----------|-------------------|
123
+ | Sessions | Website visits | Total demand reaching your site |
124
+ | Engaged Sessions | Sessions with meaningful interaction | More important than raw sessions |
125
+ | Engagement Rate | Engaged sessions ÷ Total sessions | Below 50% on location pages = content problem |
126
+ | Conversions | Completed goal actions | THE metric — everything else is a means to this |
127
+ | Conversion Rate | Conversions ÷ Sessions | Benchmark: 3-5% for local service businesses |
128
+ | Bounce Rate | Sessions with no interaction | GA4 bounce = not engaged. High bounce on location pages = bad signal |
129
+ | Average Engagement Time | Time actively on page | Under 30 seconds = content isn't connecting |
130
+
131
+ ## What to Do Next
132
+
133
+ | What You Found | Next Action | Skill |
134
+ |----------------|-------------|-------|
135
+ | Location pages with low traffic | Check GSC for indexing, then check keyword targeting | `google-search-console-tool`, `local-keyword-research` |
136
+ | Traffic but no conversions | Add/fix CTAs, forms, click-to-call | `local-landing-pages` |
137
+ | No conversion tracking set up | Configure GA4 events before anything else | Technical setup needed |
138
+ | GBP traffic not being tracked | Add UTM parameters to GBP website URL | `gbp-optimization` |
139
+ | Good traffic from organic but bad conversion rate | Landing page content/design issue | `local-landing-pages` |
140
+ | Geographic gaps in traffic | Build location pages for underserved cities | `local-landing-pages`, `service-area-seo` |
141
+ | Need this in a client report | Include traffic and conversion data in reports | `local-reporting` |
142
+
143
+ **Default next step:** Traffic without conversion tracking is vanity metrics. If GA4 events aren't configured, that's the first thing to fix — before any SEO work, you need to be able to measure results.