@jairodri/huckleberry-cli 1.0.1 → 1.1.0

package/skills/seo-content/references/pseo-playbooks.md

@@ -0,0 +1,226 @@
+# The 12 Programmatic SEO Playbooks
+
+Proven playbooks for building SEO-optimized pages at scale using templates and data.
+
+---
+
+## 1. Templates
+
+**Pattern**: "[Type] template" or "free [type] template"
+**Example**: "resume template", "invoice template", "pitch deck template"
+
+**Why it works**: High intent (people need it now), shareable/linkable assets,
+natural for product-led companies.
+
+**Value requirements**: Actually usable templates (not just previews), multiple
+variations per type, quality comparable to paid options.
+
+**URL structure**: `/templates/[type]/` or `/templates/[category]/[type]/`
+
+---
+
+## 2. Curation
+
+**Pattern**: "best [category]" or "top [number] [things]"
+**Example**: "best website builders", "top 10 crm software"
+
+**Why it works**: Comparison shoppers, high commercial intent, evergreen with updates.
+
+**Value requirements**: Genuine evaluation criteria, real testing or expertise,
+regular updates (date visible).
+
+**URL structure**: `/best/[category]/` or `/[category]/best/`
+
+---
+
+## 3. Conversions
+
+**Pattern**: "[X] to [Y]" or "[amount] [unit] in [unit]"
+**Example**: "$10 USD to GBP", "100 kg to lbs", "pdf to word"
+
+**Why it works**: Instant utility, extremely high search volume, repeat usage.
+
+**Value requirements**: Accurate real-time data, fast functional tool, related
+conversions suggested, mobile-friendly.
+
+**URL structure**: `/convert/[from]-to-[to]/`
+
+---
+
+## 4. Comparisons
+
+**Pattern**: "[X] vs [Y]" or "[X] alternative"
+**Example**: "webflow vs wordpress", "figma alternatives"
+
+**Why it works**: High purchase intent, clear search pattern, scales with competitors.
+
+**Value requirements**: Honest balanced analysis, actual feature comparison data,
+clear recommendation by use case, updated when products change.
+
+**URL structure**: `/compare/[x]-vs-[y]/` or `/[x]-vs-[y]/`
+
+---
+
+## 5. Examples
+
+**Pattern**: "[type] examples" or "[category] inspiration"
+**Example**: "saas landing page examples", "email subject line examples"
+
+**Why it works**: Research phase traffic, highly shareable, natural for design tools.
+
+**Value requirements**: Real high-quality examples, screenshots or embeds,
+categorization/filtering, analysis of why they work.
+
+**URL structure**: `/examples/[type]/` or `/[type]-examples/`
+
+---
+
+## 6. Locations
+
+**Pattern**: "[service/thing] in [location]"
+**Example**: "coworking spaces in san diego", "dentists in austin"
+
+**Why it works**: Local intent is massive, scales with geography, natural for
+marketplaces/directories.
+
+**Value requirements**: Actual local data (not just city name swapped), local
+providers listed, location-specific insights (pricing, regulations).
+
+**URL structure**: `/[service]/[city]/` or `/locations/[city]/[service]/`
+
+---
+
+## 7. Personas
+
+**Pattern**: "[product] for [audience]" or "[solution] for [role/industry]"
+**Example**: "payroll software for agencies", "crm for real estate"
+
+**Why it works**: Speaks directly to searcher's context, higher conversion than
+generic pages, scales with personas.
+
+**Value requirements**: Genuine persona-specific content, relevant features
+highlighted, testimonials from that segment.
+
+**URL structure**: `/for/[persona]/` or `/solutions/[industry]/`
+
+---
+
+## 8. Integrations
+
+**Pattern**: "[your product] [other product] integration"
+**Example**: "slack asana integration", "hubspot salesforce sync"
+
+**Why it works**: Captures users of other products, high intent, scales with
+integration ecosystem.
+
+**Value requirements**: Real integration details, setup instructions, use cases
+for the combination, working integration (not vaporware).
+
+**URL structure**: `/integrations/[product]/` or `/connect/[product]/`
+
+---
+
+## 9. Glossary
+
+**Pattern**: "what is [term]" or "[term] definition"
+**Example**: "what is pSEO", "api definition"
+
+**Why it works**: Top-of-funnel awareness, establishes expertise, natural internal
+linking opportunities.
+
+**Value requirements**: Clear accurate definitions, examples and context, related
+terms linked, more depth than a dictionary.
+
+**URL structure**: `/glossary/[term]/` or `/learn/[term]/`
+
+---
+
+## 10. Translations
+
+**Pattern**: Same content in multiple languages
+**Example**: localized content for different markets
+
+**Why it works**: Opens entirely new markets, lower competition in many languages,
+multiplies content reach.
+
+**Value requirements**: Quality translation (not just Google Translate), cultural
+localization, hreflang tags, native speaker review.
+
+**URL structure**: `/[lang]/[page]/` or `yoursite.com/es/`, `/de/`, etc.
+
+---
+
+## 11. Directory
+
+**Pattern**: "[category] tools" or "[type] software"
+**Example**: "ai copywriting tools", "email marketing software"
+
+**Why it works**: Research phase capture, link building magnet, natural for
+aggregators/reviewers.
+
+**Value requirements**: Comprehensive coverage, useful filtering/sorting, details
+per listing, regular updates.
+
+**URL structure**: `/directory/[category]/` or `/[category]-directory/`
+
+---
+
+## 12. Profiles
+
+**Pattern**: "[person/company name]" or "[entity] + [attribute]"
+**Example**: "stripe ceo", "airbnb founding story"
+
+**Why it works**: Informational intent traffic, builds topical authority, natural
+for B2B and research.
+
+**Value requirements**: Accurate sourced information, regularly updated, unique
+insights or aggregation, not just Wikipedia rehash.
+
+**URL structure**: `/people/[name]/` or `/companies/[name]/`
+
+---
+
+## Choosing Your Playbook
+
+### Match to Your Assets
+
+| If you have... | Consider... |
+|----------------|-------------|
+| Proprietary data | Stats, Directories, Profiles |
+| Product with integrations | Integrations |
+| Design/creative product | Templates, Examples |
+| Multi-segment audience | Personas |
+| Local presence | Locations |
+| Tool or utility product | Conversions |
+| Content/expertise | Glossary, Curation |
+| International potential | Translations |
+| Competitor landscape | Comparisons |
+
+### Combine Playbooks
+
+Layer multiple playbooks for compounding effect:
+- **Locations + Personas**: "Marketing agencies for startups in Austin"
+- **Curation + Locations**: "Best coworking spaces in San Diego"
+- **Integrations + Personas**: "Slack for sales teams"
+- **Glossary + Translations**: Multi-language educational content
+
+---
+
+## Data Defensibility Hierarchy
+
+1. **Proprietary** (you created it) -- strongest
+2. **Product-derived** (from your users)
+3. **User-generated** (your community)
+4. **Licensed** (exclusive access)
+5. **Public** (anyone can use) -- weakest
+
+---
+
+## Common Mistakes
+
+- **Thin content**: Just swapping city names in identical content
+- **Keyword cannibalization**: Multiple pages targeting same keyword
+- **Over-generation**: Creating pages with no search demand
+- **Poor data quality**: Outdated or incorrect information
+- **Ignoring UX**: Pages exist for Google, not users
+- **Doorway pages**: No genuine utility, just keyword targeting

package/skills/seo-content/references/schema-templates.md

@@ -0,0 +1,104 @@
+# Schema Markup Templates (JSON-LD)
+
+Generate these for every article. Include in frontmatter.
+
+---
+
+## Article Schema (Required for ALL content)
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Article",
+  "headline": "{SEO-optimized title}",
+  "description": "{meta description}",
+  "author": {
+    "@type": "Person",
+    "name": "{author name from brand context or user input}"
+  },
+  "datePublished": "{YYYY-MM-DD}",
+  "dateModified": "{YYYY-MM-DD}",
+  "publisher": {
+    "@type": "Organization",
+    "name": "{brand name from brand context or user input}"
+  },
+  "mainEntityOfPage": {
+    "@type": "WebPage",
+    "@id": "{URL placeholder -- user fills in}"
+  },
+  "keywords": ["{primary keyword}", "{secondary 1}", "{secondary 2}"]
+}
+```
+
+---
+
+## FAQ Schema (Required when FAQ section exists)
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "FAQPage",
+  "mainEntity": [
+    {
+      "@type": "Question",
+      "name": "{FAQ question 1 from PAA}",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "{Answer text}"
+      }
+    },
+    {
+      "@type": "Question",
+      "name": "{FAQ question 2 from PAA}",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "{Answer text}"
+      }
+    }
+  ]
+}
+```
+
+---
+
+## HowTo Schema (Required for how-to content type)
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "HowTo",
+  "name": "{title}",
+  "description": "{meta description}",
+  "step": [
+    {
+      "@type": "HowToStep",
+      "name": "{Step 1 title}",
+      "text": "{Step 1 description}"
+    },
+    {
+      "@type": "HowToStep",
+      "name": "{Step 2 title}",
+      "text": "{Step 2 description}"
+    }
+  ]
+}
+```
+
+---
+
+## Schema Output Location
+
+Include in the article's YAML frontmatter as multiline strings:
+
+```yaml
+---
+schema_article: |
+  {Article JSON-LD}
+schema_faq: |
+  {FAQ JSON-LD}
+schema_howto: |
+  {HowTo JSON-LD -- only for how-to content}
+---
+```
+
+This lets users copy directly into their CMS.

package/skills/seo-content/references/serp-analysis-format.md

@@ -0,0 +1,151 @@
+# SERP Analysis Format
+
+Use Exa MCP or firecrawl for live SERP research. Present findings in this format.
+
+---
+
+## SERP Analysis Output
+
+```
+──────────────────────────────────────────────
+
+SERP ANALYSIS: "{target keyword}"
+
+Top 5 results:
+├── 1. {Title} -- {domain}
+│      {content type}, ~{N} words, {date}
+│      Angle: {their angle}
+│      Gap: {what they miss}
+│
+├── 2. {Title} -- {domain}
+│      {content type}, ~{N} words, {date}
+│      Angle: {their angle}
+│      Gap: {what they miss}
+│
+├── 3. {Title} -- {domain}
+│      {content type}, ~{N} words, {date}
+│      Angle: {their angle}
+│      Gap: {what they miss}
+│
+├── 4. {Title} -- {domain}
+│      {content type}, ~{N} words, {date}
+│      Angle: {their angle}
+│      Gap: {what they miss}
+│
+└── 5. {Title} -- {domain}
+       {content type}, ~{N} words, {date}
+       Angle: {their angle}
+       Gap: {what they miss}
+
+──────────────────────────────────────────────
+
+SERP FEATURES
+
+├── Featured Snippet    {format or "none"}
+├── People Also Ask     {N} questions captured
+└── AI Overview         {present/absent, summary}
+
+──────────────────────────────────────────────
+
+OPPORTUNITY ASSESSMENT
+
+{1-3 sentence summary of the gap your content
+will fill and why it can win}
+
+──────────────────────────────────────────────
+```
+
+---
+
+## People Also Ask Capture
+
+Pull ALL PAA questions for the target keyword.
+
+**How to capture:**
+1. Search the target keyword
+2. Record every PAA question shown
+3. Click/expand each PAA to get second-level questions
+4. Record those too
+5. Search 2-3 keyword variations to find additional PAA questions
+
+**How PAA shapes the content:**
+- Each PAA question becomes an H2 or FAQ entry
+- Answer PAA questions directly (Featured Snippet format)
+- PAA phrasing is used in headers (matches how people search)
+- Questions that deserve depth become full sections
+- Questions that need brief answers go in the FAQ section
+
+**PAA output:**
+
+```
+PEOPLE ALSO ASK
+
+Full sections (answer as H2):
+├── "{question 1}" -- high search signal
+├── "{question 2}" -- aligns with content type
+└── "{question 3}" -- competitive gap
+
+FAQ entries (answer briefly):
+├── "{question 4}"
+├── "{question 5}"
+├── "{question 6}"
+└── "{question 7}"
+```
+
+---
+
+## Gap Analysis
+
+After reviewing competitors and PAA, identify:
+
+1. **What is missing?** -- Questions unanswered, angles unexplored
+2. **What is outdated?** -- Old information, deprecated methods
+3. **What is generic?** -- Surface-level advice anyone could give
+4. **What is your edge?** -- Unique data, experience, perspective (from positioning.md)
+
+Your content should fill these gaps.
+
+---
+
+## Content Refresh SERP Comparison
+
+When refreshing existing content, compare current SERP against the article:
+
+```
+CONTENT REFRESH ANALYSIS
+
+Article: "{title}"
+Published: {date}
+Days since: {N}
+
+SERP changes detected:
+
+New competitors (not in original SERP):
+├── {new URL 1} -- {what they cover that you do not}
+└── {new URL 2} -- {what they cover that you do not}
+
+New PAA questions:
+├── "{new question 1}" -- not in your FAQ
+└── "{new question 2}" -- not in your FAQ
+
+Content gaps opened:
+├── {topic/section competitors now cover}
+├── {outdated stat or claim in your article}
+└── {new angle that is gaining traction}
+
+Recommended updates:
+├── 1. Add section: "{new H2}"
+│      Reason: {why}
+│      Placement: after "{existing H2}"
+├── 2. Update section: "{existing H2}"
+│      Reason: {what changed}
+│      Specific: {what to update}
+├── 3. Add FAQ: "{new PAA question}"
+│      Answer: {brief answer to add}
+├── 4. Update stats: {specific claim}
+│      Old: {old stat}
+│      New: {updated stat}
+└── 5. Update schema: add {N} new FAQ entries
+
+Apply these updates? (y/n)
+```