@botlearn/social-media 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BotLearn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# @botlearn/social-media
+
+> Platform-adapted social media content creation with optimal hashtags, timing, and engagement optimization for OpenClaw Agent
+
+## Installation
+
+```bash
+# via npm
+npm install @botlearn/social-media
+
+# via clawhub
+clawhub install @botlearn/social-media
+```
+
+## Category
+
+Creative Generation
+
+## Dependencies
+
+`@botlearn/copywriter`
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `manifest.json` | Skill metadata and configuration |
+| `skill.md` | Role definition and activation rules |
+| `knowledge/` | Domain knowledge documents |
+| `strategies/` | Behavioral strategy definitions |
+| `tests/` | Smoke and benchmark tests |
+
+## License
+
+MIT

package/knowledge/anti-patterns.md

@@ -0,0 +1,74 @@
+---
+domain: social-media
+topic: anti-patterns
+priority: medium
+ttl: 30d
+---
+
+# Social Media — Anti-Patterns
+
+## Content Creation Anti-Patterns
+
+### 1. Cross-Posting Without Adaptation
+- **Problem**: Copying the same text verbatim across Twitter, LinkedIn, Instagram, and TikTok. Each platform's algorithm penalizes content that doesn't match its native format, and audiences perceive cross-posted content as lazy and inauthentic.
+- **Symptoms**: LinkedIn post with Twitter hashtags; Instagram caption that reads like a tweet; TikTok caption pasted from LinkedIn
+- **Fix**: Rewrite content for each platform — adjust tone, length, format, and CTA. Reuse the core idea but adapt the delivery. Wait 24-48 hours between cross-platform posts of the same idea.
+
+### 2. Hashtag Spam
+- **Problem**: Stuffing posts with 15-30 irrelevant or overly broad hashtags to "maximize reach." Modern algorithms detect hashtag spam and suppress distribution. It also signals low-quality content to users.
+- **Symptoms**: Wall of hashtags at the bottom of every post; hashtags unrelated to the content; using the same hashtag set for every post regardless of topic
+- **Fix**: Use 3-5 highly relevant hashtags per post. Rotate hashtags based on content topic. Follow the relevance pyramid: 1 broad + 2-3 niche + 1 branded. Test and measure which hashtags drive actual engagement.
+
+### 3. Ignoring Platform Culture
+- **Problem**: Writing formal corporate language on TikTok, or casual slang on LinkedIn. Each platform has unspoken cultural norms that determine whether content feels native or foreign.
+- **Symptoms**: Corporate press release tone on Instagram; meme language on LinkedIn; overly polished content on TikTok
+- **Fix**: Study top-performing content on each platform. Match the tone: LinkedIn = professional-but-human, Twitter = conversational-and-opinionated, Instagram = aspirational-and-visual, TikTok = authentic-and-entertaining.
+
+### 4. Missing the Hook
+- **Problem**: Burying the most interesting point three sentences deep. Social media feeds are scroll-driven; users decide in 1-2 seconds whether to engage.
+- **Symptoms**: Posts that start with "I wanted to share..." or "So today I was thinking..."; TikTok videos with 5+ second intros before the value
+- **Fix**: Lead with the hook. Start with the most surprising, useful, or provocative element. Use knowledge/best-practices.md hook techniques for each platform.
+
+### 5. Engagement Bait Without Value
+- **Problem**: Using manipulative engagement tactics ("Like if you agree!", "Comment YES for a free guide!") without delivering actual value. Platforms increasingly detect and penalize engagement bait.
+- **Symptoms**: High comment volume but low save/share rates; comments are all one-word responses; followers don't grow despite engagement numbers
+- **Fix**: Drive engagement through genuine value and authentic questions. If asking for comments, pose a thought-provoking question that encourages meaningful responses.
+
+## Formatting Anti-Patterns
+
+### 6. Wall-of-Text Posts
+- **Problem**: Writing long, unbroken paragraphs on platforms where visual scannability is critical. Users don't read social media — they scan.
+- **Symptoms**: LinkedIn posts with 500-word paragraphs; Instagram captions with no line breaks; Twitter threads with dense, text-heavy tweets
+- **Fix**: Use single-sentence paragraphs. Add line breaks every 1-2 sentences on LinkedIn and Instagram. Use bullet points or numbered lists for scannable content. On Twitter, one idea per tweet in threads.
+
+### 7. Over-Designed Visuals
+- **Problem**: Using overly polished, stock-photo-heavy, or corporate-branded visuals that feel like advertisements rather than native content. Authenticity outperforms polish on most platforms.
+- **Symptoms**: Every post looks like a corporate ad; stock photos with text overlays; heavy brand watermarks; templates that scream "marketing department"
+- **Fix**: Use authentic, behind-the-scenes photos. Screenshots and raw visuals outperform stock imagery. On TikTok and Instagram Reels, native filming (phone camera) outperforms professional production.
+
+### 8. Ignoring Accessibility
+- **Problem**: Not adding alt text, captions, or considering color contrast. This excludes audiences with disabilities and reduces reach (auto-captions boost engagement even for hearing users).
+- **Symptoms**: Videos without captions; images without alt text; text overlays in unreadable colors; font sizes too small for mobile
+- **Fix**: Always add captions to videos (auto-captions as minimum). Write alt text for images. Use high-contrast text overlays. Ensure text is readable at mobile scale (minimum 24pt).
+
+## Strategy Anti-Patterns
+
+### 9. Posting Without a Content Calendar
+- **Problem**: Posting randomly without a strategic plan leads to inconsistent output, missed opportunities (holidays, events, product launches), and burnout from last-minute content creation.
+- **Symptoms**: Posting 5 times one week, zero the next; missing relevant industry events or trending topics; repeating content themes without variety
+- **Fix**: Build a weekly content calendar. Plan 70% evergreen content, 20% trending/timely content, 10% experimental. Batch-create content in advance. Use the content-platform fit matrix from knowledge/best-practices.md.
+
+### 10. Ignoring Analytics and Iteration
+- **Problem**: Publishing content without reviewing performance metrics. Without data-driven iteration, you repeat what doesn't work and miss opportunities to double down on what does.
+- **Symptoms**: Same content format despite declining engagement; no A/B testing of hooks or CTAs; unfounded assumptions about audience preferences
+- **Fix**: Review engagement metrics weekly. Track: impressions, engagement rate, saves, shares, follower growth. Identify top-performing content patterns and create more of what works. A/B test hooks, formats, and posting times.
+
+### 11. Link-Dumping on Algorithm-Hostile Platforms
+- **Problem**: Posting external links directly in the post body on platforms that suppress link-containing posts (especially LinkedIn and Instagram).
+- **Symptoms**: Low-reach posts with URLs in the body; "link in bio" without actually updating the bio link; LinkedIn posts with links getting 40% less reach
+- **Fix**: On LinkedIn, add links in the first comment, not the post body. On Instagram, use "link in bio" tools (Linktree, etc.) and reference them in the caption. On Twitter, link-containing tweets are suppressed — consider a thread where the link is in the final tweet rather than the first.
+
+### 12. Neglecting Community Engagement
+- **Problem**: Treating social media as a broadcast channel rather than a conversation. Posting content but never responding to comments, never engaging with others' content, and never participating in community discussions.
+- **Symptoms**: Zero replies to comments on own posts; no engagement with other creators; declining reach despite consistent posting; audience asks questions that go unanswered
+- **Fix**: Reply to every comment within the first hour of posting (critical for algorithmic boost). Engage with 10-15 relevant posts from others daily. Join conversations in your niche. Social media rewards social behavior.

package/knowledge/best-practices.md

@@ -0,0 +1,124 @@
+---
+domain: social-media
+topic: engagement-optimization-and-content-strategy
+priority: high
+ttl: 30d
+---
+
+# Social Media — Best Practices
+
+## Platform-Native Content Creation
+
+### 1. Write for the Platform, Not for Yourself
+Every platform has a distinct communication culture:
+- **Twitter/X**: Punchy, opinionated, conversational. Use sentence fragments. Ask questions. Be quotable.
+- **LinkedIn**: Professional but human. Lead with insights. Share lessons learned. Use paragraph breaks generously.
+- **Instagram**: Visual-first storytelling. Captions complement the visual; start with a hook line. Use line breaks for readability.
+- **TikTok**: Entertainment-first education. Front-load the hook in the first 1-3 seconds. Speak directly to the viewer.
+
+### 2. The Hook-First Principle
+The first line (or first 3 seconds for video) determines whether users engage or scroll past:
+
+| Platform | Hook Technique | Example |
+|----------|---------------|---------|
+| Twitter/X | Contrarian statement | "Most marketing advice is wrong. Here's what actually works:" |
+| LinkedIn | Data-driven opener | "I analyzed 500 LinkedIn posts. Here's what the top 1% do differently." |
+| Instagram | Curiosity gap | "Stop doing this one thing and watch your engagement triple" |
+| TikTok | Pattern interrupt | "POV: You just discovered the one trick no one talks about" |
+
+### 3. Content-Platform Fit Matrix
+
+| Content Type | Twitter/X | LinkedIn | Instagram | TikTok |
+|-------------|-----------|----------|-----------|--------|
+| Hot take / Opinion | Thread or single tweet | Text post with elaboration | Carousel with supporting points | Talking head with text overlay |
+| Tutorial / How-to | Thread with steps | Carousel or document | Carousel with visuals | Step-by-step video |
+| Announcement | Single tweet + visual | Text post + image | Feed post + story | Short announcement video |
+| Behind the scenes | Photo tweet + context | Story-driven post | Story or reel | Raw, authentic video |
+| Data / Research | Thread with charts | Carousel with data viz | Carousel infographic | Explainer video with overlays |
+
+## Hashtag Strategy
+
+### 4. The Hashtag Relevance Pyramid
+For maximum discoverability without triggering spam detection:
+
+```
+          [1 Branded]
+         /           \
+      [2-3 Niche Topic]
+       /               \
+    [1-2 Industry Broad]
+```
+
+- **Branded** (optional): Your unique campaign or company tag (e.g., #BotLearnTips)
+- **Niche Topic**: Specific to the content's subject (e.g., #ContentCalendar, #LinkedInGrowth)
+- **Industry Broad**: Category-level tags (e.g., #DigitalMarketing, #SocialMedia)
+
+### 5. Hashtag Selection Criteria
+- **Relevance score**: Does the hashtag's content feed match your post topic? Check by browsing the hashtag feed first.
+- **Volume sweet spot**: Avoid overly saturated tags (>10M posts on Instagram) where your content drowns. Target 50K-500K for growth accounts.
+- **Community signal**: Hashtags used by your target audience (not just your competitors) drive better follower quality.
+- **Recency check**: Ensure the hashtag is still actively used and not associated with banned or controversial content.
+
+### 6. Platform-Specific Hashtag Counts
+
+| Platform | Minimum | Optimal | Maximum (before penalty) |
+|----------|---------|---------|--------------------------|
+| Twitter/X | 0 | 1-2 | 3 |
+| LinkedIn | 2 | 3-5 | 9 |
+| Instagram | 3 | 3-5 | 15 |
+| TikTok | 2 | 3-5 | 8 |
+
+## Engagement Optimization
+
+### 7. The Engagement Flywheel
+Content that generates engagement follows this cycle:
+
+1. **Hook** — Grab attention in the first line/second
+2. **Value** — Deliver useful, novel, or entertaining content
+3. **Relatability** — Make the audience see themselves in the content
+4. **CTA** — Ask for a specific, low-friction action (comment, save, share)
+5. **Response** — Reply to comments within the first hour to boost algorithmic distribution
+
+### 8. Call-to-Action Best Practices
+
+| CTA Type | Platform Fit | Example |
+|----------|-------------|---------|
+| Question CTA | Twitter, LinkedIn | "What's your experience with this? Drop it below." |
+| Save CTA | Instagram | "Save this for when you need it" |
+| Share CTA | All platforms | "Tag someone who needs to see this" |
+| Follow CTA | TikTok, Instagram | "Follow for Part 2" |
+| Comment CTA | LinkedIn | "Agree or disagree? I want to hear your take." |
+| Poll CTA | Twitter, LinkedIn | "Which approach do you prefer? Vote below." |
+
+### 9. Timing and Frequency
+
+- **Consistency over volume**: Posting 3x/week consistently outperforms 10x/week sporadic posting
+- **Platform-specific cadence**:
+  - Twitter/X: 3-5 tweets/day (including replies and RTs)
+  - LinkedIn: 3-5 posts/week (daily during campaigns)
+  - Instagram: 4-7 posts/week (mix of feed, reels, stories)
+  - TikTok: 1-3 videos/day (quantity + variety = growth)
+- **Batch creation**: Create content in batches (e.g., 10 posts in one session), schedule across the week
+- **Repurposing window**: Wait 7-14 days before adapting the same core idea for a different platform
+
+## Content Series and Threads
+
+### 10. Building Content Series
+Series content drives returning viewers and follower growth:
+- **Numbering**: "Day 5 of 30" or "Part 3/7" creates commitment and anticipation
+- **Consistent format**: Same visual template, same intro structure, predictable rhythm
+- **Hook forward**: End each piece with a tease for the next installment
+- **Recap**: Every 5-7 installments, create a recap/compilation post
+
+### 11. Thread Construction (Twitter/X)
+- **Tweet 1**: The hook — promise a clear value proposition ("I spent 100 hours analyzing X. Here's what I found:")
+- **Tweet 2-N**: One idea per tweet; use numbers or bullets; include visuals every 2-3 tweets
+- **Final tweet**: Summary + CTA + self-retweet of tweet 1 for thread visibility
+- **Length**: 5-7 tweets for engagement; 10-15 for viral potential; never exceed 20
+
+### 12. Carousel Best Practices (LinkedIn/Instagram)
+- **Slide 1**: Cover slide with a bold, curiosity-driven headline (this is the hook)
+- **Slide 2**: Context or "why this matters"
+- **Slides 3-N**: One takeaway per slide; large text; minimal clutter
+- **Final slide**: Summary + CTA ("Save this", "Follow for more", "Share with your team")
+- **Design**: Consistent brand colors; readable font size (min 24pt on mobile); high contrast

package/knowledge/domain.md

@@ -0,0 +1,175 @@
+---
+domain: social-media
+topic: platform-specifications-and-algorithms
+priority: high
+ttl: 30d
+---
+
+# Social Media — Platform Specifications & Algorithm Preferences
+
+## Twitter / X
+
+### Technical Limits
+- **Character limit**: 280 characters (standard), 25,000 characters (Premium+)
+- **Image**: Up to 4 images per tweet; JPEG, PNG, GIF; max 5MB per image
+- **Video**: Max 2 min 20 sec (standard), 60 min (premium); max 512MB; MP4/MOV
+- **Thread**: Unlimited tweets per thread; each tweet counts independently toward character limit
+- **Link preview**: Consumes ~23 characters regardless of URL length
+- **Poll**: 2-4 options, max 25 characters per option, duration 5 min to 7 days
+
+### Algorithm Signals (Ranked by Impact)
+1. **Reply engagement** — Tweets that generate replies are boosted significantly
+2. **Dwell time** — Time spent reading the tweet (longer = better for threads)
+3. **Retweets with quote** — Weighted higher than plain retweets
+4. **Recency** — Strong recency bias; half-life ~20 minutes for non-viral content
+5. **Media attachment** — Tweets with images get ~150% more engagement; video ~200%
+6. **Follower interaction history** — Content from accounts users frequently engage with is prioritized
+7. **Topic relevance** — Tweets matching trending topics or user interest signals are boosted
+
+### Content Formats
+- **Single tweet**: Concise take, question, or hot take — max impact in minimal words
+- **Thread (1/n)**: Long-form storytelling or educational content; 3-10 tweets optimal
+- **Quote tweet**: Commentary on existing content — adds perspective
+- **Poll**: Community engagement; drives replies and shares
+- **Spaces summary**: Recap of live audio discussions
+
+### Hashtag Rules
+- **Optimal count**: 1-2 hashtags per tweet (3+ reduces engagement by ~17%)
+- **Placement**: Inline with text or at end of tweet; never start with hashtag unless a branded campaign
+- **Character impact**: Hashtags count toward the 280-character limit
+
+---
+
+## LinkedIn
+
+### Technical Limits
+- **Post character limit**: 3,000 characters
+- **Article**: Unlimited length (published via LinkedIn's article editor)
+- **Image**: Up to 9 images per carousel post; JPEG, PNG; max 10MB
+- **Video**: 3 sec to 10 min (recommended); max 5GB; MP4
+- **Document/Carousel**: PDF upload; up to 300 pages (carousel format)
+- **Poll**: 2-4 options, duration 1 day to 2 weeks
+
+### Algorithm Signals (Ranked by Impact)
+1. **Dwell time** — LinkedIn heavily weights time spent on a post; long-form outperforms short
+2. **Comments (especially early)** — Posts receiving comments within the first hour get massive distribution
+3. **Content format** — Carousels > Documents > Videos > Images > Text-only (in terms of algorithmic boost)
+4. **Personal stories** — Personal narrative posts outperform corporate or promotional content
+5. **"See more" clicks** — Posts that get users to click "...see more" signal engagement
+6. **Profile strength** — Posts from complete profiles with active networks distribute wider
+7. **External links** — Posts with external links receive ~40% less distribution (put links in comments)
+8. **Hashtag relevance** — Relevant hashtags help discovery; irrelevant ones can hurt
+
+### Content Formats
+- **Text post**: Professional insight, career story, industry commentary — 1,200-1,500 chars optimal
+- **Carousel**: Educational slide decks; 8-12 slides; each slide one clear takeaway
+- **Document post**: PDF-based tutorials or frameworks shared as scrollable documents
+- **Poll**: Professional opinion gathering; drives engagement and discussion
+- **Article**: Long-form thought leadership; lower reach but higher authority signal
+- **Video**: Behind-the-scenes, talking head, or explainer; vertical (9:16) or square (1:1)
+
+### Hashtag Rules
+- **Optimal count**: 3-5 hashtags per post
+- **Placement**: At the end of the post, below the main content
+- **Mix strategy**: 1 broad industry tag + 2-3 niche topic tags + 1 branded tag
+- **Capitalization**: Use CamelCase for readability (e.g., #ContentMarketing, #AIStrategy)
+
+---
+
+## Instagram
+
+### Technical Limits
+- **Caption character limit**: 2,200 characters
+- **Bio**: 150 characters
+- **Image**: Square (1:1), Portrait (4:5), Landscape (1.91:1); JPEG/PNG; max 30MB
+- **Reels**: 15 sec, 30 sec, 60 sec, 90 sec; vertical (9:16); MP4/MOV
+- **Stories**: 15 sec per slide; vertical (9:16); auto-split longer videos
+- **Carousel**: Up to 20 images/videos per carousel post
+- **Hashtag limit**: 30 per post (but optimal is far fewer)
+
+### Algorithm Signals (Ranked by Impact)
+1. **Saves** — The strongest engagement signal; content worth revisiting is prioritized
+2. **Shares (DM shares)** — Content shared via DMs signals high value
+3. **Reel completion rate** — Reels watched to the end (or replayed) get massive distribution
+4. **Comments** — Especially comments with 4+ words (not just emojis)
+5. **Carousel swipe-through rate** — Users swiping through all carousel slides boosts ranking
+6. **Content type alignment** — Algorithm shows users more of the format they engage with
+7. **Posting consistency** — Regular posting (4-7 times/week) maintains algorithmic favorability
+8. **Audio trends** — Reels using trending audio get discovery boosts
+
+### Content Formats
+- **Single image**: High-quality photo with educational or inspirational caption
+- **Carousel**: Educational content, storytelling, before/after; 5-10 slides; first slide is the hook
+- **Reel**: Short-form video; entertaining, educational, or trending format; 15-30 sec optimal for reach
+- **Story**: Ephemeral, behind-the-scenes, polls, Q&A, links — drives engagement and community
+- **Guide**: Curated collection of posts around a theme; evergreen content
+
+### Hashtag Rules
+- **Optimal count**: 3-5 highly relevant hashtags (Instagram's own recommendation)
+- **Placement**: In the caption (first comment placement no longer offers advantage)
+- **Mix strategy**: 1 broad (1M+ posts) + 2-3 medium (100K-1M) + 1-2 niche (10K-100K)
+- **Avoid**: Banned or flagged hashtags; check before using
+
+---
+
+## TikTok
+
+### Technical Limits
+- **Video length**: 15 sec, 60 sec, 3 min, 10 min
+- **Caption character limit**: 4,000 characters (expanded from original 150)
+- **Aspect ratio**: 9:16 (vertical) required for full-screen experience
+- **File size**: Max 287.6MB (mobile), 500MB (desktop); MP4/MOV/WebM
+- **Text overlay**: On-screen text; auto-captions available
+- **Stitch/Duet**: Collaborative formats using other creators' content
+
+### Algorithm Signals (Ranked by Impact)
+1. **Completion rate** — The single most important metric; short videos that play to the end win
+2. **Replay rate** — Videos watched multiple times get exponential distribution
+3. **Share rate** — Content shared to other platforms or via DM
+4. **Comment engagement** — Volume and sentiment of comments
+5. **Watch time** — Total time spent on the video (not just completion)
+6. **Sound usage** — Using trending sounds gives discovery advantages
+7. **Content diversity** — The algorithm favors creators who vary their content style
+8. **Posting frequency** — 1-4 posts per day is optimal for growth
+
+### Content Formats
+- **Talking head**: Direct-to-camera education, opinion, or storytelling; authentic delivery
+- **Tutorial**: Step-by-step how-to; visual demonstration; text overlays for clarity
+- **Trend participation**: Using trending sounds, formats, or challenges with original twist
+- **Stitch/Duet**: Reacting to or building on other creators' content
+- **Story time**: Narrative format; hooks viewers with a compelling opening question or statement
+- **List/Ranking**: "Top 5...", "3 things you...", numbered educational content
+
+### Hashtag Rules
+- **Optimal count**: 3-5 hashtags
+- **Placement**: In the caption, mixed with descriptive text
+- **Strategy**: 1-2 trending/challenge hashtags + 2-3 niche/topic hashtags
+- **Avoid**: #fyp, #foryou, #foryoupage — these generic tags no longer provide meaningful reach
+
+---
+
+## Cross-Platform Posting Schedule Reference
+
+### Peak Engagement Windows (UTC)
+
+| Platform | Best Days | Best Times (UTC) | Worst Times |
+|----------|-----------|-------------------|-------------|
+| Twitter/X | Tue-Thu | 13:00-16:00 | Sat 22:00-Sun 06:00 |
+| LinkedIn | Tue-Thu | 07:00-09:00, 12:00-13:00 | Weekends, after 18:00 |
+| Instagram | Mon, Wed, Fri | 11:00-14:00, 19:00-21:00 | Sun 03:00-06:00 |
+| TikTok | Tue-Thu | 10:00-12:00, 19:00-22:00 | Mon morning |
+
+*Note*: These are global averages. Adjust for audience timezone and industry vertical. B2B content performs best during business hours; B2C content peaks in evening leisure hours.
+
+## Content Length Sweet Spots
+
+| Platform | Format | Optimal Length | Engagement Impact |
+|----------|--------|---------------|-------------------|
+| Twitter/X | Tweet | 70-100 chars | +21% engagement vs 280-char tweets |
+| Twitter/X | Thread | 5-7 tweets | +310% reach vs single tweet |
+| LinkedIn | Text post | 1,200-1,500 chars | +37% engagement vs short posts |
+| LinkedIn | Carousel | 8-12 slides | +280% reach vs image posts |
+| Instagram | Caption | 400-800 chars | Optimal for saves and shares |
+| Instagram | Reel | 15-30 sec | +55% reach vs 60+ sec |
+| TikTok | Video | 21-34 sec | Highest completion rate bracket |
+| TikTok | Caption | 100-300 chars | Enough for context + hashtags |

package/manifest.json

@@ -0,0 +1,28 @@
+{
+  "name": "@botlearn/social-media",
+  "version": "0.1.0",
+  "description": "Platform-adapted social media content creation with optimal hashtags, timing, and engagement optimization for OpenClaw Agent",
+  "category": "creative-generation",
+  "author": "BotLearn",
+  "benchmarkDimension": "creative-generation",
+  "expectedImprovement": 30,
+  "dependencies": {
+    "@botlearn/copywriter": "^1.0.0"
+  },
+  "compatibility": {
+    "openclaw": ">=0.5.0"
+  },
+  "files": {
+    "skill": "skill.md",
+    "knowledge": [
+      "knowledge/domain.md",
+      "knowledge/best-practices.md",
+      "knowledge/anti-patterns.md"
+    ],
+    "strategies": [
+      "strategies/main.md"
+    ],
+    "smokeTest": "tests/smoke.json",
+    "benchmark": "tests/benchmark.json"
+  }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@botlearn/social-media",
+  "version": "0.1.0",
+  "description": "Platform-adapted social media content creation with optimal hashtags, timing, and engagement optimization for OpenClaw Agent",
+  "type": "module",
+  "main": "manifest.json",
+  "files": [
+    "manifest.json",
+    "skill.md",
+    "knowledge/",
+    "strategies/",
+    "tests/",
+    "README.md"
+  ],
+  "keywords": [
+    "botlearn",
+    "openclaw",
+    "skill",
+    "creative-generation"
+  ],
+  "author": "BotLearn",
+  "license": "MIT",
+  "dependencies": {
+    "@botlearn/copywriter": "0.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/readai-team/botlearn-awesome-skills.git",
+    "directory": "packages/skills/social-media"
+  },
+  "homepage": "https://github.com/readai-team/botlearn-awesome-skills/tree/main/packages/skills/social-media",
+  "bugs": {
+    "url": "https://github.com/readai-team/botlearn-awesome-skills/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skill.md

@@ -0,0 +1,47 @@
+---
+name: social-media
+role: Social Media Content Specialist
+version: 1.0.0
+triggers:
+  - "social media post"
+  - "tweet"
+  - "LinkedIn post"
+  - "Instagram caption"
+  - "TikTok script"
+  - "create a post"
+  - "social content"
+  - "post for"
+---
+
+# Role
+
+You are a Social Media Content Specialist. When activated, you create platform-adapted content with optimal hashtags, timing recommendations, and engagement-maximizing formatting. You leverage copywriting expertise (via @botlearn/copywriter) to craft persuasive, audience-resonant content tailored to each platform's unique culture, algorithm preferences, and technical constraints.
+
+# Capabilities
+
+1. Analyze target platform specifications (character limits, media formats, algorithm signals) and adapt content accordingly
+2. Generate platform-native content that matches the tone, style, and conventions of Twitter/X, LinkedIn, Instagram, and TikTok
+3. Select and optimize hashtag strategies per platform — balancing discoverability with relevance and avoiding spam signals
+4. Recommend optimal posting times based on audience demographics, platform-specific engagement windows, and content type
+5. Predict engagement potential by evaluating hook strength, format alignment, CTA clarity, and algorithmic favorability
+6. Create content series and threads that build narrative momentum across multiple posts
+
+# Constraints
+
+1. Never cross-post identical content across platforms — always adapt format, tone, and length to platform norms
+2. Never exceed platform character or media limits — respect Twitter's 280 chars, LinkedIn's 3,000 chars, Instagram's 2,200 chars
+3. Never use more than the platform-optimal number of hashtags — avoid hashtag spam that triggers algorithm suppression
+4. Never ignore platform culture — LinkedIn is professional, Twitter is conversational, Instagram is visual, TikTok is entertainment-first
+5. Never generate content without a clear call-to-action or engagement hook appropriate to the platform
+6. Always disclose when content is promotional or sponsored, in compliance with platform guidelines
+
+# Activation
+
+WHEN the user requests social media content creation:
+1. Identify the target platform(s) and audience from the user's request
+2. Analyze platform constraints and algorithm preferences using knowledge/domain.md
+3. Apply copywriting principles (inherited from @botlearn/copywriter) for persuasive messaging
+4. Follow the content creation strategy in strategies/main.md
+5. Validate content against knowledge/best-practices.md for engagement optimization
+6. Verify against knowledge/anti-patterns.md to avoid common social media mistakes
+7. Output platform-ready content with hashtags, timing recommendations, and engagement predictions

package/strategies/main.md

@@ -0,0 +1,111 @@
+---
+strategy: social-media
+version: 1.0.0
+steps: 6
+---
+
+# Social Media Content Creation Strategy
+
+## Step 1: Platform Analysis
+- Parse the user's request to identify: **target platform(s)**, **audience**, **content goal**, **topic**, and **desired tone**
+- IF no platform is specified THEN ask which platform(s) the content is for, or default to the most likely platform based on context clues
+- Look up platform specifications from knowledge/domain.md:
+  - Character limits and media constraints
+  - Algorithm ranking signals
+  - Native content formats
+  - Hashtag rules and limits
+- Identify the audience demographic and match to platform engagement windows from knowledge/domain.md
+- IF multiple platforms are requested THEN plan separate, adapted content for each — never cross-post identical content
+
+## Step 2: Content Ideation
+- Determine the content type that best fits the platform and goal using the content-platform fit matrix from knowledge/best-practices.md
+- Apply copywriting principles from @botlearn/copywriter dependency:
+  - Identify the core value proposition or message
+  - Define the emotional trigger: curiosity, urgency, aspiration, relatability, humor
+  - Select the persuasion framework: problem-solution, storytelling, data-driven, social proof
+- Generate 2-3 hook options following the hook-first principle from knowledge/best-practices.md:
+  - Twitter/X: Contrarian statement, bold claim, or provocative question
+  - LinkedIn: Data-driven opener, personal story lead, or industry insight
+  - Instagram: Curiosity gap, bold visual headline, or emotional trigger
+  - TikTok: Pattern interrupt, "POV" framing, or "things nobody tells you" format
+- SELECT the strongest hook based on: novelty, emotional resonance, and scroll-stopping potential
+- IF the content is part of a series THEN reference previous installments and tease future ones
+
+## Step 3: Format Adaptation
+- Write platform-specific content following native format conventions:
+  - **Twitter/X single tweet**: 70-100 characters for maximum engagement; punch and clarity
+  - **Twitter/X thread**: 5-7 tweets; tweet 1 = hook with thread promise; one idea per tweet; final tweet = summary + CTA
+  - **LinkedIn text post**: 1,200-1,500 characters; single-sentence paragraphs; "see more" hook in first 2 lines; professional but human tone
+  - **LinkedIn carousel**: 8-12 slides; cover slide = bold headline; 1 takeaway per slide; final slide = CTA
+  - **Instagram caption**: 400-800 characters; hook in first line (before fold); line breaks every 1-2 sentences; end with CTA
+  - **Instagram carousel**: 5-10 slides; first slide = visual hook; educational or storytelling structure
+  - **TikTok script**: 21-34 seconds; hook in first 3 seconds; conversational tone; clear text overlays; trending sound note
+- APPLY platform-specific formatting:
+  - Use line breaks generously (LinkedIn, Instagram)
+  - Use emojis sparingly and platform-appropriately (Instagram yes, LinkedIn minimal, Twitter situational)
+  - Include text overlay notes for video content (TikTok, Instagram Reels)
+- VERIFY content does not exceed platform character/time limits from knowledge/domain.md
+- VERIFY content avoids anti-patterns from knowledge/anti-patterns.md (no wall-of-text, no corporate tone on casual platforms)
+
+## Step 4: Hashtag Selection
+- SELECT hashtags using the relevance pyramid from knowledge/best-practices.md:
+  1. Choose 1 broad industry hashtag (high volume, category-level)
+  2. Choose 2-3 niche topic hashtags (medium volume, specific to content subject)
+  3. Choose 0-1 branded hashtag (if applicable to campaign or personal brand)
+- VERIFY hashtag count matches platform optimal range from knowledge/domain.md:
+  - Twitter/X: 1-2 hashtags
+  - LinkedIn: 3-5 hashtags
+  - Instagram: 3-5 hashtags
+  - TikTok: 3-5 hashtags
+- VALIDATE each hashtag:
+  - Is it currently active? (not dead or abandoned)
+  - Is it relevant to the content? (would browsing this hashtag's feed show similar content?)
+  - Is it safe? (not banned, flagged, or associated with controversial content)
+- IF on Twitter/X THEN integrate hashtags naturally within the text or append at end
+- IF on LinkedIn THEN place hashtags below the main content, separated by a line break
+- IF on Instagram THEN place hashtags at the end of the caption
+- IF on TikTok THEN weave hashtags into the caption text naturally
+
+## Step 5: Timing Optimization
+- RECOMMEND optimal posting time based on:
+  1. **Platform engagement windows** from knowledge/domain.md cross-platform schedule
+  2. **Audience timezone** — IF specified, convert peak times to audience local time
+  3. **Content type** — Educational content performs better in morning; entertaining in evening
+  4. **Day of week** — B2B content peaks Tue-Thu; B2C content performs well on weekends
+- IF the user specifies an audience region THEN adjust timing:
+  - US East Coast: UTC-5 (EST) / UTC-4 (EDT)
+  - US West Coast: UTC-8 (PST) / UTC-7 (PDT)
+  - Europe (Central): UTC+1 (CET) / UTC+2 (CEST)
+  - Asia (East): UTC+8 (CST/HKT) / UTC+9 (JST)
+- RECOMMEND posting frequency based on platform best practices:
+  - Twitter/X: 3-5 tweets/day
+  - LinkedIn: 3-5 posts/week
+  - Instagram: 4-7 posts/week (mix of formats)
+  - TikTok: 1-3 videos/day
+- IF the content is time-sensitive (event, trend, news) THEN recommend posting immediately regardless of optimal windows
+
+## Step 6: Engagement Prediction & Output
+- EVALUATE the content's engagement potential by scoring these dimensions (1-5):
+  - **Hook strength**: Does the first line/second stop the scroll?
+  - **Value delivery**: Does the content teach, entertain, or inspire?
+  - **Format alignment**: Is the format native to the platform?
+  - **CTA clarity**: Is the call-to-action clear and low-friction?
+  - **Algorithmic fit**: Does the content match the platform's ranking signals?
+- CALCULATE predicted engagement level:
+  - Average score 4.0+ → High engagement predicted
+  - Average score 3.0-3.9 → Moderate engagement predicted
+  - Average score below 3.0 → Low engagement — revise content before publishing
+- IF predicted engagement is Low THEN loop back to Step 2 and strengthen the weakest dimension
+- OUTPUT the final content package:
+  1. **Platform-ready content**: The post text, formatted for the target platform
+  2. **Hashtags**: Selected and placed per platform convention
+  3. **Posting time**: Recommended day and time with timezone context
+  4. **Media notes**: Suggested image, video, or carousel specifications (if applicable)
+  5. **Engagement prediction**: Score breakdown and expected performance
+  6. **Variation** (optional): An A/B test alternative with a different hook or CTA
+- SELF-CHECK:
+  - Does the content respect platform character/media limits?
+  - Is the tone platform-native and audience-appropriate?
+  - Are hashtags relevant and within optimal count?
+  - Does the CTA match the platform's preferred engagement type?
+  - IF any check fails THEN revise the specific element before final output

package/tests/benchmark.json

@@ -0,0 +1,476 @@
+{
+  "version": "0.0.1",
+  "dimension": "creative-generation",
+  "tasks": [
+    {
+      "id": "bench-easy-01",
+      "difficulty": "easy",
+      "description": "Create a single tweet for a simple product announcement",
+      "input": "Write a tweet announcing that our open-source CLI tool 'DevFlow' just hit 10,000 GitHub stars. Keep it celebratory and authentic. Include 1-2 relevant hashtags.",
+      "rubric": [
+        {
+          "criterion": "Platform Fit",
+          "weight": 0.35,
+          "scoring": {
+            "5": "Tweet is under 280 characters; concise, punchy, conversational tone; feels native to Twitter culture; celebratory without being corporate",
+            "3": "Under 280 characters but reads like a generic announcement; could be from any platform",
+            "1": "Exceeds character limit or uses non-Twitter formatting",
+            "0": "Not recognizable as a tweet"
+          }
+        },
+        {
+          "criterion": "Engagement Potential",
+          "weight": 0.35,
+          "scoring": {
+            "5": "Includes elements that drive engagement: community gratitude, milestone celebration, implicit CTA (star the repo, celebrate together); emotionally resonant",
+            "3": "Decent engagement potential but missing a clear hook or CTA",
+            "1": "Flat announcement with no engagement drivers",
+            "0": "Reads as spam or self-promotion"
+          }
+        },
+        {
+          "criterion": "Hashtag Usage",
+          "weight": 0.3,
+          "scoring": {
+            "5": "1-2 relevant hashtags naturally integrated; tags match the developer/open-source community",
+            "3": "Hashtags present but slightly off-target or awkwardly placed",
+            "1": "Too many hashtags or irrelevant tags",
+            "0": "No hashtags or hashtag spam"
+          }
+        }
+      ],
+      "expectedScoreWithout": 40,
+      "expectedScoreWith": 80
+    },
+    {
+      "id": "bench-easy-02",
+      "difficulty": "easy",
+      "description": "Write an Instagram caption for a product photo",
+      "input": "Write an Instagram caption for a photo of our new ergonomic standing desk 'AltitudeDesk'. The desk features bamboo wood, electric height adjustment, and a built-in wireless charger. Target audience: remote workers and home office enthusiasts. Include relevant hashtags.",
+      "rubric": [
+        {
+          "criterion": "Platform Fit",
+          "weight": 0.35,
+          "scoring": {
+            "5": "Caption is Instagram-native: strong hook in first line, line breaks for readability, 400-800 characters, aspirational/lifestyle tone, complements a visual",
+            "3": "Adequate caption but reads like product specs rather than lifestyle content",
+            "1": "Too long, too short, or formatted for another platform",
+            "0": "Not recognizable as an Instagram caption"
+          }
+        },
+        {
+          "criterion": "Hook & CTA",
+          "weight": 0.35,
+          "scoring": {
+            "5": "First line creates curiosity or emotional pull; ends with a clear CTA (save, comment, share, link in bio); both are platform-appropriate",
+            "3": "Hook or CTA present but not both; or both are generic",
+            "1": "Weak hook and no CTA",
+            "0": "No hook or CTA; reads as product description"
+          }
+        },
+        {
+          "criterion": "Hashtag Strategy",
+          "weight": 0.3,
+          "scoring": {
+            "5": "3-5 relevant hashtags; mix of broad (#HomeOffice) and niche (#StandingDeskSetup); placed at caption end",
+            "3": "Hashtags present but count or relevance is off",
+            "1": "Hashtag spam or irrelevant tags",
+            "0": "No hashtags"
+          }
+        }
+      ],
+      "expectedScoreWithout": 40,
+      "expectedScoreWith": 80
+    },
+    {
+      "id": "bench-easy-03",
+      "difficulty": "easy",
+      "description": "Create a simple LinkedIn poll post",
+      "input": "Create a LinkedIn post with a poll asking engineering managers about their biggest challenge with remote team management. The poll should have 4 options. Include a brief intro that encourages participation and relevant hashtags.",
+      "rubric": [
+        {
+          "criterion": "Platform Fit",
+          "weight": 0.3,
+          "scoring": {
+            "5": "LinkedIn-native tone; professional but conversational; appropriate length for a poll intro (300-600 chars); paragraph breaks for readability",
+            "3": "Reasonable LinkedIn post but the poll intro is generic or too formal",
+            "1": "Tone mismatch or poor formatting for LinkedIn",
+            "0": "Not suitable for LinkedIn"
+          }
+        },
+        {
+          "criterion": "Poll Quality",
+          "weight": 0.4,
+          "scoring": {
+            "5": "4 clear, distinct, non-overlapping poll options that resonate with engineering managers; options are concise and cover the most common challenges",
+            "3": "4 options but some overlap or are too vague",
+            "1": "Options are unclear, overlapping, or not relevant to the audience",
+            "0": "No poll options provided or completely irrelevant"
+          }
+        },
+        {
+          "criterion": "Engagement Driver",
+          "weight": 0.3,
+          "scoring": {
+            "5": "Intro asks a thought-provoking question; includes CTA to elaborate in comments; framed to encourage sharing with peers; hashtags are relevant",
+            "3": "Basic intro with poll; some engagement element present",
+            "1": "Flat intro with no engagement drivers",
+            "0": "No intro or engagement strategy"
+          }
+        }
+      ],
+      "expectedScoreWithout": 40,
+      "expectedScoreWith": 80
+    },
+    {
+      "id": "bench-med-01",
+      "difficulty": "medium",
+      "description": "Adapt a single topic into platform-specific content for two platforms",
+      "input": "We just published a blog post titled '5 Lessons from Scaling Our API from 1K to 1M Requests Per Second'. Create social media content to promote it on both Twitter/X (as a thread) and LinkedIn (as a text post). The target audience is backend engineers and engineering leaders. Include platform-appropriate hashtags and timing recommendations.",
+      "rubric": [
+        {
+          "criterion": "Platform Differentiation",
+          "weight": 0.3,
+          "scoring": {
+            "5": "Twitter thread and LinkedIn post are clearly distinct in tone, format, and length; each feels native to its platform; not a copy-paste between platforms",
+            "3": "Some differentiation but the core text is similar; one platform feels more natural than the other",
+            "1": "Minimal differentiation; essentially the same content on both platforms",
+            "0": "Identical content cross-posted"
+          }
+        },
+        {
+          "criterion": "Twitter Thread Quality",
+          "weight": 0.25,
+          "scoring": {
+            "5": "5-7 tweet thread; tweet 1 is a compelling hook with thread promise; one lesson per tweet; punchy, quotable language; final tweet has summary + CTA + link",
+            "3": "Thread structure present but hooks are weak or tweets are too dense",
+            "1": "Thread is really just one long tweet split arbitrarily; no narrative flow",
+            "0": "Not formatted as a thread or exceeds character limits"
+          }
+        },
+        {
+          "criterion": "LinkedIn Post Quality",
+          "weight": 0.25,
+          "scoring": {
+            "5": "1,200-1,500 chars; professional insights tone; 'see more' hook; lessons presented with leadership context; link in comments note; 3-5 relevant hashtags",
+            "3": "Reasonable LinkedIn post but generic hook or missing some elements",
+            "1": "Poorly formatted for LinkedIn or reads like a tweet",
+            "0": "Not suitable for LinkedIn"
+          }
+        },
+        {
+          "criterion": "Timing & Hashtags",
+          "weight": 0.2,
+          "scoring": {
+            "5": "Platform-specific timing recommendations with rationale; hashtags are different between platforms and appropriate to each; correct count per platform",
+            "3": "Some timing/hashtag guidance but not platform-specific",
+            "1": "Generic timing or identical hashtags on both platforms",
+            "0": "No timing or hashtag guidance"
+          }
+        }
+      ],
+      "expectedScoreWithout": 30,
+      "expectedScoreWith": 70
+    },
+    {
+      "id": "bench-med-02",
+      "difficulty": "medium",
+      "description": "Create a TikTok script with engagement optimization",
+      "input": "Write a TikTok video script (30 seconds) for a personal finance creator explaining the '50/30/20 budget rule'. The audience is Gen Z (18-25). The tone should be casual, relatable, and slightly humorous. Include text overlay suggestions, a trending sound recommendation note, and hashtags.",
+      "rubric": [
+        {
+          "criterion": "Platform Nativeness",
+          "weight": 0.3,
+          "scoring": {
+            "5": "Script is unmistakably TikTok: direct-to-camera, conversational, uses TikTok-native language and formats (POV, 'things nobody tells you', etc.); 21-34 seconds; includes text overlay notes and sound suggestion",
+            "3": "Script works for TikTok but could be any short-form video; missing TikTok-specific elements",
+            "1": "Script reads like a YouTube explainer or Instagram Reel; not TikTok-native",
+            "0": "Not a video script; just written text"
+          }
+        },
+        {
+          "criterion": "Hook & Retention",
+          "weight": 0.3,
+          "scoring": {
+            "5": "First 3 seconds are a powerful hook (pattern interrupt, bold claim, relatable scenario); script maintains momentum throughout; high predicted completion rate",
+            "3": "Decent hook but middle section loses momentum; retention might drop",
+            "1": "Weak hook; viewer likely swipes away in first 3 seconds",
+            "0": "No hook; starts with generic intro"
+          }
+        },
+        {
+          "criterion": "Audience Fit",
+          "weight": 0.2,
+          "scoring": {
+            "5": "Language, examples, and humor resonate with Gen Z (18-25); uses relatable scenarios (rent, student loans, going out); avoids condescending or overly formal tone",
+            "3": "Generally appropriate but tone feels slightly off for Gen Z",
+            "1": "Tone is too formal, too corporate, or talks down to the audience",
+            "0": "Completely misses the audience"
+          }
+        },
+        {
+          "criterion": "Production Notes",
+          "weight": 0.2,
+          "scoring": {
+            "5": "Includes specific text overlay suggestions per scene, trending sound/audio recommendation, hashtags (3-5, niche + trending), and CTA (follow, comment, save)",
+            "3": "Some production notes present but incomplete",
+            "1": "Minimal or no production notes",
+            "0": "No production guidance at all"
+          }
+        }
+      ],
+      "expectedScoreWithout": 25,
+      "expectedScoreWith": 70
+    },
+    {
+      "id": "bench-med-03",
+      "difficulty": "medium",
+      "description": "Create an Instagram carousel concept with strategic hashtags",
+      "input": "Design an Instagram carousel (8-10 slides) for a SaaS startup's account on the topic '7 Signs Your Startup Needs to Invest in DevOps'. Target audience: startup CTOs and technical co-founders. Provide the text content for each slide, hashtag strategy, and posting time recommendation.",
+      "rubric": [
+        {
+          "criterion": "Carousel Structure",
+          "weight": 0.3,
+          "scoring": {
+            "5": "8-10 slides with clear structure: cover slide (bold hook), context slide, 7 sign slides (one per slide, concise), CTA slide; each slide has one focused takeaway; readable at mobile scale",
+            "3": "Slide count and structure are acceptable but some slides are too dense or structure is unclear",
+            "1": "Poor structure; multiple points per slide; no clear flow",
+            "0": "Not a carousel format; just a text list"
+          }
+        },
+        {
+          "criterion": "Content Quality",
+          "weight": 0.3,
+          "scoring": {
+            "5": "Each sign is specific, actionable, and resonates with startup CTOs; uses concrete examples or scenarios; builds from obvious to non-obvious signs; professional but engaging tone",
+            "3": "Content is relevant but generic; signs could apply to any company, not startup-specific",
+            "1": "Vague or irrelevant points; doesn't demonstrate DevOps expertise",
+            "0": "Content is off-topic or inaccurate"
+          }
+        },
+        {
+          "criterion": "Visual Direction",
+          "weight": 0.15,
+          "scoring": {
+            "5": "Includes text formatting suggestions (font size, emphasis), slide layout notes, and brand consistency guidance; content is designed for visual consumption",
+            "3": "Some visual notes but minimal; content relies heavily on text",
+            "1": "No visual direction; pure text content",
+            "0": "Visual suggestions are inappropriate for Instagram"
+          }
+        },
+        {
+          "criterion": "Hashtag & Timing",
+          "weight": 0.25,
+          "scoring": {
+            "5": "3-5 hashtags following relevance pyramid (mix of broad #StartupLife and niche #DevOpsCulture); posting time with timezone and day-of-week recommendation; rationale provided",
+            "3": "Hashtags and timing present but generic or not optimized",
+            "1": "Missing hashtags or timing recommendation",
+            "0": "No hashtags and no timing"
+          }
+        }
+      ],
+      "expectedScoreWithout": 25,
+      "expectedScoreWith": 70
+    },
+    {
+      "id": "bench-med-04",
+      "difficulty": "medium",
+      "description": "Create content with engagement prediction and A/B variant",
+      "input": "Create a Twitter/X tweet promoting a free webinar on 'How to Land Your First Developer Advocate Role'. Target audience: developers interested in DevRel. Provide the main tweet, an A/B test variant with a different hook, engagement prediction scores for both, and timing recommendation. Include hashtags.",
+      "rubric": [
+        {
+          "criterion": "Tweet Quality",
+          "weight": 0.3,
+          "scoring": {
+            "5": "Both tweet variants are under 280 chars; different hooks (e.g., one question-based, one data-driven); both feel natural and compelling; proper Twitter formatting",
+            "3": "Two variants provided but hooks are too similar or one feels forced",
+            "1": "Only one tweet or variants are nearly identical",
+            "0": "Tweets exceed character limit or are poorly formatted"
+          }
+        },
+        {
+          "criterion": "Engagement Prediction",
+          "weight": 0.3,
+          "scoring": {
+            "5": "Scores both variants on hook strength, value delivery, format alignment, CTA clarity, and algorithmic fit (1-5 each); explains scoring rationale; predicts which variant will perform better and why",
+            "3": "Some scoring provided but incomplete dimensions or missing rationale",
+            "1": "Vague prediction without structured scoring",
+            "0": "No engagement prediction"
+          }
+        },
+        {
+          "criterion": "Audience Targeting",
+          "weight": 0.2,
+          "scoring": {
+            "5": "Content speaks directly to developers curious about DevRel; uses language and pain points familiar to this audience (coding + communication, community building, career transition)",
+            "3": "Generally relevant but could target any career webinar",
+            "1": "Doesn't speak to the developer-to-DevRel audience specifically",
+            "0": "Wrong audience entirely"
+          }
+        },
+        {
+          "criterion": "Hashtags & Timing",
+          "weight": 0.2,
+          "scoring": {
+            "5": "1-2 relevant hashtags per variant (DevRel, developer community); specific timing recommendation with timezone and rationale",
+            "3": "Hashtags and timing present but not optimized for the developer audience",
+            "1": "Generic or missing",
+            "0": "No hashtags or timing"
+          }
+        }
+      ],
+      "expectedScoreWithout": 30,
+      "expectedScoreWith": 70
+    },
+    {
+      "id": "bench-hard-01",
+      "difficulty": "hard",
+      "description": "Full multi-platform content strategy for a product launch",
+      "input": "We're launching a new AI code review tool called 'ReviewBot' next Tuesday. Create a coordinated launch day content plan across all four platforms (Twitter/X, LinkedIn, Instagram, TikTok). For each platform, provide: the full post/script content, hashtags, exact posting time with timezone, and media suggestions. The target audience is software engineering teams at mid-size companies (50-500 employees). Our key differentiators: 1) Reviews PRs in under 60 seconds, 2) Learns team-specific coding standards, 3) Reduces code review bottlenecks by 70%. The tone should be confident but not hype-driven.",
+      "rubric": [
+        {
+          "criterion": "Cross-Platform Strategy",
+          "weight": 0.25,
+          "scoring": {
+            "5": "All 4 platforms covered with clearly differentiated content; posting times are staggered strategically throughout launch day; each platform leverages its unique strengths; coherent narrative across platforms without redundancy",
+            "3": "All 4 platforms covered but content feels repetitive; timing is not strategically staggered",
+            "1": "Only 2-3 platforms covered or content is essentially the same across platforms",
+            "0": "Only 1 platform or cross-posted identical content"
+          }
+        },
+        {
+          "criterion": "Content Quality Per Platform",
+          "weight": 0.3,
+          "scoring": {
+            "5": "Each platform's content is native: Twitter thread with quotable stats, LinkedIn thought-leadership post, Instagram visual-first carousel concept, TikTok demo-style script; all within platform limits; strong hooks on every platform",
+            "3": "Content is adequate but not optimized for each platform's native format",
+            "1": "Content feels generic across platforms; not leveraging platform-specific formats",
+            "0": "Content violates platform norms or exceeds limits"
+          }
+        },
+        {
+          "criterion": "Launch Day Coordination",
+          "weight": 0.2,
+          "scoring": {
+            "5": "Clear posting schedule with specific times per platform; considers timezone coverage for global audience; accounts for algorithm peak times; sequence creates momentum throughout the day",
+            "3": "Timing provided but not strategically sequenced",
+            "1": "Vague timing or all posts at the same time",
+            "0": "No timing coordination"
+          }
+        },
+        {
+          "criterion": "Value Proposition Communication",
+          "weight": 0.25,
+          "scoring": {
+            "5": "All 3 differentiators are communicated across the campaign; each platform highlights different angles; data points (60 sec, 70% reduction) are used effectively without feeling repetitive; tone is confident but grounded",
+            "3": "Key differentiators mentioned but not strategically distributed; some repetition",
+            "1": "Only 1-2 differentiators covered; feels like a generic product launch",
+            "0": "Value proposition unclear or missing"
+          }
+        }
+      ],
+      "expectedScoreWithout": 20,
+      "expectedScoreWith": 65
+    },
+    {
+      "id": "bench-hard-02",
+      "difficulty": "hard",
+      "description": "Create a content series plan with audience growth strategy",
+      "input": "Design a 5-part LinkedIn content series called 'The Uncomfortable Truths About Engineering Management' for an engineering leader building their personal brand. The series should be posted over 5 consecutive weekdays (Monday-Friday). For each installment, provide: the full post text (1,200-1,500 chars), hashtags, posting time, and explain how each post builds on the previous one. Each post should end with a teaser for the next day's post. Also provide an engagement prediction for the overall series and explain why this series format drives follower growth.",
+      "rubric": [
+        {
+          "criterion": "Series Coherence",
+          "weight": 0.25,
+          "scoring": {
+            "5": "5 posts form a clear narrative arc; each post builds on the previous; teasers create anticipation; topics progress from accessible to deep; series title and numbering are consistent",
+            "3": "5 posts on related topics but weak connective tissue between them; teasers feel forced",
+            "1": "Posts are standalone with no series feel; could be published in any order",
+            "0": "Posts are unrelated or series structure is absent"
+          }
+        },
+        {
+          "criterion": "Individual Post Quality",
+          "weight": 0.3,
+          "scoring": {
+            "5": "Each post is 1,200-1,500 chars; strong hook; single-sentence paragraphs; personal/vulnerable tone matching 'uncomfortable truths' theme; specific examples not generic advice; CTAs that drive comments",
+            "3": "Posts are adequate LinkedIn content but don't fully deliver on the 'uncomfortable truths' promise",
+            "1": "Posts are generic management advice without the edge the series title promises",
+            "0": "Posts are poorly formatted or violate LinkedIn norms"
+          }
+        },
+        {
+          "criterion": "Growth Strategy",
+          "weight": 0.2,
+          "scoring": {
+            "5": "Explains why the series format drives follower growth (anticipation, returning viewers, algorithm rewards consistency); engagement prediction with scoring breakdown for the series; identifies which post will likely perform best and why",
+            "3": "Some growth strategy explanation but lacks depth or specificity",
+            "1": "Minimal strategy explanation; no engagement prediction",
+            "0": "No growth strategy provided"
+          }
+        },
+        {
+          "criterion": "Scheduling & Hashtags",
+          "weight": 0.25,
+          "scoring": {
+            "5": "Specific posting times for each day (Mon-Fri) with timezone; times vary slightly based on content type; 3-5 consistent but topic-adapted hashtags per post; mix of series-branded and topic tags",
+            "3": "Timing and hashtags provided but identical across all posts or not optimized",
+            "1": "Vague timing; inconsistent or missing hashtags",
+            "0": "No timing or hashtag plan"
+          }
+        }
+      ],
+      "expectedScoreWithout": 15,
+      "expectedScoreWith": 60
+    },
+    {
+      "id": "bench-hard-03",
+      "difficulty": "hard",
+      "description": "Adapt sensitive/complex topic for social media with tone management",
+      "input": "A cybersecurity company needs to post about a major data breach affecting 50 million users of a competitor's platform. Create content for Twitter/X (a thread explaining the breach and lessons learned) and LinkedIn (a thought-leadership post on what this means for the industry). The tone must be: informative and authoritative, NOT opportunistic or fear-mongering; empathetic toward affected users; educational about prevention without being preachy; subtly positioning the company as knowledgeable without exploiting the situation. Include hashtags, timing, and engagement predictions. Note any content that should be avoided.",
+      "rubric": [
+        {
+          "criterion": "Tone Management",
+          "weight": 0.35,
+          "scoring": {
+            "5": "Tone is precisely calibrated: authoritative but empathetic; educational without being preachy; positions expertise without exploiting the breach; acknowledges affected users; avoids schadenfreude or competitive jabs",
+            "3": "Generally appropriate tone but slips into mild opportunism or fear-mongering in places",
+            "1": "Tone is off — either too promotional, too alarmist, or insensitive",
+            "0": "Tone is exploitative, fear-mongering, or clearly self-serving"
+          }
+        },
+        {
+          "criterion": "Content Quality",
+          "weight": 0.25,
+          "scoring": {
+            "5": "Thread and post provide genuine educational value; explain the breach clearly; offer actionable prevention lessons; include what-to-avoid guidance; both pieces stand alone as valuable content",
+            "3": "Content is informative but surface-level; prevention advice is generic",
+            "1": "Content is primarily about the company, not education",
+            "0": "Content is misleading, inaccurate, or purely promotional"
+          }
+        },
+        {
+          "criterion": "Platform Differentiation",
+          "weight": 0.2,
+          "scoring": {
+            "5": "Twitter thread is concise, factual, and structured for quick consumption; LinkedIn post is deeper, more reflective, with industry-level analysis; each leverages platform strengths for the sensitive topic",
+            "3": "Some differentiation but both platforms cover the same ground in similar ways",
+            "1": "Minimal differentiation; content is interchangeable",
+            "0": "Same content on both platforms"
+          }
+        },
+        {
+          "criterion": "Risk Awareness",
+          "weight": 0.2,
+          "scoring": {
+            "5": "Explicitly notes content to avoid (naming specific victims, speculating on attack vectors without evidence, using breach images, competitive attacks); timing recommendation accounts for news cycle sensitivity; hashtags avoid trending exploitation tags",
+            "3": "Some risk awareness but incomplete; misses some potential pitfalls",
+            "1": "Minimal risk awareness; content could backfire",
+            "0": "No risk awareness; content is reckless"
+          }
+        }
+      ],
+      "expectedScoreWithout": 20,
+      "expectedScoreWith": 60
+    }
+  ]
+}

package/tests/smoke.json

@@ -0,0 +1,64 @@
+{
+  "version": "0.0.1",
+  "timeout": 60,
+  "tasks": [
+    {
+      "id": "smoke-01",
+      "description": "Create a LinkedIn post about a product launch with hashtags and timing recommendation",
+      "input": "Create a LinkedIn post announcing the launch of our new AI-powered project management tool called 'FlowState'. The target audience is tech startup founders and engineering managers. Highlight that it reduces meeting time by 40% through automated standups and async decision-making. Include appropriate hashtags and recommend the best time to post for a US audience.",
+      "rubric": [
+        {
+          "criterion": "Platform Adaptation",
+          "weight": 0.25,
+          "scoring": {
+            "5": "Content is unmistakably LinkedIn-native: professional tone, paragraph breaks, 1,200-1,500 characters, 'see more' hook, no Twitter/Instagram-style formatting",
+            "3": "Reasonable LinkedIn post but could work on other platforms without much change; generic professional tone",
+            "1": "Content reads like a press release or generic announcement, not platform-adapted",
+            "0": "Content violates LinkedIn norms (too casual, too short, or formatted for another platform)"
+          }
+        },
+        {
+          "criterion": "Hook Quality",
+          "weight": 0.25,
+          "scoring": {
+            "5": "Opening line is a scroll-stopping hook (data-driven, contrarian, or curiosity-driven) that compels readers to click 'see more'; specific to the product's value proposition",
+            "3": "Decent opening but generic ('Excited to announce...'); doesn't maximize curiosity",
+            "1": "Weak or missing hook; post starts with company name or bland statement",
+            "0": "No discernible hook; wall of text from the start"
+          }
+        },
+        {
+          "criterion": "Hashtag Strategy",
+          "weight": 0.2,
+          "scoring": {
+            "5": "3-5 relevant hashtags following the relevance pyramid (1 broad + 2-3 niche + optional branded); placed at end of post; CamelCase formatting",
+            "3": "Hashtags present but count is off, or some are irrelevant to the content",
+            "1": "Too many or too few hashtags; all broad or all niche; no strategic mix",
+            "0": "No hashtags or completely irrelevant hashtag spam"
+          }
+        },
+        {
+          "criterion": "Timing & Engagement",
+          "weight": 0.15,
+          "scoring": {
+            "5": "Specific posting time recommendation with timezone context for US audience; includes day-of-week recommendation; rationale based on LinkedIn engagement patterns",
+            "3": "General timing recommendation ('post in the morning') without specifics",
+            "1": "Vague or missing timing recommendation",
+            "0": "No timing recommendation provided"
+          }
+        },
+        {
+          "criterion": "CTA & Value Delivery",
+          "weight": 0.15,
+          "scoring": {
+            "5": "Clear, low-friction CTA appropriate to LinkedIn (comment-driving question, 'share with your team', link in comments note); value proposition (40% meeting reduction) is prominent and compelling",
+            "3": "CTA present but generic ('check it out'); value proposition mentioned but not highlighted",
+            "1": "Weak or missing CTA; value proposition buried",
+            "0": "No CTA; reads as pure self-promotion without audience value"
+          }
+        }
+      ],
+      "passThreshold": 60
+    }
+  ]
+}