@jairodri/huckleberry-cli 1.0.2 → 1.1.0

package/skills/seo-content/references/content-structures.md

@@ -0,0 +1,148 @@
+# Content Structure Templates
+
+Outline templates by content type. Choose based on search intent and keyword.
+
+---
+
+## Pillar Guide Structure (5,000-8,000 words)
+
+```
+1. Hook Intro (150-250 words)
+   - Answer the title question immediately
+   - Why this matters NOW
+   - Who this is for (and who it's not for)
+
+2. Quick Answer Section (200-300 words)
+   - Direct answer for Featured Snippet
+   - TL;DR for skimmers
+
+3. Core Sections (3-5 major sections)
+   - Each 800-1,500 words
+   - Each answers a major sub-question
+   - H2 headers with keyword variations
+   - PAA questions as H2s where appropriate
+
+4. Implementation / How to Apply (300-500 words)
+   - Specific actionable steps
+   - Decision framework if applicable
+
+5. FAQ Section (5-10 questions)
+   - From PAA research
+   - Schema-ready format (used for JSON-LD)
+
+6. Conclusion with CTA (150-200 words)
+   - Summarize key takeaway
+   - Clear next action
+```
+
+---
+
+## How-To Tutorial Structure (2,000-3,000 words)
+
+```
+1. What You'll Achieve (150-200 words)
+   - End result shown first
+   - Time estimate
+   - Prerequisites
+
+2. Why This Method (200-300 words)
+   - Context and alternatives
+   - Why this approach works
+
+3. Step-by-Step Instructions (1,200-2,000 words)
+   - Numbered steps
+   - One action per step
+   - Troubleshooting inline
+
+4. Variations / Advanced Tips (300-400 words)
+
+5. Common Mistakes (200-300 words)
+
+6. FAQ (3-5 questions from PAA)
+
+7. Next Steps with CTA (100-150 words)
+```
+
+---
+
+## Comparison Structure (2,500-4,000 words)
+
+```
+1. Quick Verdict (200-300 words)
+   - Bottom line recommendation
+   - "Choose X if... Choose Y if..."
+
+2. Comparison Table
+   - 8-12 key differentiators
+   - Pricing, best for, key features
+
+3. Deep Dive: Option A (800-1,000 words)
+   - What it is
+   - Key features
+   - Pros/cons
+   - Best for
+   - Real example
+
+4. Deep Dive: Option B (800-1,000 words)
+   - Same structure
+
+5. Head-to-Head Comparison (300-500 words)
+   - Specific scenarios
+   - When to pick each
+
+6. FAQ (3-5 questions from PAA)
+
+7. Final Recommendation with CTA
+```
+
+---
+
+## Listicle Structure (2,000-3,000 words)
+
+```
+1. Intro with Context (150-200 words)
+   - Why this list matters
+   - How items were selected
+
+2. Quick Summary Table/List
+   - All items at a glance
+   - For skimmers
+
+3. Individual Items (150-300 words each)
+   - What it is
+   - Why it's included
+   - Best for / Use case
+   - Limitations (honesty builds trust)
+
+4. How to Choose (200-300 words)
+   - Decision framework
+
+5. FAQ (3-5 questions from PAA)
+
+6. Conclusion with CTA
+```
+
+---
+
+## Writing Rules (All Types)
+
+### The First Paragraph Rule
+Answer the search query in the first 2-3 sentences. Do not make them scroll.
+
+### The "So What?" Chain
+For every point, ask "so what?" until you hit something the reader cares about.
+Write from the bottom of the chain, not the top.
+
+### Specificity Over Generality
+- Weak: "This tool saves time."
+- Strong: "This tool cut our email outreach from 4 hours to 15 minutes per day."
+
+### Show Your Work
+- "After testing 23 AI writing tools over 6 months, three stood out..."
+- "We analyzed 147 high-ranking articles in this space. The pattern was clear..."
+
+### Positioning-Informed Angle
+If positioning.md is loaded, use it to shape perspective:
+- "The Anti-Agency" angle: write from someone who's seen the model fail
+- "Practitioner, Not Theorist" angle: lead with implementation stories
+- "Data-First" angle: lead every section with numbers and evidence

package/skills/seo-content/references/eeat-examples.md

@@ -0,0 +1,235 @@
+# E-E-A-T Content Examples
+
+Best-in-class examples of human-written content that demonstrates Experience,
+Expertise, Authoritativeness, and Trust. Study these patterns.
+
+---
+
+## What Makes Content "Human"
+
+1. **A specific person with a specific viewpoint** -- not a committee
+2. **Real experience showing through** -- stories, mistakes, specific numbers
+3. **Opinions defended with reasoning** -- not hedged, not "some say X, others say Y"
+4. **Unique insight or data** -- something you can't find by aggregating other sources
+5. **Voice that could only be this person** -- recognizable even without a byline
+
+---
+
+## Example 1: Paul Graham
+
+**Source:** paulgraham.com essays
+
+**Why it works:** Unmistakable point of view backed by decades of startup experience.
+
+**What to adapt:**
+- Direct statements ("all you need to do is")
+- Acknowledging the real world ("in practice")
+- Contrarian reframing ("already too conservative")
+- Building an argument step by step
+
+---
+
+## Example 2: Wait But Why (Tim Urban)
+
+**Source:** waitbutwhy.com
+
+**Why it works:** Deep research made accessible through personality.
+
+**What to adapt:**
+- Specific sourcing ("I have a friend who's a physicist")
+- Extending analogies to reveal insight
+- Admitting "we have no idea" when true
+- Making complex ideas visceral
+
+---
+
+## Example 3: Stratechery (Ben Thompson)
+
+**Source:** stratechery.com
+
+**Why it works:** Daily analysis with a consistent analytical framework (Aggregation Theory).
+
+**What to adapt:**
+- Original frameworks with clear definitions
+- Building from principles to applications
+- Historical context that illuminates current events
+- Confidence in analysis (not hedged to death)
+
+---
+
+## Example 4: James Clear
+
+**Source:** jamesclear.com articles
+
+**Why it works:** Research backing AND personal application.
+
+**What to adapt:**
+- Specific research citations with details (248 people, 66 days)
+- Debunking common misconceptions with evidence
+- Storytelling structure (setup, surprise, reframe)
+- Making research findings immediately relevant
+
+---
+
+## Example 5: Backlinko (Brian Dean)
+
+**Source:** backlinko.com
+
+**Why it works:** Every tactic backed by data from his own experiments.
+
+**What to adapt:**
+- Specific results with numbers (110%, 14 days)
+- Personal narrative arc (struggled, discovered, succeeded)
+- "I'll show you exactly how" -- and then actually does
+- Setting up the transformation story
+
+---
+
+## Example 6: Lenny's Newsletter (Lenny Rachitsky)
+
+**Source:** lennysnewsletter.com
+
+**Why it works:** Primary research from interviewing practitioners.
+
+**What to adapt:**
+- Primary research methodology stated explicitly (50 leaders, specific companies)
+- Honest results even when they contradict expectations
+- Named sources with real quotes
+- Going deeper when initial answer is unsatisfying
+
+---
+
+## Example 7: Derek Sivers
+
+**Source:** sive.rs
+
+**Why it works:** Short, punchy essays with unconventional positions defended by experience.
+
+**What to adapt:**
+- Strong position stated immediately
+- Simple framework that's memorable
+- No hedging
+- Personal application implied throughout
+
+---
+
+## Example 8: Matt Levine (Finance)
+
+**Source:** Bloomberg Money Stuff newsletter
+
+**Why it works:** Complex financial concepts with humor and clarity.
+
+**What to adapt:**
+- Complex topics explained through everyday analogies
+- Willingness to state conclusions clearly
+- Dry humor that doesn't undermine substance
+- Building arguments by showing what's missing
+
+---
+
+## Example 9: J. Kenji Lopez-Alt (Food Science)
+
+**Source:** Serious Eats, The Food Lab
+
+**Why it works:** Scientific methodology applied to cooking. Tests dozens of variations.
+
+**What to adapt:**
+- Specific numbers from actual tests (50 steaks, 30 seconds, 30% faster)
+- Challenging conventional wisdom with evidence
+- Methodology transparency
+- Practical conclusions from scientific approach
+
+---
+
+## Example 10: Julia Evans (Technical/Programming)
+
+**Source:** jvns.ca, Wizard Zines
+
+**Why it works:** Complex systems topics made approachable without dumbing down.
+
+**What to adapt:**
+- Starting from genuine curiosity
+- Admitting uncertainty
+- Specific scope ("spent a week")
+- Inviting engagement
+
+---
+
+## Example 11: Dr. Peter Attia (Medicine)
+
+**Source:** The Drive podcast, peterattiamd.com
+
+**Why it works:** Practitioner depth. Actually reads the papers, explains the statistics.
+
+**What to adapt:**
+- Actually reading the primary sources
+- Distinguishing relative vs absolute risk
+- Teaching methodology, not just conclusions
+- Nuanced positions
+
+---
+
+## Example 12: Morgan Housel (Behavioral Finance)
+
+**Source:** "The Psychology of Money"
+
+**Why it works:** Money and decision-making through psychology and history.
+
+**What to adapt:**
+- Specific contrasting stories
+- Simple conclusions from complex data
+- Redefining success
+- No jargon despite financial topic
+
+---
+
+## Example 13: Dan Luu (Engineering)
+
+**Source:** danluu.com
+
+**Why it works:** Deep technical analyses backed by actual measurement.
+
+**What to adapt:**
+- Measurement over assumption
+- Historical comparison that reveals regression
+- Specific numbers that can be verified
+- Clear conclusion that challenges consensus
+
+---
+
+## The Pattern Across All Examples
+
+1. **First-Person Experience** -- "I found" not "studies show"
+2. **Specific Numbers** -- "248 people" not "many"
+3. **Named Sources** -- real people, real companies, real quotes
+4. **Contrarian Angles** -- challenging convention with evidence
+5. **Admitted Limitations** -- "this won't work for everyone"
+6. **Clear Voice** -- identifiable without a byline
+7. **Original Insight** -- can't be found by aggregating other sources
+
+---
+
+## How to Apply
+
+When writing SEO content, ask:
+
+1. What's my specific experience with this topic?
+2. What numbers can I cite from actual work?
+3. What's my actual opinion here?
+4. What would I tell a smart friend who asked about this?
+5. What can only I say about this?
+
+If you can't answer these, you're writing AI-style content even if AI didn't write it.
+
+---
+
+## Quick Reference by Vertical
+
+| Vertical | Examples | Key Patterns |
+|----------|----------|--------------|
+| Marketing/Business | Paul Graham, Derek Sivers, Backlinko, Lenny | Conviction, methodology, primary research |
+| Finance | Matt Levine, Morgan Housel | Complex to accessible, stories over jargon |
+| Tech/Engineering | Julia Evans, Dan Luu | Measurement, curiosity, admitting failures |
+| Healthcare | Dr. Peter Attia | Primary sources, nuance, human stakes |
+| Food/Consumer | J. Kenji Lopez-Alt | Scientific method, myth-busting with data |
+| Deep Explainers | Wait But Why, Stratechery | Research depth, original frameworks |

package/skills/seo-content/references/on-page-seo.md

@@ -0,0 +1,261 @@
+# On-Page SEO Reference
+
+Technical on-page optimization guidelines for content that ranks. Apply these to every piece of SEO content before publishing.
+
+---
+
+## Title Tags
+
+The single most important on-page ranking factor. Get this right first.
+
+### Format
+```
+Primary Keyword — Modifier | Brand Name
+```
+
+### Rules
+- **Length:** 50-60 characters (Google truncates at ~60)
+- **Keyword placement:** Primary keyword within the first 3-5 words
+- **Uniqueness:** Every page must have a distinct title tag
+- **No keyword stuffing:** Use the keyword once, naturally
+- **Power modifiers** that boost CTR: "Best," "Guide," "2026," "How to," "Free," "Review"
+- **Separator:** Use em dash (—), pipe (|), or colon (:) between segments
+
+### Examples
+| Good | Why |
+|---|---|
+| `How to Launch a SaaS Product — Complete 2026 Guide` | Keyword first, modifier, current year |
+| `Best Email Marketing Tools for Startups | YourBrand` | Keyword early, audience qualifier, brand |
+| `Product Hunt Launch Strategy: Step-by-Step Playbook` | Keyword first, format signal |
+
+| Bad | Why |
+|---|---|
+| `YourBrand — The Best Platform for Everything` | Brand first wastes prime keyword space |
+| `How to Launch a Product, SaaS Launch, Launch Guide` | Keyword stuffing |
+| `Guide` | Too vague, no keyword, no brand |
+
+---
+
+## Meta Descriptions
+
+Not a ranking factor directly, but controls click-through rate from search results.
+
+### Format
+```
+{What the page delivers} + {proof/qualifier} + {CTA}
+```
+
+### Rules
+- **Length:** 150-160 characters (Google truncates at ~160)
+- **Include primary keyword:** Google bolds matching terms in SERPs
+- **Include a CTA:** "Learn how," "Get the checklist," "See examples"
+- **Unique per page:** Never duplicate across pages
+- **Match search intent:** If query is informational, promise information. If transactional, promise a solution.
+- **Use active voice:** "Learn how to..." not "This article discusses..."
+- **Include numbers when possible:** "7 steps," "in 30 days," "47% increase"
+
+### Template
+```
+Learn {what they'll learn} with {proof element}. {Specific benefit}. {CTA with action verb}.
+```
+
+### Example
+```
+Learn how to plan a SaaS launch with our 5-phase framework used by 200+ founders.
+Get the checklist, timeline, and channel strategy. Start planning today.
+```
+
+---
+
+## Heading Hierarchy (H1-H6)
+
+Headings signal content structure to both users and search engines.
+
+### Rules
+
+**H1 — Page Title (exactly one per page)**
+- Include primary keyword naturally
+- Should closely match or expand on the title tag
+- Never duplicate the title tag word-for-word (add context)
+
+**H2 — Major Sections (3-8 per article)**
+- Each H2 should target a secondary keyword or answer a PAA question
+- Use question format when matching PAA: "How do I plan a product launch?"
+- Think of H2s as standalone mini-topics — each should make sense in a table of contents
+
+**H3 — Subsections within H2s (2-5 per H2)**
+- Support the parent H2 topic
+- Use for step breakdowns, subcategories, or related points
+- Can include long-tail keyword variations
+
+**H4-H6 — Deep nesting (use sparingly)**
+- Only when content genuinely requires multi-level hierarchy
+- Most SEO content should not go deeper than H3
+
+### Keyword Distribution Across Headings
+| Level | Keyword Strategy |
+|---|---|
+| H1 | Primary keyword, exact or close match |
+| H2 | Secondary keywords, PAA questions, topic variations |
+| H3 | Long-tail variations, related terms, specific subtopics |
+| H4+ | No keyword targeting needed — use for readability only |
+
+### Anti-Patterns
+- Multiple H1 tags on a single page
+- Skipping levels (H1 → H3 without H2)
+- Using headings for visual styling instead of structure
+- Keyword-stuffing every heading with the same term
+- Generic headings: "Introduction," "Conclusion," "Overview"
+
+---
+
+## URL Structure
+
+Clean URLs improve crawlability, shareability, and click-through rates.
+
+### Rules
+- **Keep it short:** 3-5 words in the slug, max 60 characters total path
+- **Include primary keyword:** `/launch-strategy-saas/` not `/post-12847/`
+- **Use hyphens:** `/launch-strategy/` not `/launch_strategy/` or `/launchstrategy/`
+- **Lowercase only:** `/seo-guide/` not `/SEO-Guide/`
+- **No stop words:** `/saas-launch-strategy/` not `/how-to-create-a-saas-launch-strategy/`
+- **No dates in slugs** (unless time-sensitive content like news)
+- **No parameters in indexed pages:** `/pricing/` not `/page?id=pricing`
+- **Flat structure preferred:** `/blog/launch-strategy/` not `/blog/2026/03/13/marketing/launch-strategy/`
+
+### URL Hierarchy for Content Hubs
+```
+/blog/                          ← Blog index
+/blog/launch-strategy/          ← Pillar page
+/blog/product-hunt-launch/      ← Supporting article
+/blog/beta-launch-checklist/    ← Supporting article
+```
+
+---
+
+## Internal Linking
+
+Internal links distribute page authority, help crawlers discover content, and keep users engaged.
+
+### Rules
+- **Minimum 3-5 internal links per article** (to other relevant pages)
+- **Link from high-authority pages** to pages you want to rank
+- **Use descriptive anchor text:** "product launch checklist" not "click here" or "read more"
+- **Link contextually:** Place links within the flow of content, not in disconnected lists
+- **Link deep:** Point to specific articles, not just your homepage or blog index
+- **Reciprocal linking:** If Page A links to Page B, Page B should link back (when relevant)
+
+### Hub & Spoke Model
+```
+         ┌─── Supporting Article A
+         │
+Pillar ──┼─── Supporting Article B
+Page     │
+         ├─── Supporting Article C
+         │
+         └─── Supporting Article D
+
+Each spoke links back to the pillar.
+The pillar links out to each spoke.
+Spokes link to each other where relevant.
+```
+
+### Anchor Text Rules
+| Type | Example | When to Use |
+|---|---|---|
+| Exact match | "launch checklist" | Sparingly — 1-2 per article max |
+| Partial match | "our complete launch checklist" | Primary approach — natural and keyword-rich |
+| Branded | "see the mktg launch guide" | When referencing your own product/tool |
+| Generic | "click here," "read more" | Never for SEO — avoid entirely |
+| Natural phrase | "we covered this in our guide to launching" | Best for readability and SEO balance |
+
+---
+
+## Image Optimization
+
+Images impact page speed, accessibility, and can rank in Google Image Search.
+
+### Alt Text
+- **Describe the image content** in 5-15 words
+- **Include keyword** when the image genuinely relates to it
+- **Don't keyword-stuff:** "screenshot of launch checklist template" not "launch checklist launch plan launch strategy"
+- **Empty alt for decorative images:** `alt=""` for dividers, backgrounds, icons
+- **Be specific:** "bar chart showing 47% increase in signups after launch" not "chart"
+
+### File Naming
+- Descriptive, hyphenated: `saas-launch-timeline.png` not `IMG_3847.png`
+- Include keyword when natural: `product-hunt-listing-example.webp`
+- No spaces, no underscores, no uppercase
+
+### Compression & Format
+| Format | Use For | Target Size |
+|---|---|---|
+| WebP | Photos and complex images (primary format) | Under 100KB |
+| AVIF | Next-gen alternative to WebP (growing support) | Under 80KB |
+| PNG | Screenshots, images needing transparency | Under 200KB |
+| SVG | Icons, logos, simple illustrations | Under 20KB |
+| JPEG | Legacy fallback for photos | Under 150KB |
+
+### Responsive Images
+- Serve multiple sizes with `srcset` for different screen widths
+- Use `loading="lazy"` for images below the fold
+- Set explicit `width` and `height` attributes to prevent layout shift
+
+---
+
+## Schema Markup (JSON-LD)
+
+Structured data helps Google understand content type and can trigger rich results.
+
+### When to Use Each Type
+
+| Schema Type | Content Type | Rich Result |
+|---|---|---|
+| `Article` | Blog posts, guides, news | Headline + date in search |
+| `FAQPage` | Pages with FAQ sections | Expandable Q&A in SERPs |
+| `HowTo` | Step-by-step tutorials | Step listing with images |
+| `Product` | Product pages, reviews | Price, availability, rating |
+| `BreadcrumbList` | All pages with navigation | Breadcrumb trail in SERPs |
+| `LocalBusiness` | Location-based businesses | Knowledge panel, map |
+| `VideoObject` | Pages with embedded video | Video thumbnail in search |
+
+### Implementation Rules
+- Use JSON-LD format (Google's preferred method)
+- Place in `<head>` or at end of `<body>`
+- Validate with Google's Rich Results Test before publishing
+- One `Article` schema per page minimum
+- Add `FAQPage` whenever you have 3+ questions answered on the page
+- Keep schema data consistent with visible page content (no hidden content)
+
+### Reference
+See `schema-templates.md` in this directory for copy-paste JSON-LD templates.
+
+---
+
+## Core Web Vitals for Content
+
+Page experience signals affect rankings. Content creators can influence these.
+
+### LCP (Largest Contentful Paint) — Target: Under 2.5s
+- **Hero images:** Preload with `<link rel="preload">`, serve in WebP, compress aggressively
+- **Web fonts:** Use `font-display: swap`, preload critical fonts, limit to 2 families
+- **Above-the-fold content:** Minimize render-blocking CSS and JS
+- **Server response:** Use CDN, enable compression (gzip/brotli)
+
+### CLS (Cumulative Layout Shift) — Target: Under 0.1
+- **Always set image dimensions:** `width` and `height` attributes on every `<img>`
+- **Reserve space for ads/embeds:** Use fixed-height containers
+- **No injected content above the fold** after page load (banners, consent modals)
+- **Web fonts:** Use `font-display: optional` or size-matched fallbacks
+
+### INP (Interaction to Next Paint) — Target: Under 200ms
+- **Minimize JavaScript** on content pages — most blog posts don't need heavy JS
+- **Defer non-critical scripts:** analytics, chat widgets, social embeds
+- **Lazy load below-fold elements:** images, videos, embedded content
+
+### Content-Specific Performance Tips
+- Inline critical CSS for above-the-fold content
+- Use system fonts or variable fonts to reduce font file weight
+- Compress all images before upload — don't rely on CMS auto-compression
+- Limit embedded third-party scripts (each one adds latency and CLS risk)
+- Test with Lighthouse on a throttled connection, not your fast office WiFi