@roilab/crm-cli 0.1.0 → 0.4.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 (67) hide show
  1. package/CHANGELOG.md +125 -6
  2. package/SKILL.md +256 -7
  3. package/SURFACE.txt +148 -3
  4. package/dist/bin/crm.js +26 -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 +203 -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/report.js +209 -0
  25. package/dist/src/commands/report.js.map +1 -0
  26. package/dist/src/commands/review.js +136 -0
  27. package/dist/src/commands/review.js.map +1 -1
  28. package/dist/src/commands/skill.js +836 -0
  29. package/dist/src/commands/skill.js.map +1 -0
  30. package/dist/src/commands/task.js +298 -4
  31. package/dist/src/commands/task.js.map +1 -1
  32. package/dist/src/commands/time.js +242 -0
  33. package/dist/src/commands/time.js.map +1 -0
  34. package/dist/src/lib/skillBundles.js +84 -0
  35. package/dist/src/lib/skillBundles.js.map +1 -0
  36. package/dist/src/lib/skillManifest.js +77 -0
  37. package/dist/src/lib/skillManifest.js.map +1 -0
  38. package/dist/src/lib/skillSidecar.js +69 -0
  39. package/dist/src/lib/skillSidecar.js.map +1 -0
  40. package/dist/src/lib/skillWriter.js +162 -0
  41. package/dist/src/lib/skillWriter.js.map +1 -0
  42. package/dist/src/transport/envelope.js +12 -2
  43. package/dist/src/transport/envelope.js.map +1 -1
  44. package/dist/src/transport/http.js +27 -0
  45. package/dist/src/transport/http.js.map +1 -1
  46. package/dist/src/transport/run.js +6 -0
  47. package/dist/src/transport/run.js.map +1 -1
  48. package/dist/src/types.js.map +1 -1
  49. package/dist/src/utils/server-nudge.js +57 -0
  50. package/dist/src/utils/server-nudge.js.map +1 -0
  51. package/dist/src/utils/version-check.js +68 -0
  52. package/dist/src/utils/version-check.js.map +1 -1
  53. package/package.json +2 -1
  54. package/skill-bundles/tools/ahrefs-tool/SKILL.md +134 -0
  55. package/skill-bundles/tools/brightlocal-tool/SKILL.md +154 -0
  56. package/skill-bundles/tools/dataforseo-tool/SKILL.md +118 -0
  57. package/skill-bundles/tools/google-analytics-tool/SKILL.md +143 -0
  58. package/skill-bundles/tools/google-search-console-tool/SKILL.md +133 -0
  59. package/skill-bundles/tools/local-falcon-tool/SKILL.md +142 -0
  60. package/skill-bundles/tools/localseodata-tool/SKILL.md +388 -0
  61. package/skill-bundles/tools/lsa-spy-tool/SKILL.md +113 -0
  62. package/skill-bundles/tools/screaming-frog-tool/SKILL.md +166 -0
  63. package/skill-bundles/tools/semrush-tool/SKILL.md +121 -0
  64. package/skill-bundles/tools/serpapi-tool/SKILL.md +148 -0
  65. package/skill-bundles/tools/task-preflight/SKILL.md +149 -0
  66. package/skill-bundles/tools/tool-routing/SKILL.md +59 -0
  67. package/skill-bundles/tools/whitespark-tool/SKILL.md +129 -0
@@ -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.
@@ -0,0 +1,133 @@
1
+ ---
2
+ name: google-search-console-tool
3
+ description: When the user wants to know what queries drive traffic to their site, which pages are indexed, click-through rates, organic search performance, or technical indexing issues. Trigger on "Search Console," "GSC," "what keywords am I getting traffic for," "what queries," "impressions," "click-through rate," "indexing issues," "is my page indexed," or "organic performance."
4
+ ---
5
+
6
+ # Google Search Console Tool
7
+
8
+ GSC has official and community MCP servers available. When connected, use it for ground-truth organic search performance data — this is the only tool that shows ACTUAL clicks and impressions from Google.
9
+
10
+ ## When to Use GSC vs Other Tools
11
+
12
+ | You Need | Use GSC | Use Instead |
13
+ |----------|--------|-------------|
14
+ | Actual clicks and impressions from Google | ✅ Only source of truth | — |
15
+ | What queries drive traffic to which pages | ✅ Only source of truth | — |
16
+ | Click-through rate per query/page | ✅ Only source of truth | — |
17
+ | Average position per query | ✅ Ground truth | Semrush/Ahrefs estimates |
18
+ | Is a specific page indexed? | ✅ | — |
19
+ | Core Web Vitals per page | ✅ | — |
20
+ | Crawl errors and issues | ✅ | Screaming Frog (more detailed) |
21
+ | Keyword search volume | ❌ No volume data | Semrush, DataForSEO |
22
+ | Competitor keyword data | ❌ Your site only | Semrush, Ahrefs |
23
+ | Backlink data | ❌ Very limited | Ahrefs |
24
+ | Local pack rankings | ❌ Organic only | Local Falcon |
25
+ | Citation data | ❌ | BrightLocal |
26
+
27
+ ## Critical Distinction
28
+
29
+ GSC shows **organic search performance only** — not map pack, not LSA, not ads. A business can get zero clicks in GSC but rank #1 in the local pack (because map pack clicks don't show in GSC as organic clicks). Always pair GSC data with Local Falcon map pack data for complete visibility.
30
+
31
+ ## Core Workflows
32
+
33
+ ### Location Page Performance
34
+
35
+ **When:** User wants to know how their location pages perform in organic search.
36
+
37
+ **What to pull:**
38
+ 1. Filter pages by URL containing "/locations/" or your location page pattern
39
+ 2. Get clicks, impressions, CTR, average position per page
40
+ 3. Get queries driving traffic to each location page
41
+
42
+ **How to interpret:**
43
+ - **High impressions, low clicks (low CTR)**: Title tag or meta description doesn't compel clicks — rewrite them
44
+ - **High position (>20), some impressions**: You're on page 2-3, close to breaking through — optimize content
45
+ - **Location page with zero impressions**: Page may not be indexed, or keywords don't trigger it
46
+ - **Impressions for queries you don't have a page for**: Content gap — create a page for that query
47
+
48
+ **CTR benchmarks by position (approximate):**
49
+ | Position | Expected CTR |
50
+ |----------|-------------|
51
+ | 1 | 25-35% |
52
+ | 2 | 12-18% |
53
+ | 3 | 8-12% |
54
+ | 4-5 | 5-8% |
55
+ | 6-10 | 2-5% |
56
+ | 11-20 | 0.5-2% |
57
+
58
+ If CTR is below expected for the position, the title/meta needs improvement.
59
+
60
+ ### Local Keyword Discovery
61
+
62
+ **When:** User wants to find keywords they're already getting impressions for but not optimizing.
63
+
64
+ **What to pull:**
65
+ 1. All queries with impressions, filtered to last 3 months
66
+ 2. Sort by impressions descending
67
+ 3. Look for queries containing city names, "near me," service terms
68
+
69
+ **What to look for:**
70
+ - Queries with high impressions but position 8+: Optimization targets — these have demand
71
+ - Queries with "near me" variations: Confirm GBP is optimized for these services
72
+ - Queries you rank for that you didn't expect: New keyword opportunities
73
+ - Queries with city names you don't have a page for: Location page gaps
74
+
75
+ ### Index Coverage
76
+
77
+ **When:** User asks "is my page indexed?" or location pages aren't getting traffic.
78
+
79
+ **What to check:**
80
+ 1. URL Inspection for specific pages — are they indexed?
81
+ 2. Index coverage report — any errors affecting location pages?
82
+ 3. Sitemap processing — is the sitemap submitted and processed?
83
+
84
+ **Common issues for local:**
85
+ - Location pages not in sitemap → add them
86
+ - Location pages marked "Discovered – currently not indexed" → thin content, Google didn't find them valuable enough
87
+ - Location pages blocked by robots.txt → fix robots.txt
88
+ - Location pages with "Duplicate, submitted URL not selected as canonical" → canonicalization issue between similar location pages
89
+
90
+ ### Core Web Vitals
91
+
92
+ **When:** User's pages are slow or CWV failing.
93
+
94
+ **What to check:**
95
+ 1. CWV report for location pages specifically
96
+ 2. Which pages fail LCP, FID/INP, CLS
97
+ 3. Mobile vs desktop performance
98
+
99
+ **For local:** Mobile CWV matters most — local searches are predominantly mobile. If mobile CWV fails, fix it before other optimization.
100
+
101
+ ### Content Gap Identification
102
+
103
+ **When:** Looking for new content opportunities from actual search data.
104
+
105
+ **What to pull:**
106
+ 1. Queries where you have impressions but no dedicated page
107
+ 2. Queries with high impressions but position 15+
108
+ 3. Compare queries to your existing page structure
109
+
110
+ **Example:** GSC shows 500 impressions/month for "emergency plumber Orchard Park" but you don't have a page specifically about emergency plumbing in Orchard Park → create one.
111
+
112
+ ## Key Metrics and What They Mean
113
+
114
+ | Metric | What It Is | Local SEO Context |
115
+ |--------|-----------|-------------------|
116
+ | Clicks | Actual clicks from Google to your site | The number that matters — this is real traffic |
117
+ | Impressions | Times your page appeared in search results | Shows demand even if you're not getting clicks |
118
+ | CTR | Clicks ÷ Impressions | Low CTR = title/meta issue. Compare to position benchmarks |
119
+ | Average Position | Average ranking position for a query | Remember: this is organic only, not map pack |
120
+
121
+ ## What to Do Next
122
+
123
+ | What You Found | Next Action | Skill |
124
+ |----------------|-------------|-------|
125
+ | Location pages with low CTR | Rewrite title tags and meta descriptions | `local-landing-pages` |
126
+ | Queries without dedicated pages | Create pages targeting those queries | `local-landing-pages` |
127
+ | Location pages not indexed | Fix technical issues (thin content, canonical, sitemap) | `local-seo-audit`, `screaming-frog-tool` |
128
+ | CWV failing on mobile | Fix page speed issues | `local-seo-audit` |
129
+ | Good organic performance, want to see map pack too | Run Local Falcon scans | `local-falcon-tool` |
130
+ | Competitor analysis needed | GSC is your-site only — use Semrush for competitor data | `semrush-tool` |
131
+ | Need this in a client report | Include GSC data in performance reports | `local-reporting` |
132
+
133
+ **Default next step:** GSC is the truth layer. Start every performance analysis with GSC data, then supplement with other tools. If GSC shows no impressions for a keyword, either the page doesn't exist, isn't indexed, or doesn't target the keyword properly.