@jairodri/huckleberry-cli 1.0.2 → 1.1.0

package/skills/hook-generator/references/hook-performance-analysis.json

@@ -0,0 +1,153 @@
+{
+  "hookCategories": [
+    {
+      "pattern": "Direct Value / Resource Sharing",
+      "description": "Immediately offers a tangible asset like a prompt, guide, or formula, establishing authority and providing instant utility.",
+      "effectiveness": 95,
+      "examples": [
+        "the prompt I've been using is:",
+        "the formula for pricing AI projects (save it):",
+        "manus for niches, claude for hooks = $15k/m passive info income",
+        "Founders: 2026 Landing Page Checklist:"
+      ],
+      "template": "Here's the [Resource Type] I use to [Achieve Specific Outcome]."
+    },
+    {
+      "pattern": "Benefit-Driven / Problem-Solution",
+      "description": "Leads with a clear benefit or a solution to a known problem, appealing directly to the audience's goals and pain points.",
+      "effectiveness": 90,
+      "examples": [
+        "My Claude Code now runs several parallel Gemini agents for research and coding thus saving a ton of tokens.",
+        "you can scrape any authenticated page with claude code in like 2 mins…",
+        "AI does 90% of our initial GTM strategy formulation all in just these 6 prompts."
+      ],
+      "template": "[Tool/Method] lets you [Achieve Desired Outcome] while avoiding [Common Pain Point]."
+    },
+    {
+      "pattern": "Intrigue / Secret Unveiled",
+      "description": "Creates curiosity by hinting at a hidden method, story, or non-obvious opportunity, compelling users to read more to find the answer.",
+      "effectiveness": 90,
+      "examples": [
+        "there’s an insane amount of MONEY hiding where most people don’t look.",
+        "found out my friend makes $20k/month BUYING macbooks",
+        "a guy who's sold $20M+ in info products told me something that changed how i see marketing forever",
+        "There's an AI coding approach that lets you run seriously long-running AI agents (hours, days) that ship code while you sleep. I've tried it, and I'm not going back."
+      ],
+      "template": "There's a [Adjective] method for [Task] that few people know about."
+    },
+    {
+      "pattern": "Contrarian / Provocative Statement",
+      "description": "Challenges a common belief or states a strong, unexpected opinion to grab attention and spark discussion.",
+      "effectiveness": 85,
+      "examples": [
+        "Being a generalist is a superpower, but it’s also a dopamine trap.",
+        "Money is a proxy for energy.",
+        "Stop using Apollo for all your leads",
+        "buying google ads on competitor brand names is obvious"
+      ],
+      "template": "You've been told [Common Belief] is true. It's not. The reality is [Your Contrarian Take]."
+    },
+    {
+      "pattern": "Urgency / FOMO",
+      "description": "Implies the reader is missing out on a significant opportunity or advantage, creating a fear of being left behind.",
+      "effectiveness": 80,
+      "examples": [
+        "If you're not using Google's AI studio \"build\" feature to prototype MVPs, you're sleeping on a super power.",
+        "I DON’T UNDERSTAND WHY PEOPLE AREN’T USING GOOGLE GEMINI FOR SIDE HUSTLES IN 2026."
+      ],
+      "template": "If you're still not using [Tool/Technique] for [Goal] in 2026, you're falling behind."
+    },
+    {
+      "pattern": "Educational / Question",
+      "description": "Engages the reader by asking a direct question that also teaches them something new or highlights a feature.",
+      "effectiveness": 75,
+      "examples": [
+        "Did you know you can animate your nanobanana infographics using Veo2 model in Google AI Studio? https://t.co/J74J0eBROf",
+        "Did you know you can use skills in Codex?"
+      ],
+      "template": "Did you know you can use [Tool] to [Achieve Surprising Outcome]?"
+    },
+    {
+      "pattern": "Personal Anecdote / Storytelling",
+      "description": "Starts with a personal story (often dramatic or relatable) to build a human connection and draw the reader in.",
+      "effectiveness": 75,
+      "examples": [
+        "Yesterday I cut my knee open with a machete while chasing goats through the thicket in a ravine.",
+        "i had $57,000 in debt",
+        "Your prospect opens your message and sees you sitting in their favorite café, in their city, holding a mug with their logo on it."
+      ],
+      "template": "[Timeframe], I experienced [Unexpected Event] that taught me [Key Lesson about Tech/Work]."
+    },
+    {
+      "pattern": "Data Revelation / Warning",
+      "description": "Uses a surprising or shocking statistic to create concern and establish credibility.",
+      "effectiveness": 70,
+      "examples": [
+        "✍️ over 80% of the vibe coded apps have critical security vulnerabilities"
+      ],
+      "template": "A recent study shows [Shocking Percentage]% of [Group] are affected by [Unexpected Problem]."
+    },
+    {
+      "pattern": "Slice of Life / Authenticity",
+      "description": "Shares a personal, often non-work-related moment to build authenticity and create a personal brand connection.",
+      "effectiveness": 65,
+      "examples": [
+        "Out on the ridge with the goats.",
+        "The bread is ready to go into the wood fired oven. https://t.co/IWWg3LZcUF"
+      ],
+      "template": "[Current authentic, non-work activity]."
+    }
+  ],
+  "topPerformingHooks": [
+    {
+      "hook": "There's an AI coding approach that lets you run seriously long-running AI agents (hours, days) that ship code while you sleep. I've tried it, and I'm not going back.",
+      "pattern": "Intrigue / Secret Unveiled",
+      "whyItWorks": "It promises a powerful, almost magical solution to a major pain point for developers (long-running tasks) and ends with a strong personal endorsement."
+    },
+    {
+      "hook": "a guy who's sold $20M+ in info products told me something that changed how i see marketing forever",
+      "pattern": "Intrigue / Secret Unveiled",
+      "whyItWorks": "It leverages authority ($20M+) and promises a transformative insight, creating immense curiosity about the secret."
+    },
+    {
+      "hook": "AI does 90% of our initial GTM strategy formulation all in just these 6 prompts.",
+      "pattern": "Benefit-Driven / Problem-Solution",
+      "whyItWorks": "This is a concrete and highly impressive claim of efficiency. It provides a specific number (90%, 6 prompts) which makes it more believable and impactful."
+    },
+    {
+      "hook": "Being a generalist is a superpower, but it’s also a dopamine trap.",
+      "pattern": "Contrarian / Provocative Statement",
+      "whyItWorks": "It resonates with a large segment of the tech audience, validates their identity ('superpower'), and introduces a thought-provoking downside ('dopamine trap')."
+    }
+  ],
+  "hookFormulas": [
+    {
+      "formula": "[Tool A] for [Niche Task] + [Tool B] for [Hook Type] = [Impressive Financial/Time-saving Result]",
+      "example": "manus for niches, claude for hooks = $15k/m passive info income"
+    },
+    {
+      "formula": "Stop [Commonly Accepted Practice]. Instead, [Your Superior Method] to achieve [Better Outcome].",
+      "example": "Stop using Apollo for all your leads. Instead, scrape competitor followers and hit them with a cold email that acknowledges a pain point your competitor doesn't solve well."
+    },
+    {
+      "formula": "I had [Specific, Relatable Problem]. Here's the exact [Process/Tool] I used to fix it.",
+      "example": "i had $57,000 in debt. Here is the exact combination of AI tools and outreach scripts I used to clear it in 6 months."
+    }
+  ],
+  "forAiwithjai": {
+    "bestPatterns": [
+      "Direct Value / Resource Sharing",
+      "Benefit-Driven / Problem-Solution",
+      "Intrigue / Secret Unveiled",
+      "Contrarian / Provocative Statement"
+    ],
+    "avoidPatterns": [
+      "Slice of Life / Authenticity"
+    ],
+    "customTemplates": [
+      "I stopped using [Common Tool/Technique] because of [Specific Problem]. Now, I use [New Tool/Technique] to achieve [Specific Benefit].",
+      "Here's a prompt that automates 90% of [Complex, Annoying Task] for you.",
+      "Most people in [Your Niche] believe [Common Myth]. The truth is [Your Contrarian Insight]."
+    ]
+  }
+}

package/skills/hook-generator/references/hooks-library.md

@@ -0,0 +1,128 @@
+# Hooks Library
+
+Master collection of attention-grabbing hooks for headlines, opening lines, and content engagement.
+
+## What is a Hook?
+
+A hook is **not** your headline or first line. A hook is something you **add** to your headline or first line to make it interesting. Think of it as the "whipped cream and nuts" you add to a vanilla topic to give it spice and grab attention.
+
+**Process**: Start with your main topic → Add hook elements → Create compelling headline
+
+## Core Hook Types
+
+### 1. **Outcome Hook**
+State the specific result your content promises to deliver.
+
+**Formula**: [Action] + [Specific Outcome]
+**Examples**:
+- "Gain 28 pounds of muscle" (quantified outcome)
+- "Build an army of affiliates" (visual imagery when numbers aren't possible)
+
+**Best Practice**: Always use numbers when possible. If you can't quantify, use specific visual imagery.
+
+### 2. **Time Frame Hook** 
+Add urgency by specifying when the outcome will happen.
+
+**Formula**: [Outcome] + [Specific Time Frame]
+**Examples**:
+- "Get your first client in 24 hours"
+- "Your back pain gone in seven days"
+- "How to do the splits in less than 30 days"
+
+**Best Practice**: Be as specific as possible with timing. "24 hours" beats "quickly."
+
+### 3. **Objection Busting Hook**
+Address the main reason people think your promise won't work for them.
+
+**Formula**: [Outcome] + "even if" + [Common Objection]
+**Examples**:
+- "Get clients from Twitter even if you don't have any followers"
+- "How to do the splits in less than 30 days even if you can't touch your toes"
+
+**Best Practice**: Research common objections by reading comments on similar content.
+
+### 4. **Mechanism Hook**
+Explain HOW you'll deliver the outcome - the system, process, or method.
+
+**Formula**: [Outcome] + "with" + [Specific System/Process]
+**Examples**:
+- "Write better headlines with my foolproof five-step system"
+- "Burn fat with the all-donut diet"
+- "Bulletproof security with our five-star aluminum alloy system"
+
+**Best Practice**: Make the mechanism sound proprietary and intriguing.
+
+### 5. **Contrarian Hook**
+Go against common advice or accepted wisdom.
+
+**Formula**: [Opposite of Common Advice] + [Desired Outcome]
+**Examples**:
+- "Why you should eat carbs to burn fat"
+- "The productivity hack that requires doing less work"
+- "How being lazy made me more successful"
+
+**Best Practice**: Research what everyone else is saying, then flip it (but only if you can back it up).
+
+### 6. **Negative Hook**
+Tell people what NOT to do instead of what TO do.
+
+**Formula**: [What to Avoid] + "if you want" + [Desired Outcome]
+**Examples**:
+- "Seven foods you must avoid if you want to build muscle"
+- "The one headline mistake that's killing your conversions"
+- "Stop doing these 5 things if you want to grow on Twitter"
+
+**Best Practice**: Creates curiosity and positions you as the expert who knows the right way.
+
+## Advanced Hook Combinations
+
+You can combine multiple hooks for maximum impact:
+
+**Example**: "How to do the splits in less than 30 days even if you can't touch your toes"
+- **Outcome**: "do the splits"
+- **Time Frame**: "in less than 30 days" 
+- **Objection Buster**: "even if you can't touch your toes"
+
+## Hook Application Framework
+
+### Step 1: Write Your Content First
+Create your main content with a placeholder headline.
+
+### Step 2: Identify Your Core Promise
+What specific outcome does your content deliver?
+
+### Step 3: Research the Landscape  
+What are others saying about this topic? What objections do people have?
+
+### Step 4: Select Your Hook Elements
+Choose 1-3 hook types that best fit your content and audience.
+
+### Step 5: Test Multiple Versions
+Write several hook combinations and pick the most compelling.
+
+## Hook Quality Tests
+
+**The Curiosity Test**: Does it make you want to know more?
+**The Specificity Test**: Is it concrete and tangible?
+**The Belief Test**: Can you deliver on the promise?
+**The Standout Test**: Is it different from what others are saying?
+
+## Common Hook Mistakes
+
+❌ **Being too vague**: "Get better results" vs "Get 28 pounds of muscle"
+❌ **Following the crowd**: Copying what everyone else is doing
+❌ **Over-promising**: Claims you can't back up with content
+❌ **Under-hooking**: Using vanilla headlines without any hook elements
+
+## Hook Ethics
+
+Hooks are about grabbing attention for genuinely helpful content. It's only manipulative if:
+- You can't deliver on your promise
+- You're misleading people
+- Your content doesn't provide real value
+
+If you have valuable content, you should use hooks to help people discover it.
+
+---
+
+*Sources: Andrew & Alex Twitter Spaces discussion on head-turning hooks, plus additional hook frameworks from copywriting masters.*

package/skills/hook-generator/references/platform-hook-frameworks.md

@@ -0,0 +1,275 @@
+# Platform-Specific Hook Frameworks & Formulas
+
+## Email/Newsletter Hook Optimization
+
+### Subject Line Psychology
+**Character Limits by Email Client:**
+- **Mobile Gmail**: 30-33 characters visible
+- **Desktop Outlook**: 48-50 characters  
+- **Apple Mail**: 35-40 characters
+- **Strategy**: Front-load impact in first 30 characters
+
+**Engagement Trigger Hierarchy:**
+1. **Numbers** (highest engagement): "96%", "$4,650", "75 days"
+2. **Authority** (high trust): "Elon reveals", "According to Harvard"
+3. **Contrarian** (pattern interrupt): "Everyone does X. This works better:"
+4. **Personal** (relationship building): "I tried X for Y days. Here's what happened:"
+
+**Subject Line Formula Library:**
+```
+Data + Authority: "How [Authority] achieved [Number] in [Timeframe]"
+Example: "How Elon cut SpaceX costs 96% in 75 days"
+
+Question + Number: "What if [Action] could [Number/Outcome]?"  
+Example: "What if questioning everything saved you $4,650 monthly?"
+
+Personal + Contrarian: "I [Opposite Action] for [Time]. [Surprising Result]:"
+Example: "I deleted first, optimized last. 96% cost reduction:"
+
+Authority + Mechanism: "[Authority]'s [System] that [Industry] ignores"
+Example: "Elon's delete-first rule that 99% of founders ignore"
+
+Objection + Outcome: "[Result] even if [Common Objection]"
+Example: "Cut costs 96% even if you think everything is essential"
+```
+
+### Section Header Hooks
+**Micro-Hook Purpose**: Create curiosity gaps that make sections unskippable
+**Length**: 8-15 words optimal for scanability
+**Psychology**: Each header should ask "How?" or "What exactly?"
+
+**Section Hook Formulas:**
+```
+Outcome + Specificity: "How I [specific action] resulted in [exact number]"
+Example: "How I eliminated $4,650 in 30 days (without touching essential operations)"
+
+Authority + Contrarian: "Why [Authority] does [Unexpected] instead of [Expected]"
+Example: "Why Elon optimizes last (not first) in his cost-cutting algorithm"
+
+Promise + Proof: "[Specific deliverable]: [evidence/timeframe]"
+Example: "$6,650 monthly savings: exact numbers from 75 days of deletion"
+
+Comparison + Revelation: "[Option A] vs [Option B]: the [shocking] difference"
+Example: "Customer request vs internal assumption: the $2,400 difference"
+
+Tool + Result: "Every [resource type] from my [specific outcome]"
+Example: "Every spreadsheet and template from my $6,650 cost cut"
+```
+
+## Social Media Platform Optimization
+
+### Twitter/X Hook Engineering
+**Algorithm Factors (2025):**
+- First 3 seconds determine engagement trajectory
+- Questions generate 23% higher reply rates
+- Numbers increase retweets by 67%
+- Contrarian takes drive quote tweets
+
+**Character Optimization:**
+- **Hook Zone**: First 50 characters (preview text)
+- **Full Hook**: 150-180 characters (leaves room for thread indicators)
+- **Thread Setup**: End with "Here's what I learned:" or "The breakdown:"
+
+**Twitter Hook Formulas:**
+```
+Data + Question: "[Number/Stat]. Why does everyone ignore this?"
+Example: "96% cost reduction. Why does everyone optimize before deleting?"
+
+Authority + Thread Setup: "[Authority] mentioned this [Number] times. The breakdown:"
+Example: "Elon mentioned his algorithm 25 times in one interview. The breakdown:"
+
+Personal + Contrarian: "Everyone does [X]. I did [Y] for [time]. [Surprising result]:"
+Example: "Everyone optimizes first. I deleted first for 75 days. 96% cost reduction:"
+
+Question + Hook: "What if [assumption] is backwards? [Thread setup]:"
+Example: "What if optimization actually locks in waste? Here's what I found:"
+
+Problem + Solution Tease: "[Common problem]. [Authority] has a [surprising] solution. Thread:"
+Example: "High costs killing your margins. Elon has a delete-first solution. Thread:"
+```
+
+### LinkedIn Hook Optimization
+**Professional Context Requirements:**
+- Industry credibility establishment
+- Career/business benefit clarity  
+- Leadership insight demonstration
+- B2B value proposition
+
+**LinkedIn Algorithm Preferences:**
+- **Engagement bait penalties**: Avoid "thoughts?" and "agree?"
+- **Value-first content**: Lead with insight, not personal story
+- **Professional authority**: Credentials and experience matter more
+- **Long-form friendly**: 1,300+ character posts perform best
+
+**LinkedIn Hook Formulas:**
+```
+Industry + Insight: "After [experience/time] in [industry], here's what most get wrong about [topic]:"
+Example: "After 10 years in manufacturing, here's what most get wrong about cost reduction:"
+
+Authority + Professional Application: "[Authority]'s approach to [topic] changed how I [professional activity]:"  
+Example: "Elon's delete-first methodology changed how I evaluate every vendor relationship:"
+
+Data + Business Impact: "[Statistic] of companies [fail/succeed] because they [action]. Here's the alternative:"
+Example: "96% of cost reduction efforts fail because they optimize before deleting. Here's the alternative:"
+
+Leadership + Lesson: "Leading [context], I learned that [contrarian insight]. The process:"
+Example: "Leading our cost reduction initiative, I learned that questioning comes before cutting. The process:"
+
+ROI + Method: "How we achieved [business metric] using [unexpected approach]:"
+Example: "How we achieved $6,650 monthly savings using Elon's 5-step deletion process:"
+```
+
+### Instagram Hook Strategy  
+**Visual-Content Integration:**
+- Hook must work with image/video content
+- Story format compatibility essential
+- Behind-the-scenes angle preference
+- Lifestyle + business lesson blend
+
+**Instagram Algorithm Factors:**
+- **Visual engagement first**: Image/video determines initial reach
+- **Caption depth**: Longer captions increase saves and shares  
+- **Story continuation**: Hooks that work across story sequence
+- **Community building**: Comments and DM generation priority
+
+**Instagram Hook Formulas:**
+```
+Visual + Story: "[Visual description] → [business lesson]. Here's the full story:"
+Example: "This spreadsheet → $6,650 monthly savings. Here's the full story:"
+
+Behind-the-Scenes + Result: "What happens when [personal situation] meets [business principle]:"
+Example: "What happens when farm life constraints meet Elon's deletion algorithm:"
+
+Transformation + Process: "[Before situation] → [After situation]. The exact process:"
+Example: "$28,000 monthly expenses → $21,350. The exact process:"
+
+Lifestyle + Lesson: "[Personal context] taught me [business insight]. Swipe for the breakdown:"
+Example: "Raising goats taught me constraint thinking. Swipe for the breakdown:"
+
+Story + Application: "This [personal story] changed how I [business application]:"
+Example: "This conversation with Elon changed how I evaluate every business expense:"
+```
+
+### TikTok Viral Hook Patterns
+**Retention Requirements:**
+- First 3 seconds determine completion rate
+- Pattern interrupts essential for For You Page
+- Generation Z language and cultural references
+- Quick value delivery (under 60 seconds total)
+
+**TikTok Algorithm Optimization:**
+- **Hook + Hold**: First 3 seconds + reason to stay  
+- **Value Density**: Information per second maximization
+- **Comment Bait**: Built-in discussion triggers
+- **Shareability**: "Send this to someone who..." compatibility
+
+**TikTok Hook Formulas:**
+```
+Pattern Interrupt + Value: "Everyone thinks [common belief]. I tested it for [time]. Results:"
+Example: "Everyone thinks you optimize first. I tested delete-first for 75 days. Results:"
+
+POV + Revelation: "POV: You discover [surprising insight] and it changes everything:"
+Example: "POV: You discover Elon's cost algorithm and it saves you $6K monthly:"
+
+Quick Explanation + Impact: "30-second explanation of [complex topic] that could [outcome]:"
+Example: "30-second explanation of Elon's deletion method that could cut your costs 96%:"
+
+Story + Lesson: "This [short story] teaches [valuable lesson]. Here's why:"
+Example: "This $200 bracket elimination teaches million-dollar thinking. Here's why:"
+
+Challenge + Solution: "If you [common situation], try this [unexpected solution]:"
+Example: "If you're drowning in expenses, try Elon's delete-first approach:"
+```
+
+## Blog/SEO Hook Optimization
+
+### Search Intent Alignment
+**Informational Intent Hooks:**
+- "How to [achieve outcome] using [method]"
+- "The complete guide to [topic] for [audience]"
+- "Why [authority] recommends [approach] over [alternative]"
+
+**Commercial Intent Hooks:**
+- "Best [tools/methods] for [outcome] in [year]"
+- "[Number] proven strategies to [achieve goal]"
+- "[Authority]'s method vs [alternatives]: complete comparison"
+
+**Navigational Intent Hooks:**
+- "[Brand/Authority] [method/system]: everything you need to know"
+- "Official guide to [specific approach/system]"
+
+### SEO + Curiosity Balance
+**Primary Keyword Integration:**
+- Natural placement in first 60 characters
+- Semantic keyword variants throughout
+- Related search terms incorporated
+
+**Featured Snippet Optimization:**
+```
+Question Format: "How does [authority] achieve [outcome]? [Answer preview]"
+List Format: "[Number] steps to [outcome] (according to [authority])"
+Definition Format: "What is [method]? [Authority]'s [outcome] approach explained"
+```
+
+## Performance Tracking Framework
+
+### Engagement Metrics by Platform
+**Email/Newsletter:**
+- Open rates by subject line formula
+- Click-through rates by section header type
+- Time spent reading (heat map analysis)
+- Forward/share rates
+
+**Social Media:**
+- **Twitter**: Likes, retweets, quote tweets, replies, thread completion
+- **LinkedIn**: Reactions, comments, shares, saves, profile views
+- **Instagram**: Likes, comments, saves, shares, story completion
+- **TikTok**: Views, likes, shares, comments, completion rate
+
+### A/B Testing Protocol
+**Subject Line Testing:**
+- Test 2 formulas simultaneously 
+- 50/50 audience split
+- 24-hour measurement window
+- Statistical significance threshold: 95%
+
+**Social Hook Testing:**
+- Platform-specific variations
+- Time-of-day posting variables
+- Audience segment testing
+- Content format pairing analysis
+
+### Conversion Tracking
+**Newsletter to Action:**
+- Click-through to blog posts
+- Consultation request rates
+- Social platform growth
+- Email list growth from shares
+
+**Social to Newsletter:**
+- Profile visits from hook engagement
+- Newsletter signup conversions
+- Cross-platform traffic flow
+- Brand mention increases
+
+## Continuous Optimization System
+
+### Weekly Performance Review:
+1. **Top performing hooks** by platform and metric
+2. **Formula effectiveness** analysis and ranking updates
+3. **Research angle success** patterns identification  
+4. **Audience preference** shifts and trend analysis
+
+### Monthly Framework Updates:
+1. **New formula development** based on performance data
+2. **Platform algorithm** change adaptations
+3. **Competitor hook analysis** for differentiation opportunities
+4. **Industry trend integration** for relevance optimization
+
+### Quarterly Strategy Evolution:
+1. **Brand voice refinement** based on audience feedback
+2. **Platform priority** adjustments based on ROI analysis
+3. **Content type** expansion based on engagement success
+4. **Tool and resource** upgrades for improved efficiency
+
+This framework ensures hooks evolve with performance data while maintaining systematic generation approaches across all platforms.