@jairodri/huckleberry-cli 1.0.1 → 1.1.0

package/skills/keyword-research/SKILL.md

@@ -0,0 +1,503 @@
+---
+name: keyword-research
+description: >
+  Strategic keyword research powered by web search and brand context. Use this
+  skill whenever the user mentions keywords, keyword research, SEO topics,
+  content topics, 'what should I write about', content strategy, blog ideas,
+  search traffic, or content planning. Also trigger when the user wants to plan
+  what content to create, when existing content isn't attracting search traffic,
+  when any skill needs keyword-plan.md but it doesn't exist, or when the user
+  asks about SEO in the context of content creation. Even casual mentions like
+  'I need blog post ideas' or 'what topics should I cover' warrant this skill.
+  8-phase process from seed to content brief.
+---
+
+
+## On Activation
+
+1. Check if `brand/` directory exists in the project root.
+2. If it does, read available files: `voice-profile.md`, `positioning.md`, `audience.md`, `creative-kit.md`, `stack.md`, `learnings.md`.
+3. Apply any loaded brand context to enhance output quality.
+4. If `brand/` does not exist, proceed without it — this skill works standalone.
+
+> **Note:** Examples below use fictional brands (Acme, Lumi, Helm). Replace with your own brand context.
+
+# /keyword-research -- Data-Backed Keyword Strategy
+
+Most keyword research is backwards. People start with tools, get overwhelmed by
+data, and end up with a spreadsheet they never use.
+
+This skill starts with strategy. What does your business need? Who are you trying
+to reach? What would make them find you? Then it validates with live search data
+and builds a content plan that actually makes sense.
+
+No expensive tools required. Systematic thinking plus web search.
+
+**Reads:** `positioning.md`, `audience.md`, `competitors.md`, `learnings.md`
+**Writes:** `brand/keyword-plan.md`, `campaigns/content-plan/*.md`
+
+---
+
+## Iteration Detection
+
+Before starting, check whether `./brand/keyword-plan.md` already exists.
+
+### If keyword-plan.md EXISTS --> Refresh Mode
+
+Do not start from scratch. Instead:
+
+1. Read the existing plan.
+2. Present a summary of the current keyword strategy:
+   ```
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+     EXISTING KEYWORD PLAN
+     Last updated {date} by /keyword-research
+
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+     Pillars:
+     ├── {Pillar 1}    {N} clusters    Priority: {level}
+     ├── {Pillar 2}    {N} clusters    Priority: {level}
+     └── {Pillar 3}    {N} clusters    Priority: {level}
+
+     Top keywords:
+     ├── {keyword 1}   {priority}
+     ├── {keyword 2}   {priority}
+     └── {keyword 3}   {priority}
+
+     Content briefs: {N} created, {N} published
+
+     ──────────────────────────────────────────────
+
+     What would you like to do?
+
+     ① Refresh with new SERP data
+     ② Add a new topic area
+     ③ Re-prioritize existing clusters
+     ④ Full rebuild from scratch
+     ⑤ Generate briefs for top keywords
+   ```
+
+3. Process the user's choice:
+   - Option ① --> Re-run web search for existing keywords, update priorities based on fresh data
+   - Option ② --> Gather new seed keywords, run full expansion, merge into existing plan
+   - Option ③ --> Re-score all clusters with updated business context
+   - Option ④ --> Full process from scratch
+   - Option ⑤ --> Skip to content brief generation for highest-priority unfilled clusters
+
+4. Before overwriting, show a diff of what changed:
+   ```
+   Changes to keyword plan:
+
+   New clusters added:
+   ├── "AI email marketing" (Pillar: AI Marketing)
+   └── "automated content creation" (Pillar: AI Marketing)
+
+   Priority changes:
+   ├── "marketing automation" High → Critical
+   └── "fractional CMO" Medium → Low
+
+   Removed:
+   └── "our methodology" (failed validation)
+
+   Save these changes? (y/n)
+   ```
+
+5. Only overwrite after explicit confirmation.
+
+### If keyword-plan.md DOES NOT EXIST --> Full Research Mode
+
+Proceed to the full process below.
+
+---
+
+## The Core Job
+
+Transform a business context into a **prioritized content plan** with:
+- Keyword clusters organized by topic
+- Priority ranking based on opportunity and live SERP data
+- Content type recommendations
+- Individual content briefs for top keywords
+- A clear "start here" action
+
+**Output format:** Clustered keywords mapped to content pieces, prioritized by
+business value, competitive opportunity, and search demand. Saved to disk as
+a keyword plan and individual content briefs.
+
+---
+
+## The Process
+
+```
+SEED --> EXPAND --> SEARCH --> CLUSTER --> VALIDATE --> PRIORITIZE --> MAP --> BRIEF
+```
+
+1. **Seed** -- Generate initial keywords from business context and brand memory
+2. **Expand** -- Use the 6 Circles Method to build the full list
+3. **Search** -- Pull live SERP data: autocomplete, People Also Ask, competitor rankings
+4. **Cluster** -- Group related keywords into content pillars
+5. **Validate** -- Run 4-check pillar validation with live competitive data
+6. **Prioritize** -- Score by opportunity, business value, and search evidence
+7. **Map** -- Assign clusters to specific content pieces
+8. **Brief** -- Generate individual content briefs for top priorities
+
+---
+
+## Before Starting: Gather Context
+
+Get these inputs before generating anything. If brand memory files exist, pre-fill
+what you can and confirm with the user.
+
+1. **What do you sell/offer?** (1-2 sentences)
+   - Pre-fill from: ./brand/positioning.md
+2. **Who are you trying to reach?** (Be specific)
+   - Pre-fill from: ./brand/audience.md
+3. **What is your website?** (To understand current content)
+4. **Who are 2-3 competitors?** (Or help identify them)
+   - Pre-fill from: ./brand/competitors.md
+5. **What is the goal?** (Traffic? Leads? Sales? Authority?)
+6. **Timeline?** (Quick wins or long-term plays?)
+
+If brand memory supplies 3+ of these, present what you found and ask for
+confirmation rather than re-asking:
+
+```
+  From your brand profile:
+
+  ├── Offer       "{from positioning.md}"
+  ├── Audience    "{from audience.md}"
+  ├── Competitors {list from competitors.md}
+  └── Positioning "{angle from positioning.md}"
+
+  Does this still look right? And two more
+  questions:
+
+  1. What is the goal -- traffic, leads, sales,
+     or authority?
+  2. Timeline -- quick wins or long-term plays?
+```
+
+---
+
+## Phase 1: Seed Generation
+
+From the business context (and brand memory if loaded), generate 20-30 seed
+keywords covering:
+
+**Direct terms** -- What you actually sell
+> "AI marketing automation", "fractional CMO", "marketing workflows"
+
+**Problem terms** -- What pain you solve
+> "can't keep up with content", "marketing team too small", "don't understand AI"
+
+**Outcome terms** -- What results you deliver
+> "faster campaign execution", "10x content production", "marketing ROI"
+
+**Category terms** -- Broader industry terms
+> "marketing automation", "AI marketing", "growth marketing"
+
+**Brand-aligned terms** -- From positioning if loaded
+> If positioning is "The Anti-Agency" → seed "agency alternatives", "in-house marketing",
+> "DIY marketing strategy"
+> If positioning is "AI-First Marketing" → seed "AI marketing tools", "automated campaigns",
+> "machine learning marketing"
+
+---
+
+## Phase 2: Expand (The 6 Circles Method)
+
+> See references/keyword-examples.md for detailed expansion techniques.
+
+1. **What You Sell** -- Direct product/service terms
+2. **Problems You Solve** -- Pain points and challenges
+3. **Outcomes You Deliver** -- Results and benefits
+4. **Your Unique Positioning** -- Differentiators
+5. **Adjacent Topics** -- Related audience interests
+6. **Entities to Associate With** -- People, brands, tools
+
+---
+
+## Phase 3: Web Search Validation (Exa-stack canonical)
+
+Data-backed research layer for each pillar keyword + top 30-50 expansions. Canonical stack (mktg-native, no Ahrefs): Exa MCP (`web_search_advanced_exa`, `deep_search_exa`, `company_research_exa`) + Firecrawl (autocomplete + SERP scrape) + `/last30days` (Reddit/X/HN aggregation) + `gh` CLI (OSS GitHub-stars) + **Agent-Reach** (skill: `agent-reach`) for Exa search (`mcporter call 'exa.web_search_exa(...)'`). For Ahrefs precision see appendix in `seo-machine/references/exa-recipes.md`.
+
+### If Web Search Is Unavailable
+
+Proceed with Phase 1 (seed generation) and Phase 2 (6 Circles expansion) using brand context only. Skip Phase 3 entirely but note the limitation to the user: 'Keyword clusters are based on strategic assessment, not live SERP data. Validate against actual search results before committing to content production.' Cluster and prioritize based on brand alignment and audience pain points rather than search volume.
+
+**Check Agent-Reach first**: Run `agent-reach doctor --json` — it may have Exa via mcporter configured even when standalone Exa MCP isn't available.
+
+### Step 1: Google Autocomplete Mining
+
+For each seed and pillar keyword, search for autocomplete suggestions:
+
+```
+Search: "[keyword] a", "[keyword] b", ... "[keyword] z"
+Search: "how to [keyword]"
+Search: "best [keyword]"
+Search: "why [keyword]"
+Search: "[keyword] vs"
+Search: "[keyword] for"
+```
+
+Capture every unique suggestion. These are real queries people type.
+
+**What to look for:**
+- Suggestions you did not think of (add to expanded list)
+- Recurring modifiers (signals what people care about)
+- Question patterns (signals informational intent)
+- Brand/product mentions (signals commercial intent)
+- Year modifiers ("2026") signal freshness demand
+
+### Step 2: People Also Ask (PAA) Mining
+
+For each pillar keyword, search Google and capture the People Also Ask boxes:
+
+```
+Search: "[pillar keyword]"
+→ Capture PAA questions
+→ Click/expand each PAA to get follow-up PAAs
+→ Capture the second-level questions too
+```
+
+**What PAA data reveals:**
+- The exact questions your audience asks (use as H2s in content)
+- Related subtopics Google associates with this keyword
+- Content gaps -- if PAA answers are thin, opportunity exists
+- Semantic relationships between topics
+
+**How to use PAA data:**
+- Add new questions to your expanded keyword list
+- Map PAA questions to content sections within pillar articles
+- Identify PAA questions that deserve standalone articles
+- Use PAA phrasing in headers (matches how people search)
+
+### Step 3: SERP Analysis
+
+For each priority keyword, examine the top search results:
+
+```
+Search: "[keyword]"
+→ Analyze the top 5-10 results
+→ Note: content type, word count, freshness, domain authority
+```
+
+**Capture for each result:**
+- Title and URL
+- Content type (guide, listicle, comparison, tool page, etc.)
+- Freshness (when was it published/updated?)
+- Quality assessment (comprehensive or thin?)
+- Domain type (major publication, niche site, personal blog?)
+
+**SERP signals:** Old results (2+ years) = freshness opportunity. Thin results (<1000 words) = depth opportunity. All big brands (DR 80+) = hard to win, try long-tail. Mixed big + small sites = winnable. Forums/Reddit in top 5 = huge content gap. Featured snippet = optimize for snippet format.
+
+### Step 4: Competitor Content Analysis
+
+If ./brand/competitors.md is loaded (or competitors were provided), search
+for what they rank for:
+
+```
+Search: "site:{competitor-domain.com} [topic]"
+Search: "{competitor name} [pillar keyword]"
+Search: "{competitor name} blog"
+```
+
+**Build a competitor content map** for each competitor: topics covered, content types, keywords targeted, gaps, and quality. Identify three priority gap types: (1) catch-up — topics all competitors cover but you don't, (2) blue ocean — topics nobody covers well, (3) improvement — topics where competitors are weak/outdated.
+
+### Search Integration Output
+
+After web search, present a summary before clustering: total terms found, top 3 discoveries (unexpected keywords, competitor gaps, PAA insights), and new keywords added from search. Show counts for autocomplete suggestions, PAA questions, SERPs analyzed, and competitor pages reviewed.
+
+---
+
+## Phase 4: Cluster
+
+Group expanded keywords (including web search discoveries) into content pillars
+using the hub-and-spoke model:
+
+```
+                    [PILLAR]
+                 Main Topic Area
+                      |
+        +-------------+-------------+
+        |             |             |
+   [CLUSTER 1]   [CLUSTER 2]   [CLUSTER 3]
+    Subtopic       Subtopic       Subtopic
+        |             |             |
+    Keywords      Keywords      Keywords
+```
+
+### Identifying Pillars (5-10 per business)
+
+A pillar is a major topic area that could support:
+- One comprehensive guide (3,000-8,000 words)
+- 3-7 supporting articles
+- Ongoing content expansion
+
+Ask: "Could this be a complete guide that thoroughly covers the topic?"
+
+### Clustering Process
+
+1. **Group by semantic similarity** -- Keywords that mean similar things
+2. **Group by search intent** -- Keywords with same user goal
+3. **Identify the pillar keyword** -- The broadest term in each group
+4. **Identify supporting keywords** -- More specific variations
+5. **Attach PAA questions** -- Map People Also Ask questions to the cluster they belong to
+6. **Note competitor coverage** -- Mark which competitors cover this cluster
+
+
+> See references/keyword-examples.md for example cluster with search data.
+
+---
+
+## Phase 5: Pillar Validation
+
+> See references/keyword-examples.md for validation criteria.
+
+Validate: search volume, competition, content-market fit, business alignment.
+
+---
+
+## Phase 6: Prioritize
+
+Not all keywords are equal. Score each cluster using both strategic assessment
+AND live search evidence from Phase 3.
+
+Score each cluster on three dimensions:
+
+- **Business Value** (High/Medium/Low): How directly does this connect to revenue? Commercial intent keywords close to purchase = High. Educational/authority content = Medium. Top-of-funnel brand awareness = Low.
+- **Opportunity** (High/Medium/Low): What does the SERP data show? Forums ranking, outdated content, thin results = High opportunity. DR 80+ sites with comprehensive content = Low.
+- **Speed to Win** (Fast/Medium/Long): Low competition with unique expertise = Fast (3 months). Moderate competition = Medium (6 months). High competition needing authority = Long (9-12 months).
+
+**Priority:** High Value + High Opportunity + Fast = DO FIRST. High + High + Medium = DO SECOND. Medium + High + Fast = QUICK WIN. High + Low = LONG PLAY. Low value = BACKLOG.
+
+### DR-Cap + Confidence Labels (mandatory filters)
+Apply **DR-cap** (`KD > DR + buffer` → `out_of_reach` → BACKLOG) and tag every keyword with a 3-tier `confidence` label (`high`/`medium`/`estimated`). Table + output schema: `references/dr-cap-and-confidence.md`.
+
+---
+
+## Phase 7: Map to Content
+
+For each priority cluster, assign a content type (Pillar Guide, How-To, Comparison, Listicle, Use Case, or Definition), match to search intent (Informational, Commercial, Transactional), and place in the content calendar (Tier 1-4 over 12 weeks).
+
+Use PAA questions to build article outlines — each PAA question becomes an H2, aligning content structure with what Google knows people are asking.
+
+> See references/keyword-examples.md for content type tables, intent matching rules, calendar tiers, and PAA-driven outline examples.
+
+---
+
+## Phase 8: Content Brief Generation
+
+> See references/keyword-examples.md for brief template and keyword plan format.
+
+Generate briefs for top-priority keywords: target keyword, search intent, content type, SERP snapshot, PAA questions, outline, angle.
+
+---
+
+## Output Format
+
+See `references/keyword-examples.md` for the full terminal output template and keyword plan file format. Use the premium formatting system for terminal output (box-drawing characters, section headers) and standard markdown for files saved to disk.
+
+---
+
+## Chain to /seo-content
+
+After presenting the keyword plan, actively offer to chain into content
+creation for the top-priority keyword:
+
+```
+  ──────────────────────────────────────────────
+
+  READY TO WRITE?
+
+  Your top-priority keyword is "{keyword}" with
+  a content brief ready at
+  ./campaigns/content-plan/{slug}.md
+
+  I can write this article now using /seo-content.
+  It will use your brand voice, the content brief,
+  and the SERP data I just gathered.
+
+  → "Write it" to start /seo-content now
+  → "Not yet" to save the plan and stop here
+
+  ──────────────────────────────────────────────
+```
+
+If the user says "write it" or similar, hand off to /seo-content with:
+- The content brief file path
+- The keyword plan context
+- The SERP analysis from Phase 3
+- Brand memory context already loaded
+
+---
+
+
+> See references/keyword-examples.md for a complete worked example.
+
+---
+
+## Worked Example
+
+**Cluster: 'verified meal delivery'**
+
+| Keyword | Volume | Difficulty | Intent | Priority |
+|---|---|---|---|---|
+| verified meal delivery near me | 12,100 | 45 | Transactional | P1 |
+| verified-source restaurants that deliver | 3,600 | 38 | Transactional | P1 |
+| is doordash organic | 2,900 | 22 | Informational | P2 |
+| verified meal prep delivery | 1,300 | 31 | Transactional | P2 |
+| verifiedeats delivery | 880 | 15 | Navigational | P3 |
+
+**Content brief:** Target 'verified meal delivery near me' with a city-specific landing page template (programmatic SEO). Target 'is doordash organic' with a comparison article linking to Acme.
+
+---
+
+## What This Skill Does NOT Do
+
+This skill provides **strategic direction backed by search data**, not:
+- Exact search volume numbers (use paid tools like exa MCP or web search for precision)
+- Automated rank tracking (different tool category)
+- Content writing (use /seo-content skill after brief generation)
+- Technical SEO audits (different skill set)
+- Link building strategy (separate from content strategy)
+
+The output is a validated, prioritized plan with content briefs. Execution
+is handled by /seo-content and other downstream skills.
+
+---
+
+
+> See references/keyword-examples.md for free tools.
+
+---
+
+## How This Skill Connects to Others
+
+**keyword-research** creates the content strategy. Then: /seo-content writes articles from briefs, /positioning-angles finds the angle for each piece, /direct-response-copy handles commercial-intent landing pages, /content-atomizer repurposes pillar content, and /lead-magnet creates assets for top-of-funnel keywords.
+
+---
+
+## The Test
+
+A good keyword research output is data-backed (SERP evidence, not intuition), actionable (clear "start here" with a brief ready), prioritized (ranked by opportunity), realistic (acknowledges competition), strategic (connects to business goals), specific (content types and outlines, not just keywords), and executable (briefs ready for /seo-content). If the output is "here's 500 keywords, good luck" — it failed.
+
+---
+
+
+## Progressive Enhancement Levels
+
+| Level | Context Available | Output Quality |
+|-------|------------------|---------------|
+| L0 | Product name only, no web search | Basic seed keywords, strategic clusters, estimated priorities |
+| L1 | + brand files (positioning, audience) | Brand-aligned keywords, audience-informed clusters |
+| L2 | + competitors.md | Competitor gap analysis, differentiated content strategy |
+| L3 | + web search available | Live SERP data, validated priorities, PAA-driven outlines |
+| L4 | + existing keyword-plan.md (refresh) | Evolved plan with trend tracking, updated priorities |
+
+---
+
+## Feedback
+
+After delivering the keyword plan, append learnings to `brand/learnings.md` when the user provides feedback on what worked or what they changed.

package/skills/keyword-research/references/dr-cap-and-confidence.md

@@ -0,0 +1,62 @@
+# DR-Cap Heuristic + 3-Tier Confidence Labels
+
+Two filters every keyword cluster goes through in Phase 6 before priority ranking.
+
+## DR-Cap (non-negotiable filter)
+
+A site can only rank for keywords with `KD (keyword difficulty) ≤ DR (domain rating) + buffer`. Targeting head terms above the cap = wasted work — pages don't rank, no traffic, just compounding indexation debt.
+
+| Site DR (0–100) | Max winnable KD | Rationale |
+|---|---|---|
+| 0–10 (greenfield) | ≤30 | Stick to long-tail + branded comparison. Anything else is a doomed phase. |
+| 10–20 | ≤40 | Use-case + alternatives pages with low-KD modifiers. |
+| 20–30 | ≤50 | Mid-volume commercial terms become winnable. |
+| 30–50 | ≤60 | Most useful niche head terms in range. |
+| 50+ | ≤70 | Compete on anything except brand-direct mega-volume. |
+
+**How to apply:**
+- For each cluster, compute `cluster_max_kd = max(keyword.kd for keyword in cluster)`.
+- If `cluster_max_kd > DR_CAP` → flag as `out_of_reach`.
+- Demote `out_of_reach` clusters to BACKLOG, OR replace the seed keyword with a longer-tail variant that brings KD under the cap.
+- Be honest with the user when this triggers: "You can't rank for 'social media management tool' at DR 8 — KD 78. Closest winnable alternative: '[brand] alternatives for agencies' at KD 18."
+
+**Where DR comes from** (Exa-native proxy, no Ahrefs required):
+
+| Signal | What it tells us |
+|---|---|
+| Indexed-page count via `mcp__exa__web_search_advanced_exa(query: "site:<domain>", numResults: 100)` | <50 pages → DR 0–10; 50-500 → 10–25; 500–5000 → 25–45; 5000+ → 45+ |
+| Brand-mention count via `mcp__exa__web_search_advanced_exa(query: "<brand-name> -site:<own-domain>", numResults: 30)` | <20 unique referring domains → DR <15; 100+ → DR 25+ |
+| `mcp__exa__company_research_exa(companyName: "<brand>")` | Recognized business profile signals established DR (rough +5-10 to estimate) |
+| (OSS only) `gh repo view <owner/repo> --json stargazerCount` | >1k stars → +5 to DR estimate; >10k stars → +10 |
+| Ahrefs MCP `site-explorer-domain-rating` (if paid sub configured) | Exact numeric DR (0-100) — replaces the proxy when available |
+| Default fallback | DR 10 if no data — under-estimating is safer than over-target |
+
+Persist the result to `.seo/config.json` as `domain_rating_estimate`. The full Exa-native DR proxy is documented as **Recipe A** in `skills/seo-machine/references/exa-recipes.md`.
+
+## 3-Tier Confidence Labels
+
+Every keyword in `brand/keyword-plan.md` gets a `confidence` field reflecting how trustworthy the volume/KD estimate is. Downstream skills (seo-machine, seo-content) use this to prioritize high-confidence opportunities and flag low-confidence ones for human review before publishing.
+
+| Tier | Criteria | Source pattern |
+|---|---|---|
+| `high` | Multiple independent sources agree | Ahrefs MCP + GSC + SERP scrape concur within ±20% on volume |
+| `medium` | Single tool reports the number, SERP scrape consistent | Exa SERP scrape + autocomplete + one paid tool |
+| `estimated` | No tool data, inferred | Category averages, PAA mining, or pure heuristic |
+
+**Output schema (in `brand/keyword-plan.md` per keyword row):**
+
+```yaml
+keyword: "competitor-x alternatives"
+volume: 320
+kd: 18
+confidence: high   # or: medium / estimated
+sources: [ahrefs, exa-serp]
+```
+
+**Validation rule:** any keyword targeted in a content brief must be `confidence: high` OR `confidence: medium`. Pages targeting `confidence: estimated` keywords get a "validate before commit" flag in the seo-machine roadmap — either wait for post-launch GSC data or paste Ahrefs/Semrush numbers from the user's existing UI to upgrade the confidence tier.
+
+**Why this matters:** keyword-research today emits keyword data with no signal of how trustworthy each number is. Downstream consumers treat all data equally and ship pages targeting numbers that turn out to be off by 10× in either direction. Confidence tags let seo-machine prioritize correctly and let `mktg compete` know which numbers to recompute periodically.
+
+## Reference implementation
+
+The same DR-cap math + confidence labels are encoded in `skills/seo-machine/references/ahrefs-recipes.md` (the cookbook seo-machine consumes during Initialize). Keep these two docs in sync — if the DR-cap thresholds change here, update the cookbook there.