@jairodri/huckleberry-cli 1.0.1 → 1.1.0

package/skills/social-content/SKILL.md

@@ -0,0 +1,359 @@
+---
+name: social-content
+description: Create, schedule, and optimize social media content across platforms.
+depends-on:
+  - hook-generator
+metadata:
+  version: 1.2.0
+---
+
+# Social Content
+
+You are an expert social media strategist. Your goal is to help create engaging content that builds audience, drives engagement, and supports business goals.
+
+## Before Creating Content
+
+**Check for brand-specific assets in businesses/{business}/brand/ first:**
+If `businesses/{business}/brand/` exists (or `businesses/{business}/brand/` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
+
+Gather this context (ask if not provided):
+
+### 1. Goals
+- What's the primary objective? (Brand awareness, leads, traffic, community)
+- What action do you want people to take?
+- Are you building personal brand, company brand, or both?
+
+### 2. Audience
+- Who are you trying to reach?
+- What platforms are they most active on?
+- What content do they engage with?
+
+### 3. Brand Voice
+- What's your tone? (Professional, casual, witty, authoritative)
+- Any topics to avoid?
+- Any specific terminology or style guidelines?
+
+### 4. Resources
+- How much time can you dedicate to social?
+- Do you have existing content to repurpose?
+- Can you create video content?
+
+---
+
+## Awareness Gate (MANDATORY)
+
+Before any content creation, determine the target audience's awareness level:
+
+1. **Can you determine awareness level from the prompt/context?**
+   - For SEO: keyword intent maps to awareness level
+     - Informational ("how to fix X") → Problem-aware
+     - Comparative ("X vs Y") → Solution-aware
+     - Branded ("your product") → Product-aware
+     - Transactional ("buy X") → Most-aware
+   - For social: content topic + audience → awareness level
+   - For email: subscriber stage → awareness level
+
+2. **If YES** → Proceed with awareness-matched strategy
+   - Load `references/awareness-level-guide.md`
+   - Select copy framework based on awareness level
+
+3. **If NO** → ASK THE USER before proceeding:
+   "What awareness level is your target audience at?"
+   - Unaware — doesn't know they have a problem
+   - Problem-aware — knows the problem, doesn't know solutions exist
+   - Solution-aware — knows solutions exist, doesn't know your product
+   - Product-aware — knows your product, not convinced it's right
+   - Most-aware — ready to buy, just needs the offer
+
+---
+
+## Platform Quick Reference
+
+| Platform | Best For | Frequency | Key Format |
+|----------|----------|-----------|------------|
+| LinkedIn | B2B, thought leadership | 3-5x/week | Carousels, stories |
+| Twitter/X | Tech, real-time, community | 3-10x/day | Threads, hot takes |
+| Instagram | Visual brands, lifestyle | 1-2 posts + Stories daily | Reels, carousels |
+| TikTok | Brand awareness, younger audiences | 1-4x/day | Short-form video |
+| Facebook | Communities, local businesses | 1-2x/day | Groups, native video |
+
+**For detailed platform strategies**: See [references/platforms.md](references/platforms.md)
+
+---
+
+## Content Pillars Framework
+
+Build your content around 3-5 pillars that align with your expertise and audience interests.
+
+### Example for a SaaS Founder
+
+| Pillar | % of Content | Topics |
+|--------|--------------|--------|
+| Industry insights | 30% | Trends, data, predictions |
+| Behind-the-scenes | 25% | Building the company, lessons learned |
+| Educational | 25% | How-tos, frameworks, tips |
+| Personal | 15% | Stories, values, hot takes |
+| Promotional | 5% | Product updates, offers |
+
+### Pillar Development Questions
+
+For each pillar, ask:
+1. What unique perspective do you have?
+2. What questions does your audience ask?
+3. What content has performed well before?
+4. What can you create consistently?
+5. What aligns with business goals?
+
+---
+
+## Hook Formulas
+
+The first line determines whether anyone reads the rest.
+
+**Hook-generator integration:** Before using the manual formulas below, spawn a hook-generator subagent for platform-specific hooks:
+```
+Load the hook-generator skill and execute the full Phase 1-6 pipeline with this context.
+Context:
+- WHO: <target audience>
+- WHAT/WHY: <post's core message or insight>
+- Knife: <pain point this post addresses>
+- Platform: <twitter / instagram / linkedin / tiktok — map from target platform>
+- Brand: <brand name>
+- Target Score: 85
+Return ONLY this JSON array: [{"hook":"...","score":<0-100>,"pattern":"...","formula":"..."}]
+```
+Use scored hooks as first-line candidates. Discard any that don't match the post's tone. If subagent fails, fall back to the manual formulas below.
+
+### Curiosity Hooks
+- "I was wrong about [common belief]."
+- "The real reason [outcome] happens isn't what you think."
+- "[Impressive result] — and it only took [surprisingly short time]."
+
+### Story Hooks
+- "Last week, [unexpected thing] happened."
+- "I almost [big mistake/failure]."
+- "3 years ago, I [past state]. Today, [current state]."
+
+### Value Hooks
+- "How to [desirable outcome] (without [common pain]):"
+- "[Number] [things] that [outcome]:"
+- "Stop [common mistake]. Do this instead:"
+
+### Contrarian Hooks
+- "Unpopular opinion: [bold statement]"
+- "[Common advice] is wrong. Here's why:"
+- "I stopped [common practice] and [positive result]."
+
+**For post templates and more hooks**: See [references/post-templates.md](references/post-templates.md)
+
+---
+
+## Content Repurposing System
+
+Turn one piece of content into many:
+
+### Blog Post → Social Content
+
+| Platform | Format |
+|----------|--------|
+| LinkedIn | Key insight + link in comments |
+| LinkedIn | Carousel of main points |
+| Twitter/X | Thread of key takeaways |
+| Instagram | Carousel with visuals |
+| Instagram | Reel summarizing the post |
+
+### Repurposing Workflow
+
+1. **Create pillar content** (blog, video, podcast)
+2. **Extract key insights** (3-5 per piece)
+3. **Adapt to each platform** (format and tone)
+4. **Schedule across the week** (spread distribution)
+5. **Update and reshare** (evergreen content can repeat)
+
+---
+
+## Content Calendar Structure
+
+### Weekly Planning Template
+
+| Day | LinkedIn | Twitter/X | Instagram |
+|-----|----------|-----------|-----------|
+| Mon | Industry insight | Thread | Carousel |
+| Tue | Behind-scenes | Engagement | Story |
+| Wed | Educational | Tips tweet | Reel |
+| Thu | Story post | Thread | Educational |
+| Fri | Hot take | Engagement | Story |
+
+### Batching Strategy (2-3 hours weekly)
+
+1. Review content pillar topics
+2. Write 5 LinkedIn posts
+3. Write 3 Twitter threads + daily tweets
+4. Create Instagram carousel + Reel ideas
+5. Schedule everything
+6. Leave room for real-time engagement
+
+---
+
+## Engagement Strategy
+
+### Daily Engagement Routine (30 min)
+
+1. Respond to all comments on your posts (5 min)
+2. Comment on 5-10 posts from target accounts (15 min)
+3. Share/repost with added insight (5 min)
+4. Send 2-3 DMs to new connections (5 min)
+
+### Quality Comments
+
+- Add new insight, not just "Great post!"
+- Share a related experience
+- Ask a thoughtful follow-up question
+- Respectfully disagree with nuance
+
+### Building Relationships
+
+- Identify 20-50 accounts in your space
+- Consistently engage with their content
+- Share their content with credit
+- Eventually collaborate (podcasts, co-created content)
+
+---
+
+## Analytics & Optimization
+
+### Metrics That Matter
+
+**Awareness:** Impressions, Reach, Follower growth rate
+
+**Engagement:** Engagement rate, Comments (higher value than likes), Shares/reposts, Saves
+
+**Conversion:** Link clicks, Profile visits, DMs received, Leads attributed
+
+### Weekly Review
+
+- Top 3 performing posts (why did they work?)
+- Bottom 3 posts (what can you learn?)
+- Follower growth trend
+- Engagement rate trend
+- Best posting times (from data)
+
+### Optimization Actions
+
+**If engagement is low:**
+- Test new hooks
+- Post at different times
+- Try different formats
+- Increase engagement with others
+
+**If reach is declining:**
+- Avoid external links in post body
+- Increase posting frequency
+- Engage more in comments
+- Test video/visual content
+
+---
+
+## Content Ideas by Situation
+
+### When You're Starting Out
+- Document your journey
+- Share what you're learning
+- Curate and comment on industry content
+- Engage heavily with established accounts
+
+### When You're Stuck
+- Repurpose old high-performing content
+- Ask your audience what they want
+- Comment on industry news
+- Share a failure or lesson learned
+
+---
+
+## Scheduling Best Practices
+
+### When to Schedule vs. Post Live
+
+**Schedule:** Core content posts, Threads, Carousels, Evergreen content
+
+**Post live:** Real-time commentary, Responses to news/trends, Engagement with others
+
+### Queue Management
+
+- Maintain 1-2 weeks of scheduled content
+- Review queue weekly for relevance
+- Leave gaps for spontaneous posts
+- Adjust timing based on performance data
+
+---
+
+## Reverse Engineering Viral Content
+
+Instead of guessing, analyze what's working for top creators in your niche:
+
+1. **Find creators** — 10-20 accounts with high engagement
+2. **Collect data** — 500+ posts for analysis
+3. **Analyze patterns** — Hooks, formats, CTAs that work
+4. **Codify playbook** — Document repeatable patterns
+5. **Layer your voice** — Apply patterns with authenticity
+6. **Convert** — Bridge attention to business results
+
+**For the complete framework**: See [references/reverse-engineering.md](references/reverse-engineering.md)
+
+---
+
+## Task-Specific Questions
+
+1. What platform(s) are you focusing on?
+2. What's your current posting frequency?
+3. Do you have existing content to repurpose?
+4. What content has performed well in the past?
+5. How much time can you dedicate weekly?
+6. Are you building personal brand, company brand, or both?
+
+---
+
+## Agent-Reach for Social Research (Free)
+
+**Agent-Reach** (skill: `agent-reach`) provides zero-config access to social platforms for content ideation and trend monitoring:
+
+```bash
+agent-reach doctor --json  # Check available platforms
+
+# X/Twitter trends & sentiment
+twitter search "your topic" -n 20
+bird search "your topic"
+
+# Reddit discussions & pain points
+opencli reddit search "topic" -f yaml
+
+# Bilibili (Chinese tech/Creator content)
+bili search "topic" --type video -n 10
+
+# V2EX (Chinese developer community)
+curl https://www.v2ex.com/api/topics/hot.json
+
+# XiaoYuZhou podcasts (Chinese)
+~/.agent-reach/tools/xiaoyuzhou/transcribe.sh "URL"
+
+# Exa semantic search (free, no API key)
+mcporter call 'exa.web_search_exa(query: "topic", numResults: 5)'
+
+# GitHub for dev content
+gh search repos "topic" --sort stars --limit 10
+```
+
+**Use Agent-Reach before writing** to gather:
+- Trending discussions on your topic
+- Audience pain points (Reddit, X)
+- Competitor content angles
+- Platform-specific formats that work
+
+---
+
+## Related Skills
+
+- **copywriting**: For longer-form content that feeds social
+- **launch-strategy**: For coordinating social with launches
+- **email-sequence**: For nurturing social audience via email
+- **marketing-psychology**: For understanding what drives engagement

package/skills/social-content/evals/evals.json

@@ -0,0 +1,92 @@
+{
+  "skill_name": "social-content",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Help me create a LinkedIn content strategy. I'm a SaaS founder building in public and want to grow my personal brand to drive awareness for my product. I currently have 500 followers and post maybe once a week.",
+      "expected_output": "Should check for product-marketing-context.md first. Should establish content pillars (3-5) appropriate for a SaaS founder building in public: industry insights, behind-the-scenes, educational content, personal stories, promotional (minimal). Should apply the platform quick reference for LinkedIn (3-5x/week recommended, carousels and stories perform well). Should provide hook formulas for LinkedIn posts. Should create a weekly content calendar. Should include engagement strategy (daily 30-min routine). Should address going from 1x/week to 3-5x/week with a batching strategy.",
+      "assertions": [
+        "Checks for product-marketing-context.md",
+        "Establishes 3-5 content pillars",
+        "Applies LinkedIn platform guidance",
+        "Provides hook formulas",
+        "Creates weekly content calendar",
+        "Includes engagement strategy",
+        "Addresses batching strategy for consistency",
+        "Recommends increasing from 1x to 3-5x per week"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Write me a Twitter/X thread about the lessons I learned bootstrapping my SaaS to $10k MRR. Include hooks and a CTA at the end.",
+      "expected_output": "Should apply the hook formulas for a story hook (e.g., '6 months ago, I had $0 MRR. Today, I hit $10k.'). Should structure the thread following platform best practices: strong hook in tweet 1, each tweet should stand alone but flow together, use specific numbers and stories, end with a CTA. Should reference the content pillar this fits into (behind-the-scenes / founder journey). Should provide the actual thread content with 8-12 tweets. Should include engagement prompts.",
+      "assertions": [
+        "Applies hook formulas from the skill",
+        "Uses a story hook for the first tweet",
+        "Structures thread with standalone but flowing tweets",
+        "Uses specific numbers and stories",
+        "Ends with clear CTA",
+        "Provides 8-12 tweet thread content",
+        "Includes engagement prompts"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "i have a blog post that did really well. how do i turn it into social media content for multiple platforms?",
+      "expected_output": "Should trigger on casual phrasing. Should apply the content repurposing system. Should use the Blog Post → Social Content mapping: LinkedIn (key insight post + carousel of main points), Twitter/X (thread of key takeaways), Instagram (carousel with visuals + Reel summarizing the post). Should follow the repurposing workflow: create pillar content → extract key insights (3-5) → adapt to each platform → schedule across the week. Should provide specific format recommendations per platform.",
+      "assertions": [
+        "Triggers on casual phrasing",
+        "Applies content repurposing system",
+        "Uses Blog Post → Social Content mapping",
+        "Provides format for LinkedIn, Twitter/X, and Instagram",
+        "Follows the repurposing workflow",
+        "Extracts 3-5 key insights to repurpose",
+        "Provides platform-specific format recommendations"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "My LinkedIn posts get like 200 impressions and almost no engagement. What am I doing wrong?",
+      "expected_output": "Should apply the analytics and optimization section, specifically the 'if engagement is low' guidance. Should diagnose potential issues: weak hooks (first line not compelling), posting at wrong times, not engaging with others' content, poor formatting (no line breaks, walls of text), content not resonating with audience. Should recommend specific fixes: test new hook formulas, post at different times, increase engagement with others (the daily engagement routine), try different formats (carousels, stories). Should provide before/after hook examples.",
+      "assertions": [
+        "Applies analytics and optimization guidance",
+        "Diagnoses potential engagement issues",
+        "Addresses hook quality",
+        "Addresses posting timing",
+        "Recommends daily engagement routine",
+        "Suggests trying different content formats",
+        "Provides specific before/after hook examples"
+      ],
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "Help me reverse-engineer what's working for top creators in the DevTools space on Twitter. I want to understand their content patterns.",
+      "expected_output": "Should apply the reverse engineering viral content framework. Should walk through the process: identify 10-20 top accounts in DevTools, collect high-performing posts, analyze patterns (hooks, formats, CTAs, topics, posting times), codify a playbook of repeatable patterns, then layer the user's authentic voice. Should provide specific guidance on what to look for in the analysis. Should recommend tools or methods for collecting the data.",
+      "assertions": [
+        "Applies reverse engineering viral content framework",
+        "Walks through the full process (find, collect, analyze, codify, apply)",
+        "Recommends identifying 10-20 accounts",
+        "Describes what patterns to analyze",
+        "Emphasizes layering authentic voice",
+        "Provides data collection guidance"
+      ],
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "Write me a 5-email welcome sequence for new email subscribers who came from my LinkedIn audience.",
+      "expected_output": "Should recognize this is an email sequence task, not social content. Should defer to or cross-reference the email-sequence skill, which handles welcome sequences, drip campaigns, and lifecycle emails. May note the social-to-email bridge context but should make clear that email-sequence is the right skill for writing email sequences.",
+      "assertions": [
+        "Recognizes this as email sequence work",
+        "References or defers to email-sequence skill",
+        "Does not attempt to write email sequence using social content patterns",
+        "May note social-to-email bridge context"
+      ],
+      "files": []
+    }
+  ]
+}

package/skills/social-content/references/platforms.md

@@ -0,0 +1,170 @@
+# Platform-Specific Strategy Guide
+
+Detailed strategies for each major social platform.
+
+## Contents
+- LinkedIn
+- Twitter/X
+- Instagram
+- TikTok
+- Facebook
+
+## LinkedIn
+
+**Best for:** B2B, thought leadership, professional networking, recruiting
+**Audience:** Professionals, decision-makers, job seekers
+**Posting frequency:** 3-5x per week
+**Best times:** Tuesday-Thursday, 7-8am, 12pm, 5-6pm
+
+**What works:**
+- Personal stories with business lessons
+- Contrarian takes on industry topics
+- Behind-the-scenes of building a company
+- Data and original insights
+- Carousel posts (document format)
+- Polls that spark discussion
+
+**What doesn't:**
+- Overly promotional content
+- Generic motivational quotes
+- Links in the main post (kills reach)
+- Corporate speak without personality
+
+**Format tips:**
+- First line is everything (hook before "see more")
+- Use line breaks for readability
+- 1,200-1,500 characters performs well
+- Put links in comments, not post body
+- Tag people sparingly and genuinely
+
+**Algorithm tips:**
+- First hour engagement matters most
+- Comments > reactions > clicks
+- Dwell time (people reading) signals quality
+- No external links in post body
+- Document posts (carousels) get strong reach
+- Polls drive engagement but don't build authority
+
+---
+
+## Twitter/X
+
+**Best for:** Tech, media, real-time commentary, community building
+**Audience:** Tech-savvy, news-oriented, niche communities
+**Posting frequency:** 3-10x per day (including replies)
+**Best times:** Varies by audience; test and measure
+
+**What works:**
+- Hot takes and opinions
+- Threads that teach something
+- Behind-the-scenes moments
+- Engaging with others' content
+- Memes and humor (if on-brand)
+- Real-time commentary on events
+
+**What doesn't:**
+- Pure self-promotion
+- Threads without a strong hook
+- Ignoring replies and mentions
+- Scheduling everything (no real-time presence)
+
+**Format tips:**
+- Tweets under 100 characters get more engagement
+- Threads: Hook in tweet 1, promise value, deliver
+- Quote tweets with added insight beat plain retweets
+- Use visuals to stop the scroll
+
+**Algorithm tips:**
+- Replies and quote tweets build authority
+- Threads keep people on platform (rewarded)
+- Images and video get more reach
+- Engagement in first 30 min matters
+- Twitter Blue/Premium may boost reach
+
+---
+
+## Instagram
+
+**Best for:** Visual brands, lifestyle, e-commerce, younger demographics
+**Audience:** 18-44, visual-first consumers
+**Posting frequency:** 1-2 feed posts per day, 3-10 Stories per day
+**Best times:** 11am-1pm, 7-9pm
+
+**What works:**
+- High-quality visuals
+- Behind-the-scenes Stories
+- Reels (short-form video)
+- Carousels with value
+- User-generated content
+- Interactive Stories (polls, questions)
+
+**What doesn't:**
+- Low-quality images
+- Too much text in images
+- Ignoring Stories and Reels
+- Only promotional content
+
+**Format tips:**
+- Reels get 2x reach of static posts
+- First frame of Reels must hook
+- Carousels: 10 slides with educational content
+- Use all Story features (polls, links, etc.)
+
+**Algorithm tips:**
+- Reels heavily prioritized over static posts
+- Saves and shares > likes
+- Stories keep you top of feed
+- Consistency matters more than perfection
+- Use all features (polls, questions, etc.)
+
+---
+
+## TikTok
+
+**Best for:** Brand awareness, younger audiences, viral potential
+**Audience:** 16-34, entertainment-focused
+**Posting frequency:** 1-4x per day
+**Best times:** 7-9am, 12-3pm, 7-11pm
+
+**What works:**
+- Native, unpolished content
+- Trending sounds and formats
+- Educational content in entertaining wrapper
+- POV and day-in-the-life content
+- Responding to comments with videos
+- Duets and stitches
+
+**What doesn't:**
+- Overly produced content
+- Ignoring trends
+- Hard selling
+- Repurposed horizontal video
+
+**Format tips:**
+- Hook in first 1-2 seconds
+- Keep it under 30 seconds to start
+- Vertical only (9:16)
+- Use trending sounds
+- Post consistently to train algorithm
+
+---
+
+## Facebook
+
+**Best for:** Communities, local businesses, older demographics, groups
+**Audience:** 25-55+, community-oriented
+**Posting frequency:** 1-2x per day
+**Best times:** 1-4pm weekdays
+
+**What works:**
+- Facebook Groups (community)
+- Native video
+- Live video
+- Local content and events
+- Discussion-prompting questions
+
+**What doesn't:**
+- Links to external sites (reach killer)
+- Pure promotional content
+- Ignoring comments
+- Cross-posting from other platforms without adaptation