@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,166 @@
1
+ ---
2
+ name: screaming-frog-tool
3
+ description: When the user wants a technical site audit, crawl data analysis, location page quality checks, duplicate content detection, schema validation at scale, or internal linking analysis. Trigger on "Screaming Frog," "site crawl," "technical audit," "crawl data," "broken links," "duplicate content," "location page audit," or when analyzing exported crawl CSV/Excel files.
4
+ ---
5
+
6
+ # Screaming Frog Tool
7
+
8
+ Screaming Frog is a desktop crawler with community-built MCP servers available. Even without MCP, the agent can analyze exported crawl data (CSV/Excel). This is your primary technical SEO audit tool.
9
+
10
+ ## When to Use Screaming Frog vs Other Tools
11
+
12
+ | You Need | Use Screaming Frog | Use Instead |
13
+ |----------|-------------------|-------------|
14
+ | Full technical site crawl | ✅ Most detailed crawler | Semrush site audit (lighter) |
15
+ | Location page quality audit at scale | ✅ Best for this | — |
16
+ | Custom data extraction (NAP, schema fields) | ✅ Unique capability | — |
17
+ | Duplicate content detection | ✅ | — |
18
+ | Internal linking analysis | ✅ | — |
19
+ | Redirect chain detection | ✅ | — |
20
+ | Schema validation per page | ✅ Custom extraction | — |
21
+ | Missing titles/metas across hundreds of pages | ✅ | — |
22
+ | Keyword rankings | ❌ | Local Falcon, Semrush |
23
+ | Backlink data | ❌ | Ahrefs |
24
+ | Search traffic data | ❌ | GSC, GA4 |
25
+ | Citation data | ❌ | BrightLocal |
26
+
27
+ ## How the Agent Interacts with Screaming Frog
28
+
29
+ ### With MCP Connected
30
+ The agent can trigger crawls and read results directly.
31
+
32
+ ### Without MCP (More Common)
33
+ The user runs the crawl locally and exports data. The agent analyzes the exported CSV/Excel files.
34
+
35
+ **Tell the user what to export:**
36
+ 1. Run the crawl in Screaming Frog
37
+ 2. Export: Internal > All (CSV)
38
+ 3. If needed: Bulk Export > specific reports (response codes, directives, schema, etc.)
39
+ 4. Upload the CSV to the conversation
40
+
41
+ ## Core Workflows
42
+
43
+ ### Location Page Technical Audit
44
+
45
+ **When:** User has a multi-location site and needs to verify all location pages are technically sound.
46
+
47
+ **What to check in crawl data:**
48
+
49
+ | Check | Where to Find | What's Wrong If... |
50
+ |-------|--------------|-------------------|
51
+ | Title tags | Title 1 column | Duplicate titles across locations, missing titles, truncated titles |
52
+ | Meta descriptions | Meta Description 1 | Duplicate metas, missing metas, boilerplate metas |
53
+ | H1 tags | H1-1 column | Missing H1, duplicate H1s, H1 doesn't include service + city |
54
+ | Word count | Word Count column | Under 300 words = thin content (Google may not index) |
55
+ | Status codes | Status Code column | 404 errors, 302 redirects (should be 301), 5xx errors |
56
+ | Canonical tags | Canonical Link Element 1 | Self-referencing canonical missing, or canonical pointing to wrong page |
57
+ | Internal links in | Inlinks column | 0 or 1 internal links = orphan page |
58
+ | Schema present | Custom extraction needed | No LocalBusiness schema on location pages |
59
+ | NAP on page | Custom extraction needed | Missing or inconsistent NAP |
60
+ | Page speed | PageSpeed tab (if PSI integration enabled) | LCP > 2.5s, CLS > 0.1 |
61
+
62
+ ### Custom Extraction for Local SEO
63
+
64
+ **What to tell the user to configure:**
65
+
66
+ **LocalBusiness Schema Extraction:**
67
+ - Extraction: CSS Selector or XPath
68
+ - Target: `script[type="application/ld+json"]`
69
+ - This extracts the full JSON-LD block — agent can then validate schema fields
70
+
71
+ **NAP Extraction:**
72
+ - Business name: CSS selector for the element containing business name
73
+ - Phone: CSS selector for tel: links
74
+ - Address: CSS selector for address block
75
+
76
+ **Per-page schema validation the agent should do:**
77
+ 1. Is `@type` correct? (e.g., Dentist, Plumber, LocalBusiness)
78
+ 2. Does `name` match GBP exactly?
79
+ 3. Does `address` match GBP exactly?
80
+ 4. Does `telephone` match GBP exactly?
81
+ 5. Are `openingHoursSpecification` present?
82
+ 6. Are `geo` coordinates present and correct?
83
+ 7. Is `areaServed` present (for SABs)?
84
+
85
+ ### Duplicate Content Detection
86
+
87
+ **When:** Multi-location sites often have boilerplate location pages with only the city name changed.
88
+
89
+ **What to check:**
90
+ - Near-duplicate detection (Screaming Frog has this built in)
91
+ - Word count column — if all location pages are exactly the same word count, they're probably templated
92
+ - Title tag patterns — if all titles are "[Service] in [City] | [Brand]" with identical supporting content, Google may not index them all
93
+
94
+ **What "unique enough" looks like:**
95
+ - Unique intro paragraph mentioning specific area landmarks, neighborhoods, demographics
96
+ - Unique service details relevant to that location
97
+ - Unique testimonials or case studies from that area
98
+ - Different photos per location
99
+ - Unique FAQ based on common questions from that area's customers
100
+
101
+ ### Internal Linking Analysis
102
+
103
+ **When:** Location pages aren't getting organic traffic and you suspect they're orphaned or poorly linked.
104
+
105
+ **What to check:**
106
+ - **Inlinks column**: How many internal pages link to each location page
107
+ - **Crawl depth**: How many clicks from homepage to reach each location page
108
+ - **Link structure**: Are location pages linked from the main navigation, footer, or buried?
109
+
110
+ **Healthy internal linking for location pages:**
111
+ - Every location page linked from a locations index/directory page
112
+ - Location pages linked from service pages (where relevant)
113
+ - Location pages linked from each other (nearby locations)
114
+ - Crawl depth: Max 3 clicks from homepage
115
+
116
+ ### Redirect Audit
117
+
118
+ **When:** User migrated sites, changed URLs, or has old location pages that redirected.
119
+
120
+ **What to check:**
121
+ - 302 redirects (should usually be 301 for permanent moves)
122
+ - Redirect chains (A → B → C → D — should be A → D)
123
+ - Redirect loops (A → B → A)
124
+ - Old location URLs that 404 instead of redirecting
125
+
126
+ ## Interpreting Crawl Data for Local SEO
127
+
128
+ ### Priority Issues (Fix First)
129
+
130
+ | Issue | Impact | How to Find |
131
+ |-------|--------|------------|
132
+ | Location pages returning 404 | Pages completely invisible | Status Code = 404, filter to location URLs |
133
+ | Location pages not in sitemap | Google may not discover them | Cross-reference sitemap URLs with crawled URLs |
134
+ | Location pages blocked by robots.txt | Google can't crawl them | Indexability column = "Blocked by Robots.txt" |
135
+ | Location pages with noindex | Google won't index them | Meta Robots column contains "noindex" |
136
+
137
+ ### Important Issues (Fix Next)
138
+
139
+ | Issue | Impact | How to Find |
140
+ |-------|--------|------------|
141
+ | Duplicate titles across locations | Google may suppress duplicates | Title 1 column — sort and find duplicates |
142
+ | Thin content (under 300 words) | Google may not index | Word Count column < 300 |
143
+ | Missing schema | Losing structured data signals | Custom extraction shows empty |
144
+ | Orphan pages (0-1 internal links) | Low crawl priority, low authority | Inlinks column = 0 or 1 |
145
+
146
+ ### Maintenance Issues (Fix When Possible)
147
+
148
+ | Issue | Impact | How to Find |
149
+ |-------|--------|------------|
150
+ | Missing meta descriptions | Lower CTR from search results | Meta Description 1 = empty |
151
+ | Images without alt text | Accessibility + minor SEO signal | Images tab, Alt Text column empty |
152
+ | Redirect chains | Wasted crawl budget, slow page loads | Redirect Chains report |
153
+
154
+ ## What to Do Next
155
+
156
+ | What You Found | Next Action | Skill |
157
+ |----------------|-------------|-------|
158
+ | Location pages with thin content | Rewrite with unique, substantial content per location | `local-landing-pages` |
159
+ | Missing schema on location pages | Implement LocalBusiness schema | `local-schema` |
160
+ | Duplicate titles/metas | Rewrite with unique, keyword-targeted titles per location | `local-landing-pages` |
161
+ | Orphan location pages | Fix internal linking structure | `local-landing-pages` |
162
+ | Indexing issues (noindex, robots.txt, missing from sitemap) | Fix technical issues | `local-seo-audit` |
163
+ | NAP inconsistencies found via custom extraction | Fix on-page NAP to match GBP exactly | `gbp-optimization`, `local-citations` |
164
+ | All technical issues documented | Package into audit report for client | `client-deliverables` |
165
+
166
+ **Default next step:** Screaming Frog crawl data is a goldmine but it's raw. Always prioritize: indexing blockers → content issues → structural issues → optimization opportunities.
@@ -0,0 +1,121 @@
1
+ ---
2
+ name: semrush-tool
3
+ description: When the user wants keyword research with search volume, competitive keyword analysis, site audit data, position tracking, or competitor organic analysis. Trigger on "keyword research," "search volume," "keyword difficulty," "what keywords do they rank for," "site audit," "Semrush," or "competitive analysis." Use Semrush for keyword data and competitive intelligence — use Ahrefs for backlink-focused analysis.
4
+ ---
5
+
6
+ # Semrush Tool
7
+
8
+ > **Note:** LocalSEOData (`localseodata-tool`) now covers keyword suggestions, search volume, keyword trends, and keyword opportunities. Use LocalSEOData as default. Semrush remains the stronger choice for advanced keyword gap analysis, Keyword Magic Tool, and combined keyword + site audit workflows.
9
+
10
+ Semrush has an official MCP server. When connected, use it for keyword research, competitive organic analysis, and technical site audits. This is your primary keyword intelligence tool.
11
+
12
+ ## When to Use Semrush vs Other Tools
13
+
14
+ | You Need | Use Semrush | Use Instead |
15
+ |----------|------------|-------------|
16
+ | Keyword search volume for local terms | ✅ Best for this | — |
17
+ | Keyword difficulty scores | ✅ | Ahrefs (different scale, both valid) |
18
+ | What keywords a competitor ranks for | ✅ Best for this | — |
19
+ | Keyword gap (you vs competitor) | ✅ Best for this | — |
20
+ | Backlink analysis | ⚠️ Decent but not best | Ahrefs (larger index) |
21
+ | Link intersect / link gap | ⚠️ Can do it | Ahrefs (preferred for links) |
22
+ | Technical site audit | ✅ Good crawler | Screaming Frog (more detailed) |
23
+ | Position tracking by location | ✅ | Local Falcon (geogrid is better for local) |
24
+ | Citation management | ❌ | BrightLocal, Whitespark |
25
+ | Live SERP snapshot | ❌ | SerpAPI |
26
+ | Geogrid rankings | ❌ | Local Falcon |
27
+
28
+ ## Core Workflows
29
+
30
+ ### Local Keyword Research
31
+
32
+ **When:** User needs to find keywords to target with volume and difficulty data.
33
+
34
+ **What to pull:**
35
+ 1. **Keyword Overview**: Volume, KD, CPC, SERP features for target keywords
36
+ 2. **Keyword Magic Tool**: Related keywords from a seed term (e.g., "plumber buffalo" → generates hundreds of variations)
37
+ 3. **Keyword Gap**: Compare user's domain vs 2-3 competitors to find keywords competitors rank for that user doesn't
38
+
39
+ **How to interpret for local:**
40
+ - Volume under 100/mo is common for local keywords — that's normal and still valuable
41
+ - KD under 40 for local service keywords is achievable
42
+ - CPC above $5 means high commercial intent — prioritize these
43
+ - Look for keyword clusters: same service, different locations (e.g., "dentist Orchard Park," "dentist Hamburg," "dentist West Seneca")
44
+
45
+ **What to do with the data:**
46
+ - Group keywords by service category
47
+ - Map keywords to existing or needed pages
48
+ - Identify gaps where competitors rank but you don't
49
+ - Feed into `local-keyword-research` skill for full keyword strategy
50
+ - Feed into `local-landing-pages` skill for page creation
51
+
52
+ ### Competitor Organic Analysis
53
+
54
+ **When:** User wants to know what keywords competitors rank for or how they compare.
55
+
56
+ **What to pull:**
57
+ 1. **Domain Overview**: Total organic keywords, traffic estimate, top keywords
58
+ 2. **Organic Research**: All keywords a competitor ranks for with positions
59
+ 3. **Keyword Gap**: Side-by-side comparison showing where competitor ranks and you don't
60
+
61
+ **What to look for:**
62
+ - Keywords where competitor ranks top 10 and you rank 11-20 (quick wins — you're close)
63
+ - Keywords where competitor ranks and you don't rank at all (content gaps)
64
+ - Keywords where you rank higher than competitor (protect these)
65
+ - Competitor's top traffic-driving keywords (understand their strategy)
66
+
67
+ ### Technical Site Audit
68
+
69
+ **When:** User needs a crawl of their website for technical issues.
70
+
71
+ **What Semrush's audit catches:**
72
+ - Broken links (internal and external)
73
+ - Missing/duplicate title tags and meta descriptions
74
+ - Slow pages
75
+ - Redirect chains
76
+ - Missing schema markup
77
+ - Crawlability issues
78
+ - HTTPS issues
79
+
80
+ **For local specifically, check:**
81
+ - Location page titles: unique per location?
82
+ - Location page meta descriptions: unique per location?
83
+ - Internal linking to location pages
84
+ - Schema presence on location pages
85
+ - Canonical tags on similar location pages
86
+
87
+ **When to use Screaming Frog instead:** If you need custom extraction (NAP data, specific schema fields) or the site has 1000+ location pages, Screaming Frog gives more control.
88
+
89
+ ### Position Tracking
90
+
91
+ **When:** User wants to track keyword rankings over time at a specific location.
92
+
93
+ - Set location to city/ZIP level
94
+ - Track target keywords weekly
95
+ - Compare against competitors in the same tracker
96
+
97
+ **When to use Local Falcon instead:** For local businesses, geogrid ranking (Local Falcon) is more meaningful than point-based position tracking (Semrush) because rankings vary by searcher location. Use Semrush position tracking for organic rankings, Local Falcon for map pack rankings.
98
+
99
+ ## Key Data Points and What They Mean
100
+
101
+ | Metric | What It Is | What It Means for Local SEO |
102
+ |--------|-----------|---------------------------|
103
+ | Search Volume | Monthly searches | Under 100 is normal for local — still valuable if intent is high |
104
+ | Keyword Difficulty (KD) | How hard to rank organically | Under 40 = achievable for local businesses with good content |
105
+ | CPC | Cost per click in Google Ads | High CPC = high commercial intent = priority keyword |
106
+ | Competitive Density | How many advertisers bid on this keyword | High density = proven money keyword |
107
+ | SERP Features | What appears in results (local pack, ads, PAA, etc.) | Local pack present = GBP optimization matters for this keyword |
108
+ | Traffic | Estimated monthly organic visits | Relative metric — compare competitors to each other |
109
+
110
+ ## What to Do Next
111
+
112
+ | What You Found | Next Action | Skill |
113
+ |----------------|-------------|-------|
114
+ | Keywords identified with volume data | Map keywords to pages and build content | `local-landing-pages` |
115
+ | Keyword gaps vs competitors | Prioritize gaps by volume × intent and create pages | `local-keyword-research` |
116
+ | Competitor ranking for keywords you're not | Analyze if it's a content gap or authority gap | `local-competitor-analysis` |
117
+ | Technical issues from site audit | Fix critical issues first (broken links, missing titles) | `local-seo-audit` |
118
+ | High-CPC keywords worth running ads for | Set up PPC campaigns | `local-ppc-ads` |
119
+ | Keywords with local pack in SERP | Optimize GBP for those keywords | `gbp-optimization` |
120
+
121
+ **Default next step:** Keyword data without a page plan is just a spreadsheet. Always map keywords → pages → publish → measure.
@@ -0,0 +1,148 @@
1
+ ---
2
+ name: serpapi-tool
3
+ description: When the user wants to check live SERP results for a keyword, see what's in the local pack right now, check People Also Ask, see AI Overviews, verify SERP features, or do a quick spot-check of local search results. Trigger on "what shows up when you search," "check the SERP," "who's in the map pack," "what does the search results page look like," or "search for [keyword]."
4
+ ---
5
+
6
+ # SerpAPI Tool
7
+
8
+ > **Note:** LocalSEOData (`localseodata-tool`) now covers live SERP data via `organic_serp`, `local_pack`, `maps`, and `local_finder` endpoints. Use LocalSEOData as default. SerpAPI remains useful if LocalSEOData is not connected, or for non-Google engines (Bing, Yahoo).
9
+
10
+ You have direct access to SerpAPI via MCP. This gives you live, real-time search results from Google, Bing, and other engines at any location.
11
+
12
+ ## When to Use SerpAPI vs Other Tools
13
+
14
+ | You Need | Use SerpAPI | Use Instead |
15
+ |----------|------------|-------------|
16
+ | Live SERP snapshot right now | ✅ | — |
17
+ | What's in the local pack for a query | ✅ | Local Falcon for geographic grid coverage |
18
+ | People Also Ask questions | ✅ | — |
19
+ | AI Overview content | ✅ | Local Falcon GAIO scan for geographic coverage |
20
+ | Quick rank check at one location | ✅ | Local Falcon for systematic multi-point |
21
+ | SERP features present (ads, knowledge panel, etc.) | ✅ | — |
22
+ | Rankings across a geographic grid | ❌ Too slow point by point | Local Falcon |
23
+ | Keyword volume/difficulty | ❌ | Semrush, Ahrefs, DataForSEO |
24
+ | Historical ranking trends | ❌ Snapshot only | Local Falcon trends |
25
+
26
+ ## Core Workflows
27
+
28
+ ### Check Live SERP for a Local Keyword
29
+
30
+ **When:** User wants to see what Google shows right now for a search.
31
+
32
+ ```json
33
+ {
34
+ "params": {
35
+ "q": "emergency plumber",
36
+ "engine": "google",
37
+ "location": "Buffalo, New York, United States"
38
+ },
39
+ "mode": "compact"
40
+ }
41
+ ```
42
+
43
+ **What to extract from results:**
44
+ - `local_results` — the map pack (positions, business names, ratings, reviews)
45
+ - `organic_results` — organic listings below the map
46
+ - `ads` — paid ads present (indicates commercial value)
47
+ - `related_questions` — People Also Ask (content opportunity)
48
+ - `ai_overview` — AI Overview content if present
49
+ - `knowledge_graph` — knowledge panel for branded searches
50
+
51
+ ### Check Google Maps Results Specifically
52
+
53
+ **When:** User wants to see local business listings specifically.
54
+
55
+ ```json
56
+ {
57
+ "params": {
58
+ "q": "dentist",
59
+ "engine": "google_maps",
60
+ "location": "Orchard Park, New York"
61
+ }
62
+ }
63
+ ```
64
+
65
+ Use `google_maps` engine when you want more than the top 3 map pack — this returns the full local finder results.
66
+
67
+ ### Check Local Results from a Specific Location
68
+
69
+ **When:** User wants to see results as if searching FROM a specific place.
70
+
71
+ ```json
72
+ {
73
+ "params": {
74
+ "q": "chiropractor near me",
75
+ "engine": "google_local",
76
+ "location": "Amherst, New York"
77
+ }
78
+ }
79
+ ```
80
+
81
+ **Important:** Location parameter simulates searching FROM that location. "Near me" queries will show results near that location.
82
+
83
+ ### Quick Competitive SERP Analysis
84
+
85
+ **When:** User wants to understand the competitive landscape for a keyword.
86
+
87
+ Run the search, then analyze:
88
+ 1. **Are there ads?** → Keyword has commercial value
89
+ 2. **Is there a local pack?** → Google sees local intent
90
+ 3. **How many reviews do map pack businesses have?** → Review benchmark
91
+ 4. **Is there an AI Overview?** → Content needs to be AI-optimizable
92
+ 5. **What are the PAA questions?** → Content/FAQ opportunities
93
+ 6. **Who's ranking organically?** → Directories vs. actual businesses
94
+
95
+ ### Verify SERP Features for Keyword Research
96
+
97
+ **When:** Building keyword strategy and need to know which keywords trigger which features.
98
+
99
+ Run searches for each target keyword and note:
100
+ - Local pack present → prioritize GBP optimization for this keyword
101
+ - Ads present → keyword has conversion value, consider PPC
102
+ - AI Overview present → optimize content for AI citation
103
+ - Featured snippet → structured content opportunity
104
+ - PAA questions → FAQ content opportunities
105
+ - No local pack → keyword may not have local intent, reconsider targeting
106
+
107
+ ## Engine Selection Guide
108
+
109
+ | Engine | When to Use |
110
+ |--------|-------------|
111
+ | `google` | Default — full SERP with all features including local pack |
112
+ | `google_maps` | Want full local/maps results beyond top 3 |
113
+ | `google_local` | Local finder results specifically |
114
+ | `google_light` | Quick check, less data, faster response |
115
+ | `google_news` | Check if keyword has news coverage |
116
+ | `google_images` | Check image results for a query |
117
+ | `bing` | Check Bing results (relevant for Copilot/AI search) |
118
+
119
+ ## Interpreting Results for Local SEO
120
+
121
+ ### Local Pack Analysis
122
+ - **Position 1-3**: These businesses dominate — note their review counts, ratings, categories
123
+ - **No local pack**: Google doesn't see local intent for this query — reconsider keyword strategy
124
+ - **Ads above local pack**: Competitive keyword — organic alone may not be enough
125
+
126
+ ### People Also Ask (PAA)
127
+ - Each PAA question is a content opportunity
128
+ - If your target keyword generates PAAs like "How much does [service] cost in [city]?" — create content answering that
129
+ - PAA questions often become FAQ schema candidates
130
+
131
+ ### AI Overview
132
+ - If present: Google is summarizing content for this query
133
+ - Note which sources are cited — those sites have the content structure Google prefers
134
+ - Your content needs to be factual, well-structured, and directly answering the query
135
+
136
+ ## What to Do Next
137
+
138
+ | What You Found | Next Action | Skill |
139
+ |----------------|-------------|-------|
140
+ | Local pack shows competitors with more reviews | Build review strategy | `review-management` |
141
+ | No local pack for target keyword | This isn't a local keyword — adjust strategy | `local-keyword-research` |
142
+ | AI Overview present, user not cited | Optimize content for AI visibility | `ai-local-search` |
143
+ | PAA questions found | Create FAQ content targeting those questions | `local-landing-pages` |
144
+ | Ads present, user not running ads | Consider PPC for this keyword | `local-ppc-ads` |
145
+ | Want geographic ranking data, not just this one point | Run a proper geogrid scan | `local-falcon-tool` |
146
+ | User in map pack but wrong position | Diagnose with geogrid analysis | `geogrid-analysis` |
147
+
148
+ **Default next step:** SerpAPI gives you a snapshot. For ongoing tracking, set up Local Falcon scans. Use SerpAPI for exploration and spot-checks, Local Falcon for measurement.
@@ -0,0 +1,149 @@
1
+ ---
2
+ name: task-preflight
3
+ description: Cómo interpretar la respuesta de `crm task preflight` antes de crear una tarea. Decisión rápida sobre duplicados, sobrecarga de dominio y profundización con datos de GSC/GA4 cuando hace falta. Cárgalo SÓLO si el envelope del preflight tiene `similarTasks` con score alto, `urlScopedTasks` no vacío, o vas a crear una tarea URL-scoped y dudas si ya existe.
4
+ when_to_use: "el preflight devolvió Posible duplicado", "urlScopedTasks no vacío", "openTaskCounts alto", "necesito profundizar con GSC/GA4 antes de crear", "la URL ya tenía un task pero está en done"
5
+ ---
6
+
7
+ # Task preflight — interpretación
8
+
9
+ `crm task preflight` se llama **antes** de cualquier `crm task create`. Este
10
+ skill explica cómo leer la respuesta sin volver a leerse cli/SKILL.md (que ya
11
+ te dijo el ritual). Cárgalo sólo si el envelope te deja en duda; en el 80% de
12
+ los casos los `hints[]` ya te dicen qué hacer.
13
+
14
+ ## Forma de la respuesta (recordatorio)
15
+
16
+ ```jsonc
17
+ {
18
+ "ok": true,
19
+ "data": {
20
+ "similarTasks": [ { id, title, status, score, sameDomain, when } ],
21
+ "recall": [ { type, id, when, score, snippet } ], // [] si no pasaste --url
22
+ "recentChanges": [ { id, url, occurredAt, note, types[] } ],
23
+ "urlScopedTasks": [ { id, title, status, when } ], // [] si no pasaste --url
24
+ "recentBacklinks": [ { id, sourceUrl, targetUrl, status, anchorText, when } ],
25
+ "openTaskCounts": { todo, doing, blocked, done } | null, // null si no pasaste --domain
26
+ "hints": [ "Posible duplicado: ...", ... ],
27
+ "meta": { title, url, domainId, sinceMs, limit }
28
+ },
29
+ "summary": "preflight: N similar · M recall · ..."
30
+ }
31
+ ```
32
+
33
+ ## Árbol de decisión
34
+
35
+ ```
36
+ similarTasks[0].score >= 0.55
37
+ ├── status ∈ {todo, doing, blocked}
38
+ │ → COMENTA en la existente (`crm comment create --task <id>`).
39
+ │ NO crees una nueva. Si tu trabajo es escope adicional, edita la
40
+ │ descripción con `crm task update <id> --description`.
41
+ │
42
+ └── status == done
43
+ → Pregunta: ¿es regresión?
44
+ - Sí: crea NUEVA citando la cerrada con `#[Title](id)` en la
45
+ descripción + `--kind decision` en un comentario explicando
46
+ por qué se reabre.
47
+ - No: es trabajo de seguimiento real → crea nueva con `#link`.
48
+
49
+ similarTasks[0].score ∈ [0.45, 0.55) y sameDomain == true
50
+ → Lectura rápida con `crm task get <id>`. Si el title coincide en >2/3
51
+ tokens, trátalo como duplicado fuerte (rama de arriba). Si no, sigue.
52
+
53
+ urlScopedTasks no vacío (sin importar similarTasks)
54
+ → La URL YA tiene KPIs ligados. Tu nueva tarea probablemente debería
55
+ enlazar a la misma propertyLink (mismo scope) en vez de duplicar la
56
+ medición. Mira `crm task get <id>` para ver el `keyMetric` y reusa.
57
+
58
+ openTaskCounts.todo + .doing + .blocked >= 8
59
+ → Dominio sobrecargado. Si el humano no pidió explícitamente "más",
60
+ responde con la cuenta y pregunta qué priorizar.
61
+
62
+ recentChanges contiene tu URL en los últimos 30 días con tipo coincidente
63
+ → Lo pediste pero ya se hizo. Lee el `note` y la lista de `types[]`. Si
64
+ coincide, NO crees — informa al humano con un resumen de lo que ya cambió.
65
+
66
+ Nada de lo de arriba aplica
67
+ → Adelante con `crm task create`. Pasa `#[Title](id)` referenciando los
68
+ `recall` o `urlScopedTasks` si son tangenciales pero útiles.
69
+ ```
70
+
71
+ ## Cuándo cargar datos vivos (después del preflight, no antes)
72
+
73
+ Si decides crear pero tu propuesta de KPI no es obvia, **entonces** carga la
74
+ vista en vivo — no antes:
75
+
76
+ | Necesitas... | Comando | Coste |
77
+ |---|---|---|
78
+ | Clicks/impresiones/CTR/posición agregados del dominio | `crm domain metrics dom_xyz --start … --end …` | Tinybird, ~50ms, sin cuota |
79
+ | Mismo, filtrado a una URL | `crm gsc query --property prop_X --dimension page --filters "page=<url>"` | live GSC + queryPageCache 6h, cuenta cuota GSC en miss |
80
+ | Tráfico/conversiones por URL | `crm ga4 query --property prop_X --filters "pagePath=<url>"` | live GA4, cuenta cuota |
81
+ | Backlinks/anchors actuales hacia la URL | `crm backlink list --domain dom_xyz --target-url <url>` | Convex, gratis |
82
+
83
+ Regla: **el preflight es Convex puro (gratis). Tinybird es barato. GSC/GA4
84
+ live cuestan cuota — sólo si hay decisión real que tomar.**
85
+
86
+ ## Qué no pre-crawlees
87
+
88
+ - **Nunca** lances Screaming Frog para entender una URL puntual. Si necesitas
89
+ ver el HTML, usa `WebFetch` (1 GET, sin cuota). SF se justifica cuando la
90
+ tarea es "audita el sitio entero", no antes de crear cada tarea.
91
+ - **No corras `crm gsc query` para todas las páginas del dominio** sólo para
92
+ "tener contexto". Eso quema cuota. Si necesitas un overview, ya tienes
93
+ `crm domain metrics`.
94
+
95
+ ## Anti-patrones
96
+
97
+ - **Pasar `--title` con palabras de relleno** ("Hacer cosa en pricing").
98
+ Hace que `similarTasks` traiga ruido y los `hints` no detecten duplicados.
99
+ Usa el verbo + sustantivo + URL/sección como en la propia tarea final.
100
+ - **Ignorar `hints` y mirar sólo `similarTasks`.** Los hints están escritos
101
+ por el server con la lógica completa (recall + scoped + counts). Confía en
102
+ ellos.
103
+ - **Crear sin `--domain`.** Sin dominio, `openTaskCounts` queda en `null` y
104
+ `recentChanges` se restringe a coincidencias por URL. El preflight pierde
105
+ la mitad de su valor.
106
+ - **Llamar `crm recall` después del preflight "por si acaso".** El preflight
107
+ ya hace recall (con cap de 10 items en lugar de 50, pero suficiente). Sólo
108
+ llama `crm recall` directamente si necesitas más profundidad histórica
109
+ (ej. `--since-ms` mayor a 180 días).
110
+
111
+ ## Ejemplo de decisión (no ejecutar — sólo lectura)
112
+
113
+ ```bash
114
+ $ crm task preflight \
115
+ --title "Reescribir meta title /seo-tools" \
116
+ --url https://example.com/seo-tools \
117
+ --domain dom_abc \
118
+ --jq .data
119
+ ```
120
+
121
+ ```jsonc
122
+ {
123
+ "similarTasks": [
124
+ { "id": "tsk_x1", "title": "Optimizar meta title de /seo-tools",
125
+ "status": "done", "score": 0.78, "sameDomain": true,
126
+ "when": 1741..., "reviewRequired": false }
127
+ ],
128
+ "recall": [
129
+ { "type": "change", "id": "che_a", "when": 1741..., "score": 0.92,
130
+ "snippet": "meta_title: 'SEO Tools — guía 2026'" }
131
+ ],
132
+ "urlScopedTasks": [],
133
+ "recentChanges": [
134
+ { "id": "che_a", "url": ".../seo-tools", "occurredAt": "2026-04-12",
135
+ "types": ["meta_title"], "note": "rev2" }
136
+ ],
137
+ "openTaskCounts": { "todo": 3, "doing": 1, "blocked": 0, "done": 14 },
138
+ "hints": [
139
+ "Posible duplicado: \"Optimizar meta title de /seo-tools\" (estado: done). Revísala con `crm task get tsk_x1` antes de crear."
140
+ ]
141
+ }
142
+ ```
143
+
144
+ Lectura: el meta title ya se reescribió hace 3 semanas (`change` con `score`
145
+ muy alto y `recentChanges` confirma). La tarea original está en `done`. Si
146
+ estás aquí porque el humano dijo "está mal otra vez", esto es regresión →
147
+ crea nueva citando `#[Optimizar meta title de /seo-tools](tsk_x1)` y deja un
148
+ `--kind decision` explicando qué falla del rev2. Si no, NO crees — comenta
149
+ al humano la fecha del último cambio.
@@ -0,0 +1,59 @@
1
+ ---
2
+ name: tool-routing
3
+ description: Elige entre las herramientas externas de SEO local que tiene la agencia (Screaming Frog, Ahrefs, BrightLocal, LocalSEOData, Local Falcon, Semrush, SerpAPI, DataForSEO, Whitespark, LSA Spy, Google Search Console, Google Analytics). Úsalo cuando hay que decidir qué tool atacar una tarea antes de cargar el skill específico de esa herramienta.
4
+ when_to_use: "qué tool uso para X", "con qué herramienta audito Y", "¿Screaming Frog o Ahrefs?", "cuál es la mejor para citations", "qué tool tiene datos de backlinks", "tool para geogrid", "tool para reviews"
5
+ ---
6
+
7
+ # Tool Routing
8
+
9
+ Decide qué herramienta externa usar para cada tipo de tarea antes de cargar
10
+ el skill detallado. Cada fila de la tabla apunta al skill con la doc completa
11
+ de ese tool.
12
+
13
+ ## Matriz de decisión
14
+
15
+ | Necesitas | Tool primario | Skill a cargar | Alternativas |
16
+ |---|---|---|---|
17
+ | Decidir si crear una tarea (duplicados + recall + cargas) | `crm task preflight` | `task-preflight` | — (siempre primero, antes de cualquier task create) |
18
+ | Auditoría técnica de sitio (crawl completo) | Screaming Frog | `screaming-frog-tool` | Semrush site audit (ligero) |
19
+ | Análisis de páginas de ubicación a escala | Screaming Frog | `screaming-frog-tool` | — |
20
+ | Extracción custom (NAP, schema) | Screaming Frog | `screaming-frog-tool` | — |
21
+ | Backlinks / referring domains / link gap | Ahrefs | `ahrefs-tool` | LocalSEOData (`backlink_summary`, `backlink_gap`) para overviews rápidos |
22
+ | Anchor text / lost links | Ahrefs | `ahrefs-tool` | — |
23
+ | Auditoría de citations + NAP consistency | BrightLocal / LocalSEOData | `brightlocal-tool` / `localseodata-tool` | Whitespark (más profundo) |
24
+ | Descubrir listings desconocidos | LocalSEOData | `localseodata-tool` | — |
25
+ | Geogrid scan (rankings por geolocalización) | Local Falcon | `local-falcon-tool` | LocalSEOData `geogrid_scan` (one-off) |
26
+ | Auditoría integral en una llamada | LocalSEOData | `localseodata-tool` | — |
27
+ | Keyword research (volumen, dificultad, intent) | Semrush | `semrush-tool` | Ahrefs (secundario) |
28
+ | SERP snapshots / análisis de SERPs | SerpAPI | `serpapi-tool` | DataForSEO SERP |
29
+ | Datos crudos de Google (SERP + Ads) | DataForSEO | `dataforseo-tool` | SerpAPI (más simple) |
30
+ | Local Services Ads (LSA) ranking / precios | LSA Spy | `lsa-spy-tool` | — |
31
+ | Descubrimiento de directorios / data aggregators | Whitespark | `whitespark-tool` | BrightLocal |
32
+ | Performance orgánico (clicks, impresiones, queries) | Google Search Console | `google-search-console-tool` | — (única fuente de verdad) |
33
+ | Tráfico y conversiones | Google Analytics | `google-analytics-tool` | — (única opción) |
34
+ | Reviews (Google Maps) | LocalSEOData | `localseodata-tool` | BrightLocal |
35
+
36
+ ## Preguntas que el agente debería hacer antes de elegir
37
+
38
+ 1. ¿El usuario ya tiene exportado un CSV de alguna herramienta? → lo analizas tú, no hace falta tool nuevo.
39
+ 2. ¿Es monitoreo recurrente o análisis puntual? → monitoreo → LocalSEOData/Local Falcon; puntual → Screaming Frog / Ahrefs.
40
+ 3. ¿El cliente paga esa herramienta? Pregunta si no está claro — no asumas acceso.
41
+ 4. ¿Lo pide la agencia (IP interno) o es investigación pública? → para IP interno, GBP/GSC/GA4; para investigación, SerpAPI/DataForSEO.
42
+
43
+ ## Anti-patrones
44
+
45
+ - **No cargues varios tool-skills a la vez.** Cada uno trae una tabla "When to Use X vs Y" — si cargas ahrefs-tool + semrush-tool simultáneamente, duplicas contexto. Usa este skill para elegir, luego carga uno.
46
+ - **No inventes endpoints.** Si no hay skill cargado, dile al usuario que exporte el CSV y tú lo lees — es más realista que pretender una integración que no existe.
47
+ - **No recomiendes el tool de mayor precio por defecto.** Ahrefs + Semrush son caros. Si el cliente solo necesita un overview, LocalSEOData o GSC cubren el 80% gratis.
48
+
49
+ ## Workflow típico
50
+
51
+ ```
52
+ 1. Usuario: "Audítame el SEO local de cliente X"
53
+ 2. Agente: carga `tool-routing` (este skill)
54
+ 3. Agente: identifica qué subtareas componen la auditoría
55
+ 4. Agente: carga los 2-3 skills específicos necesarios
56
+ (ej. `local-seo-audit` como playbook + `localseodata-tool` + `screaming-frog-tool`)
57
+ 5. Agente: ejecuta la auditoría. Si un tool no está disponible, degrada
58
+ a la alternativa de la matriz arriba y avisa al usuario.
59
+ ```