@jairodri/huckleberry-cli 1.0.2 → 1.1.0

package/skills/topical-authority/SKILL.md

@@ -0,0 +1,307 @@
+---
+name: topical-authority
+description: Market-first topical authority system with systematic keyword-to-content-cluster workflow.
+---
+name: topical-authority
+description: Market-first topical authority system using systematic framework. Complete workflow from keyword research through content cluster generation.
+---
+
+# Topical Authority Skill
+
+**Market-first topical authority system using Jake Ward's 7-step framework**
+
+## Overview
+
+This skill implements a complete topical authority workflow that starts with market research (forums, Reddit, Quora) and builds SEO-optimized content clusters using SERP analysis and hub-and-spoke architecture.
+
+**Key Innovation**: All script execution is delegated to Gemini CLI for 95%+ token savings.
+
+## When to Use This Skill
+
+Use this skill when:
+- Starting SEO strategy for a new brand or niche
+- Building topical authority in a specific domain
+- Need to identify high-value content opportunities (GOLDEN/GOOD)
+- Want to prevent keyword cannibalization via SERP clustering
+- Building hub-and-spoke content architecture
+- Auditing and improving internal linking structure
+
+**Trigger phrases**:
+- "build topical authority for [brand]"
+- "run SEO discovery for [brand]"
+- "identify content gaps for [brand]"
+- "audit internal links for [brand]"
+
+## Workflow Phases
+
+### Phase 1: Forum Discovery (Scripts 1-4)
+Scrape pain points and questions from multiple sources:
+- **Reddit**: Pain point detection across ICP-relevant subreddits
+- **Quora**: High-engagement questions by topic
+- **People Also Ask**: Recursive PAA expansion from seed keywords
+- **Competitor Analysis**: Content gap identification
+
+**Output**: `businesses/{business}/evergreen.mdforum-data/*.json`
+
+### Phase 2: Keyword Extraction (Script 5)
+Use Gemini CLI to extract keyword variations from forum data:
+- 5-10 keyword variations per forum item
+- Volume estimates (high/medium/low)
+- Search intent classification
+- Deduplication and normalization
+
+**Output**: `businesses/{business}/evergreen.mdkeyword-universe.json`
+
+### Phase 3: SERP Clustering (Scripts 6-8)
+Prevent keyword cannibalization using URL overlap analysis:
+- **Fetch SERP URLs**: Top 10 results per keyword
+- **Cluster by Intent**: Jaccard similarity + Gemini analysis
+- **Build Architecture**: Identify pillars and clusters
+
+**Algorithm**:
+- ≥70% URL overlap → Same cluster (same page)
+- <30% URL overlap → Different clusters (separate pages)
+- 30-69% overlap → Gemini analyzes search intent
+
+**Output**: `businesses/{business}/evergreen.mdhub-architecture.json`
+
+### Phase 4: Gap Analysis (Scripts 9-10)
+Identify high-value opportunities and research needs:
+- **Content Gaps**: Priority Score = `Volume × (100 - Difficulty)`
+- **Research Gaps**: Check if podcast research exists
+
+**Opportunity Levels**:
+- GOLDEN (top 10%): High volume + Very low difficulty (<20)
+- GOOD (next 20%): Good volume + Low difficulty (20-40)
+- MEDIUM (next 30%): Medium volume or medium difficulty
+- SKIP (bottom 40%): Low volume or high difficulty (>60)
+
+**Output**: `businesses/{business}/evergreen.mdcontent-gaps.json`, `research-gaps.json`
+
+### Phase 5: Internal Linking (Scripts 11-12)
+Audit and improve internal link structure:
+- **Audit**: Build link graph, identify orphaned pages
+- **Weave**: Auto-suggest strategic link insertions
+
+**Health Metrics**:
+- Orphan rate (% pages with no inbound links)
+- Avg internal links per page
+- Hub-spoke adherence score
+- Linking density
+
+**Output**: `businesses/{business}/evergreen.mdinternal-links-health.md`, `link-suggestions.md`
+
+## Cost Structure
+
+**Total estimated cost for 500-1,000 keywords**: ~$2-10
+
+| Component | Cost | Notes |
+|-----------|------|-------|
+| SERP Fetching | Free | HTTP requests (production: use SERP API) |
+| Keyword Extraction | ~$1-2 | Gemini CLI batch processing |
+| SERP Clustering | ~$1-5 | Gemini only for ambiguous cases (30-69% overlap) |
+| Total | ~$2-10 | vs $50/mo subscriptions |
+
+## Usage
+
+### Option 1: Run Complete Workflow
+```bash
+# Invoke skill and specify phase
+Skill: topical-authority
+
+# Then in skill context:
+# Run all phases for brand ai.withjai
+# Use defaults: min-volume=100, min-cluster-size=3
+```
+
+### Option 2: Run Individual Phases
+```bash
+# Phase 1: Forum discovery
+/topical-authority-discover --brand ai.withjai
+
+# Phase 2-3: SERP clustering
+/topical-authority-cluster --brand ai.withjai
+
+# Phase 4-5: Gap analysis + linking
+/topical-authority-analyze --brand ai.withjai
+```
+
+### Option 3: Run Individual Scripts
+```bash
+# Forum scrapers
+node scripts/seo/scrape-reddit-pain-points.js --brand ai.withjai
+node scripts/seo/scrape-quora-questions.js --brand ai.withjai --topics "ai automation,content marketing"
+
+# SERP clustering
+node scripts/seo/fetch-serp-urls.js --brand ai.withjai --limit 100
+node scripts/seo/gemini-serp-clustering.js --brand ai.withjai --threshold 0.7
+
+# Gap analysis
+node scripts/seo/identify-content-gaps.js --brand ai.withjai --min-volume 100
+node scripts/seo/identify-research-gaps.js --brand ai.withjai --min-priority 2
+
+# Internal linking
+node scripts/seo/audit-internal-links.js --brand ai.withjai --min-links 3
+node scripts/seo/weave-internal-links.js --brand ai.withjai --auto-insert
+```
+
+## Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `--brand` | Required | Brand identifier (ai.withjai, enchantents, etc) |
+| `--subreddits` | Auto-detected | Comma-separated list of subreddits |
+| `--topics` | Auto-detected | Comma-separated topics for Quora |
+| `--seed-keywords` | Auto-detected | Seed keywords for PAA expansion |
+| `--limit` | 100 | Max items to process per source |
+| `--threshold` | 0.7 | SERP clustering threshold (70% overlap) |
+| `--min-cluster-size` | 3 | Min keywords to be a pillar page |
+| `--min-volume` | 100 | Min monthly search volume |
+| `--min-priority` | 2 | Min priority level (1=GOLDEN, 2=GOOD) |
+| `--min-links` | 3 | Min internal links per page |
+| `--auto-insert` | false | Auto-insert suggested links (creates backups) |
+
+## Integration with Existing Workflows
+
+### After Topical Authority Setup → Content Creation
+```bash
+# 1. Run topical authority to identify opportunities
+Skill: topical-authority
+
+# 2. Check research gaps
+# Output shows: "Need podcast research for: [topics]"
+
+# 3. Use podcast-smart-ingestion to fill gaps
+Skill: podcast-smart-ingestion
+
+# 4. Create content using lean blog workflow
+/podcast-blog-lean --podcast "{path}" --brand {brand}
+
+# 5. Validate internal linking
+node scripts/seo/audit-internal-links.js --brand {brand}
+```
+
+### Quarterly Refresh
+```bash
+# Every 3 months, refresh topical authority analysis
+# 1. Re-scrape forums for new pain points
+# 2. Re-fetch SERP data (search results change)
+# 3. Re-analyze content gaps
+# 4. Re-audit internal links
+```
+
+## Orchestrator Architecture
+
+**Token Optimization**: All script execution delegated to Gemini CLI
+
+```javascript
+// Orchestrator pattern
+1. User invokes skill with brand + phase
+2. Orchestrator builds Gemini CLI prompt:
+   - List of scripts to run
+   - Parameters for each script
+   - Expected outputs
+   - Validation criteria
+3. Gemini CLI executes scripts sequentially
+4. Orchestrator validates outputs
+5. Return summary to user
+```
+
+**Token Savings**: 95%+ reduction vs running scripts directly in Claude context
+
+## Output Artifacts
+
+All outputs saved to `businesses/{business}/evergreen.md`:
+
+| File | Description |
+|------|-------------|
+| `forum-data/reddit-pain-points.json` | Reddit pain points by category |
+| `forum-data/quora-questions.json` | High-engagement Quora questions |
+| `forum-data/paa-questions.json` | People Also Ask recursive expansion |
+| `forum-data/competitor-coverage.json` | Competitor content gap analysis |
+| `keyword-universe.json` | Deduplicated keyword list with intent |
+| `serp-data/serp-urls.json` | Top 10 URLs per keyword |
+| `serp-data/keyword-clusters.json` | SERP-based keyword clusters |
+| `hub-architecture.json` | Pillar pages + cluster structure + linking plan |
+| `content-gaps.json` | Prioritized content opportunities |
+| `research-gaps.json` | Missing research + podcast queries |
+| `internal-links-graph.json` | Link graph + health metrics |
+| `internal-links-health.md` | Human-readable link audit report |
+| `link-suggestions.md` | Strategic link insertion suggestions |
+
+## Success Criteria
+
+**Forum Discovery**:
+- ✅ 50+ pain points from Reddit
+- ✅ 30+ high-engagement Quora questions
+- ✅ 50+ PAA questions (depth 2)
+- ✅ 10+ competitor content gaps
+
+**SERP Clustering**:
+- ✅ 100+ keywords validated
+- ✅ 5-10 pillar pages identified
+- ✅ 20-50 supporting clusters
+- ✅ <$5 Gemini CLI cost
+
+**Gap Analysis**:
+- ✅ 10+ GOLDEN opportunities identified
+- ✅ 20+ GOOD opportunities
+- ✅ Research coverage >60%
+- ✅ Podcast queries for gaps
+
+**Internal Linking**:
+- ✅ Health score >80/100
+- ✅ Orphan rate <10%
+- ✅ Avg 5+ links per page
+- ✅ Hub-spoke adherence >80%
+
+## Technical Implementation
+
+**All 12 Scripts**:
+1. `scripts/seo/scrape-reddit-pain-points.js`
+2. `scripts/seo/scrape-quora-questions.js`
+3. `scripts/seo/extract-paa-questions.js`
+4. `scripts/seo/analyze-competitor-coverage.js`
+5. `scripts/seo/extract-keywords-from-forums.js`
+6. `scripts/seo/fetch-serp-urls.js`
+7. `scripts/seo/gemini-serp-clustering.js`
+8. `scripts/seo/build-clusters-from-serp.js`
+9. `scripts/seo/identify-content-gaps.js`
+10. `scripts/seo/identify-research-gaps.js`
+11. `scripts/seo/audit-internal-links.js`
+12. `scripts/seo/weave-internal-links.js`
+
+**Orchestrator**: `.claude/skills/topical-authority/scripts/orchestrator.js`
+
+**Slash Commands**:
+- `/topical-authority-discover` - Phase 1: Forum discovery
+- `/topical-authority-cluster` - Phase 2-3: SERP clustering
+- `/topical-authority-analyze` - Phase 4-5: Gap analysis + linking
+
+## References
+
+- Jake Ward's Topical Authority Framework (YouTube)
+- Implementation Plan: `docs/TOPICAL-AUTHORITY-IMPLEMENTATION-PLAN.md`
+- SERP Clustering Algorithm: Jaccard similarity + Gemini intent analysis
+- Priority Formula: `Volume × (100 - Difficulty)`
+
+## Troubleshooting
+
+**Issue**: SERP fetching blocked by Google
+- **Solution**: Use SERP API (DataForSEO, SerpAPI, ValueSERP) or rotating proxies
+
+**Issue**: Gemini CLI timeout on large datasets
+- **Solution**: Reduce batch size or increase timeout
+
+**Issue**: Low research coverage (<40%)
+- **Solution**: Run podcast-smart-ingestion with research gap queries
+
+**Issue**: Link health score <60/100
+- **Solution**: Run weave-internal-links with --auto-insert
+
+**Issue**: No GOLDEN opportunities found
+- **Solution**: Lower min-volume threshold or expand keyword universe
+
+## Version History
+
+- **v1.0.0** (2025-11-17): Initial implementation with 12 scripts + Gemini CLI orchestration

package/skills/topical-authority/references/jake-ward-framework.md

@@ -0,0 +1,201 @@
+# Jake Ward's Topical Authority Framework
+
+**Source**: Jake Ward's YouTube channel (SEO expert and topical authority specialist)
+
+## Core Philosophy
+
+**Market-First, Not Content-First**: Start with what the market is searching for, not what content you already have. Most SEO strategies fail because they work backward from existing content instead of forward from market demand.
+
+## The 7-Step Framework
+
+### 1. Forum Research (Market Discovery)
+**Goal**: Find real pain points and questions from your target audience
+
+**Sources**:
+- Reddit (subreddits relevant to your niche)
+- Quora (high-engagement questions)
+- People Also Ask (Google's PAA boxes)
+- Competitor content gaps
+
+**Why it works**: Forums reveal what people actually search for, not what you think they search for.
+
+### 2. Keyword Extraction
+**Goal**: Convert forum discussions into searchable keyword variations
+
+**Process**:
+- Extract 5-10 keyword variations per forum item
+- Include longtail variations (2-5 words)
+- Classify by search intent (informational, commercial, transactional)
+- Deduplicate and normalize
+
+**Target**: 500-1,000 keywords for comprehensive topical coverage
+
+### 3. SERP Clustering (Anti-Cannibalization)
+**Goal**: Prevent keyword cannibalization by clustering keywords with same search intent
+
+**Algorithm**:
+1. Fetch top 10 URLs for each keyword
+2. Calculate URL overlap (Jaccard similarity)
+3. Cluster by overlap threshold:
+   - ≥70% overlap → Same cluster (Google sees them as same intent)
+   - <30% overlap → Different clusters (different intent)
+   - 30-69% overlap → Ambiguous, use AI to analyze intent
+
+**Why it works**: Google doesn't rank multiple pages from same site for keywords with identical search intent. Clustering prevents internal competition.
+
+**Cost optimization**: Only use expensive SERP APIs or AI analysis for ambiguous cases (30-69% overlap).
+
+### 4. Hub-and-Spoke Architecture
+**Goal**: Build topical authority through strategic content structure
+
+**Structure**:
+- **Pillar Pages** (Hubs): Comprehensive guides on broad topics (2500+ words)
+- **Cluster Pages** (Spokes): Specific subtopics linking back to pillars (1500+ words)
+- **Bidirectional Linking**: Pillars link to clusters, clusters link back to pillars
+
+**Topical Authority Score**: `(Pillars × 10) + (Clusters × 2) + Total Keywords`
+
+**Why it works**: Google rewards sites that demonstrate comprehensive coverage of a topic through interconnected content.
+
+### 5. Priority Scoring (Attack Weak Points)
+**Goal**: Identify "GOLDEN" opportunities (high volume + low difficulty)
+
+**Formula**: `Priority Score = Volume × (100 - Difficulty)`
+
+**Opportunity Levels**:
+- **GOLDEN** (top 10%): High volume + Very low difficulty (<20) → Attack first!
+- **GOOD** (next 20%): Good volume + Low difficulty (20-40) → Attack second
+- **MEDIUM** (next 30%): Medium volume or medium difficulty → Consider later
+- **SKIP** (bottom 40%): Low volume or high difficulty (>60) → Ignore
+
+**Strategy**: Work smarter, not harder. Start with GOLDEN and GOOD opportunities for fastest ROI.
+
+### 6. Research Validation
+**Goal**: Ensure you have research/expertise to create quality content
+
+**Process**:
+1. Check if research exists for high-priority opportunities
+2. Identify research gaps
+3. Generate search queries for missing research
+4. Acquire research (podcasts, articles, expert interviews)
+
+**Why it works**: Quality content requires quality research. Don't create content you can't back with expertise.
+
+### 7. Internal Linking Optimization
+**Goal**: Strengthen topical authority through strategic internal linking
+
+**Metrics**:
+- **Orphan Rate**: % of pages with no inbound links (target: <10%)
+- **Hub-Spoke Adherence**: % of proper pillar ↔ cluster links (target: >80%)
+- **Linking Density**: Total links / Total pages (target: >0.05)
+- **Health Score**: Overall linking quality (target: >80/100)
+
+**Strategy**:
+1. Fix orphaned pages first (critical)
+2. Complete hub-spoke connections (strategic)
+3. Add contextual links between related content (natural)
+
+## Key Insights
+
+### 1. Start with Market, Not Content
+"Don't ask 'What content should I create?'. Ask 'What is my market searching for?'"
+
+Traditional approach: Content audit → Keyword optimization → Hope for traffic
+Jake Ward approach: Market research → SERP clustering → Strategic content creation
+
+### 2. Prevent Keyword Cannibalization
+"If two keywords have 70%+ SERP overlap, Google sees them as the same intent. Creating two pages will cannibalize your rankings."
+
+Example:
+- "email marketing tools" and "best email marketing software" → 85% overlap → Same page
+- "email marketing" and "email marketing automation" → 25% overlap → Different pages
+
+### 3. Attack Weak Points First
+"Don't compete with giants on difficult keywords. Find the 'weak points' - high volume + low difficulty."
+
+Priority Score = Volume × (100 - Difficulty)
+
+Example:
+- Keyword A: 5,000 volume, 80 difficulty → Priority: 100,000
+- Keyword B: 1,000 volume, 15 difficulty → Priority: 85,000
+
+Keyword B is the better opportunity (lower difficulty, still good traffic potential).
+
+### 4. Topical Authority Beats Single-Article SEO
+"Google doesn't rank pages anymore, it ranks sites. Demonstrate you're an authority on the entire topic."
+
+Single article strategy: 1 pillar page → Limited rankings
+Topical authority strategy: 1 pillar + 10 clusters → Rankings multiply
+
+### 5. Internal Linking is Not Optional
+"Your internal linking structure tells Google what your site is about. Hub-and-spoke is the strongest signal."
+
+Weak signal: Random internal links
+Strong signal: Systematic hub-and-spoke architecture
+
+## Implementation Timeline
+
+**Week 1**: Forum research + Keyword extraction + SERP clustering
+**Week 2**: Hub architecture + Priority scoring + Research validation
+**Week 3**: Content creation for GOLDEN opportunities + Internal linking
+
+**Result**: 5-10 pillar pages + 20-50 cluster pages = Comprehensive topical coverage
+
+## Success Metrics
+
+**Short-term (3 months)**:
+- 50+ keywords ranking in top 100
+- 10+ keywords ranking in top 20
+- Topical authority score >70
+
+**Medium-term (6 months)**:
+- 100+ keywords ranking in top 100
+- 30+ keywords ranking in top 20
+- 5+ keywords ranking in top 10
+- Topical authority score >85
+
+**Long-term (12 months)**:
+- 200+ keywords ranking in top 100
+- 50+ keywords ranking in top 20
+- 20+ keywords ranking in top 10
+- Topical authority score >95
+- Recognized as authority in niche
+
+## Common Mistakes to Avoid
+
+1. **Starting with content audit**: Wrong order. Start with market research.
+2. **Ignoring SERP overlap**: Creates keyword cannibalization.
+3. **Targeting only high-volume keywords**: Misses GOLDEN opportunities (high volume + low difficulty).
+4. **Creating content without research**: Results in thin, low-quality content.
+5. **Random internal linking**: Weakens topical authority signal.
+
+## Tools & Resources
+
+**Required**:
+- Forum scraping (Reddit API, Quora, PAA extraction)
+- Keyword research (Google Ads API, SEMrush, Ahrefs)
+- SERP analysis (DataForSEO, SerpAPI, or free scraping)
+- AI for intent analysis (GPT-4, Claude, Gemini)
+
+**Optional**:
+- Rank tracking (Google Search Console, Ahrefs, SEMrush)
+- Content optimization (Surfer SEO, Clearscope, Frase)
+
+## Our Implementation
+
+We've built 12 scripts that automate this entire framework:
+
+**Scripts 1-5**: Forum research + Keyword extraction
+**Scripts 6-8**: SERP clustering + Hub architecture
+**Scripts 9-10**: Priority scoring + Research validation
+**Scripts 11-12**: Internal linking audit + Optimization
+
+**Cost**: ~$2-10 for 500-1,000 keywords (vs $50/mo subscriptions)
+**Time**: 3-4 hours for complete analysis (vs weeks of manual work)
+**Token savings**: 95%+ via Gemini CLI delegation
+
+## Additional Resources
+
+- Jake Ward YouTube Channel: In-depth SEO strategy videos
+- Implementation Plan: `docs/TOPICAL-AUTHORITY-IMPLEMENTATION-PLAN.md`
+- All scripts: `scripts/seo/*.js`