Skill: hughtan93-dev/hughtan93-social-media-manager (version 1.0.0)

# SKILL.md - social-media-manager ## Metadata ```yaml name: social-media-manager-xiaoxing description: AI-powered social media management assistant for content creation, scheduling, and analytics version: 2.0.0 author: Xiao Xing tags: [social-media, content, marketing, automation, twitter, instagram, linkedin, facebook] ``` ## Overview Social Media Manager is a comprehensive AI-powered assistant that helps users manage their social media presence effectively. It can generate engaging content, research hashtags, plan posting schedules, analyze engagement metrics, and optimize for each platform's unique requirements. ## Capabilities ### 1. Content Generation - Generate social media posts for various platforms - Adapt tone and style to match brand voice - Create platform-specific content (Twitter threads, LinkedIn posts, Instagram captions) - Write compelling headlines and hooks - Repurpose content across platforms ### 2. Hashtag Research - Suggest relevant trending hashtags - Create branded hashtag strategies - Optimize hashtag density per platform - Generate hashtag bundles by niche/topic ### 3. Content Calendar - Plan content themes by week/month - Suggest optimal posting times per platform - Coordinate multi-platform campaigns - Track content pillars and themes ### 4. Engagement Analysis - Analyze post performance metrics - Suggest improvements based on engagement data - Identify best-performing content types - Benchmark against competitors ### 5. Platform-Specific Optimization - **Twitter/X**: Thread creation, character limits (280), GIF support, quote tweets - **Instagram**: Caption formatting, story ideas, Reel descriptions, carousel posts - **LinkedIn**: Professional tone, article suggestions, document uploads - **Facebook**: Community engagement, event promotion, group posting --- ## Content Generation Prompts by Platform ### Twitter/X Prompts **Thread Opener:** ``` Create a Twitter thread about [TOPIC]. Include: - A compelling hook (first tweet must grab attention in first 50 chars) - 5-7 substantive tweets expanding on the topic - A strong CTA in the final tweet - 2-3 relevant hashtags distributed naturally Tone: [professional/casual/humorous/inspirational] Brand voice: [describe your brand voice] ``` **Single Tweet:** ``` Write a single impactful tweet about [TOPIC]: - Max 280 characters - Include a hook in first 30 characters - Add value or emotion - End with 1-2 relevant hashtags or a CTA Tone: [specify] ``` **Example Thread:** ``` Topic: 5 AI Tools That Will Save You 10 Hours This Week Thread structure: 1/5 🚨 Stop wasting time on repetitive tasks. Here are 5 AI tools that changed my workflow: 2/5 1. @NotionAI - Writing and summarization 3/5 2. @Copy.ai - Marketing copy 4/5 3. @Midjourney - Visual content creation 5/5 Which one are you trying first? Drop your pick in the comments 👇 #AITools #Productivity #TechTips ``` ### Instagram Prompts **Post Caption:** ``` Create an Instagram caption for [CONTENT/VISUAL]: - Hook: 1-2 lines that stop the scroll - Body: 2-3 paragraphs telling a story or sharing value - CTA: Clear call-to-action (save, comment, share) - Hashtags: 5-15 relevant tags (mix of popular and niche) Brand aesthetic: [describe] Tone: [specify] ``` **Carousel Post:** ``` Design a carousel post about [TOPIC]: - Slide 1: Hook/Title - Slides 2-8: Content points (one per slide) - Slide 9: CTA/Summary - Each slide: Visual description + caption text Format: Educational/Entertainment/Behind-the-scenes ``` **Story Ideas:** ``` Generate 5 Instagram Story ideas for [BRAND/TOPIC]: - Mix of: poll, quiz, slider, question sticker, countdown - Each story: hook + interactive element + CTA ``` **Reel Description:** ``` Create a Reel description for [VIDEO CONTENT]: - First 3 lines: Hook (show up in feed) - Lines 4-10: Context/value proposition - CTA: Save, share, or comment - Hashtags: 3-5 relevant tags ``` ### LinkedIn Prompts **Professional Post:** ``` Write a LinkedIn post about [TOPIC]: - Opening: Personal story or bold statement - Body: 2-4 paragraphs with insights - Ending: Thought-provoking question or CTA - Length: 700-1500 characters ideal Tone: Professional, authentic, thought-leadership Industry: [specify] ``` **Article Outline:** ``` Create a LinkedIn article outline about [TOPIC]: - Title: Compelling, keyword-rich - Introduction: Hook + what reader will learn - 5-7 main points with subheadings - Conclusion: Key takeaways + CTA Target length: 1500-3000 words ``` **Company Update:** ``` Write a company update post: - Announce: [product/feature/milestone] - Why it matters: Benefit to audience - Quote: CEO or team member - CTA: Link to learn more Format: Professional, celebratory ``` ### Facebook Prompts **Post:** ``` Create a Facebook post for [TOPIC]: - Length: 80-200 words for reach - Hook: First 40 characters - Content: Conversational, community-focused - CTA: Comment, share, or visit link Tone: Friendly, community-oriented ``` **Event Promotion:** ``` Write a Facebook event post: - Event: [name, date, time, location] - Hook: What's the value of attending? - Details: Key information - CTA: RSVP link Format: Event announcement ``` --- ## Hashtag Generation Methods ### Method 1: Niche-Based Generation ``` Generate 20 hashtags for [NICHE/INDUSTRY]: - Top 5: Broad reach hashtags (1M+ posts) - Top 10: Medium reach (100K-1M posts) - Top 5: Niche hashtags (<100K posts) - Include: 1-2 branded hashtags ``` ### Method 2: Trending + Evergreen Mix ``` Create hashtag bundle for [TOPIC]: - 3 trending hashtags (currently viral) - 5 evergreen hashtags (consistent engagement) - 2 niche-specific hashtags - 1 branded hashtag ``` ### Method 3: Competitor Analysis ``` Research hashtags used by [COMPETITOR/INFLUENCER]: - Extract their top 20 hashtags - Identify patterns and themes - Suggest 10 alternative hashtags in same niche ``` ### Hashtag Best Practices by Platform | Platform | Optimal Count | Best Placement | Tips | |----------|---------------|----------------|------| | Twitter | 1-3 | End of tweet | Mix broad + niche | | Instagram | 5-15 | Caption end + first comment | 30 max limit | | LinkedIn | 3-5 | End of post | Industry-specific | | Facebook | 1-3 | End of post | Avoid over-tagging | --- ## Content Calendar Templates ### Weekly Content Plan | Day | Theme | Platform Focus | Content Type | |-----|-------|----------------|--------------| | Monday | Motivation | LinkedIn, Twitter | Quote, goals | | Tuesday | Educational | LinkedIn, Instagram | Tips, how-to | | Wednesday | Product/Service | All platforms | Feature highlight | | Thursday | Community | Facebook, Instagram | User stories, UGC | | Friday | Engagement | Twitter, Instagram | Poll, question, fun | | Saturday | Behind-the-Scenes | Instagram, Facebook | BTS, team, culture | | Sunday | Curated/Planning | All | Repurpose, plan | ### Monthly Content Themes **Example: Tech/SaaS Month** ``` Week 1: Product Features & Updates Week 2: Educational Content & Tips Week 3: Customer Success Stories Week 4: Industry Trends & Thought Leadership ``` **Example: E-commerce Month** ``` Week 1: New Product Launches Week 2: How-to Use/Style Guides Week 3: Customer Reviews/Testimonials Week 4: Special Offers/Behind-the-Scenes ``` ### Optimal Posting Times (General) | Platform | Best Times (EST) | Worst Times | |----------|------------------|-------------| | Twitter | 9am, 12pm, 5pm | 11pm-5am | | Instagram | 11am, 2pm, 7pm | 11pm-5am | | LinkedIn | 8am, 10am, 12pm | 6pm-6am | | Facebook | 9am, 1pm, 4pm | 12am-6am | --- ## Engagement Analysis Framework ### Key Metrics by Platform **Twitter/X:** - Impressions - Engagement rate (engagements/impressions) - Retweets, Likes, Replies - Follows from tweet - Link clicks **Instagram:** - Reach - Engagement rate - Saves - Shares - Profile visits **LinkedIn:** - Impressions - Engagement rate - Click-through rate - Comments - Reposts **Facebook:** - Reach - Engagement rate - Shares - Comments - Page likes ### Engagement Analysis Prompt ``` Analyze [POST] performance: - Metrics: [list actual numbers] - Compare to: Industry average / Previous posts - Strengths: What worked well - Weaknesses: What underperformed - Recommendations: 3-5 specific improvements ``` ### Content Performance Checklist - [ ] Hook captures attention in first 2 seconds - [ ] Value proposition is clear - [ ] Visual is high-quality and relevant - [ ] CTA is specific and actionable - [ ] Hashtags are relevant (not spammy) - [ ] Timing aligns with audience activity - [ ] Format matches platform norms --- ## Configuration Configure your preferences in a `config.json` file: ```json { "platforms": ["twitter", "instagram", "linkedin", "facebook"], "brand": { "name": "Your Brand", "voice": "professional|casual|humorous|inspirational", "colors": ["#hex1", "#hex2"], "hashtags": ["#brand1", "#brand2"] }, "posting": { "frequency": "daily|3x/week|weekly", "times": { "twitter": ["09:00", "12:00", "17:00"], "instagram": ["11:00", "14:00", "19:00"], "linkedin": ["08:00", "10:00", "12:00"], "facebook": ["09:00", "13:00", "16:00"] } }, "audience": { "demographics": "age, location, interests", "goals": "brand awareness, lead generation, community" } } ``` ## Scripts Available - **scripts/post_generator.py** - Generate platform-specific posts - **scripts/hashtag_tool.py** - Generate and research hashtags - **scripts/calendar_planner.py** - Plan content schedules ## References - **references/platform_guidelines.md** - Platform-specific posting rules - **references/best_practices.md** - Content strategy tips - **references/api_reference.md** - API documentation ## Notes - Always comply with platform terms of service - Maintain consistent brand identity - Engage with comments and messages promptly - Track competitors and industry trends - Test different posting times for your specific audience - Repurpose content across platforms with appropriate formatting

path: assets/example_asset.txt
content: # Example Asset File

This placeholder represents where asset files would be stored.
Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed.

Asset files are NOT intended to be loaded into context, but rather used within
the output Claude produces.

Example asset files from other skills:
- Brand guidelines: logo.png, slides_template.pptx
- Frontend builder: hello-world/ directory with HTML/React boilerplate
- Typography: custom-font.ttf, font-family.woff2
- Data: sample_data.csv, test_dataset.json

## Common Asset Types

- Templates: .pptx, .docx, boilerplate directories
- Images: .png, .jpg, .svg, .gif
- Fonts: .ttf, .otf, .woff, .woff2
- Boilerplate code: Project directories, starter files
- Icons: .ico, .svg
- Data files: .csv, .json, .xml, .yaml

Note: This is a text placeholder. Actual assets can be any file type.


path: references/api_reference.md
content: # Reference Documentation for Social Media Manager

This is a placeholder for detailed reference documentation.
Replace with actual reference content or delete if not needed.

Example real reference docs from other skills:
- product-management/references/communication.md - Comprehensive guide for status updates
- product-management/references/context_building.md - Deep-dive on gathering context
- bigquery/references/ - API references and query examples

## When Reference Docs Are Useful

Reference docs are ideal for:
- Comprehensive API documentation
- Detailed workflow guides
- Complex multi-step processes
- Information too lengthy for main SKILL.md
- Content that's only needed for specific use cases

## Structure Suggestions

### API Reference Example
- Overview
- Authentication
- Endpoints with examples
- Error codes
- Rate limits

### Workflow Guide Example
- Prerequisites
- Step-by-step instructions
- Common patterns
- Troubleshooting
- Best practices


path: references/best_practices.md
content: # Social Media Best Practices - Content Strategy Tips

## Content Strategy Fundamentals

### The 80/20 Rule
- **80% Value**: Educational, entertaining, inspiring content
- **20% Promotion**: Product/service promotion
- Balance builds trust before selling

### Content Pillars
Establish 3-5 content pillars:
1. **Educational**: Tips, how-tos, tutorials
2. **Inspirational**: Motivation, success stories
3. **Entertainment**: Memes, fun facts, behind-the-scenes
4. **Promotional**: Products, services, offers
5. **Community**: UGC, questions, polls

---

## Content Creation Tips

### Writing Hooks That Work
```
Before: "Here are 5 tips for better productivity"
After: "I tried 5 productivity hacks for 30 days - here's what happened"

Before: "Our new feature is launching"
After: "We spent 6 months building this feature. Here's why it almost didn't happen."

Before: "Tips for better marketing"
After: "99% of businesses make this marketing mistake"
```

### Creating Scroll-Stopping Headlines
- Use numbers ("7 ways...", "5 reasons...")
- Create curiosity gaps
- Make bold claims
- Use power words: Secret, Ultimate, Proven, Essential
- Address pain points directly

### Call-to-Actions That Convert
- **Save-worthy**: "Save this for later!"
- **Comment-driven**: "What's your take? Drop it below"
- **Share-friendly**: "Tag someone who needs to see this"
- **Question-based**: "Which one resonates with you?"

---

## Platform-Specific Tips

### Twitter/X
- Tweet when your audience is active (analyze your metrics)
- Engage in conversations, don't just broadcast
- Use threads for complex topics
- Retweet with comment adds value
- Reply to others to build relationships

### Instagram
- Stories = daily presence (post 3-5 daily)
- Reels = reach (create weekly)
- Carousels = saves (educational content)
- Live = engagement (weekly)
- DMs = relationships (respond to all)

### LinkedIn
- Personal brand > Company page
- Document posts perform well
- First 3 lines matter most
- Comments drive more reach than posts
- Connect with purpose (not just numbers)

### Facebook
- Groups > Page (for community)
- Video > Images > Links
- Questions drive comments
- Respond to ALL comments
- Post when fans are online

---

## Engagement Best Practices

### Responding to Comments
- Respond within 1-2 hours
- Be personal, not generic
- Ask follow-up questions
- Add value to the conversation
- Show personality

### Building Community
- Ask questions regularly
- Feature user content
- Celebrate community members
- Host giveaways/contests
- Create专属 hashtags

### Handling Negative Feedback
- Don't delete (unless abusive)
- Respond professionally
- Take it offline when needed
- Learn from criticism
- Thank them for feedback

---

## Hashtag Strategy

### Finding Right Hashtags
1. Check competitors' hashtags
2. Use platform's suggested tags
3. Research niche-specific tags
4. Mix broad + medium + niche
5. Track performance over time

### Hashtag Formulas
```
Post engagement: [broad hashtag] + [niche hashtag] + [1 branded]

Educational: [topic] + [education] + [tips] + [learning]

Business: [industry] + [business] + [motivation] + [brand]

Location: [broad] + [location] + [niche]
```

### Platform-Specific Limits
- Twitter: 1-3 hashtags
- Instagram: 5-15 hashtags (30 max)
- LinkedIn: 3-5 hashtags
- Facebook: 1-3 hashtags

---

## Content Calendar Best Practices

### Planning Frequency
- **Monthly**: Theme + campaigns
- **Weekly**: Content pillars + themes
- **Daily**: Actual posting

### Weekly Content Mix (Example)
| Day | Content Type | Platform Focus |
|-----|--------------|----------------|
| Monday | Motivation/Goals | LinkedIn, Twitter |
| Tuesday | Educational | LinkedIn, Instagram |
| Wednesday | Product/Feature | All platforms |
| Thursday | Community/UGC | Facebook, Instagram |
| Friday | Engagement/Poll | Twitter, Instagram |
| Saturday | Behind-the-scenes | Instagram, Facebook |
| Sunday | Curated/Planning | Repurpose content |

### Batch Creating Content
- Create content in batches (1 day/week)
- Use templates for consistency
- Repurpose across platforms
- Schedule in advance
- Leave room for trending topics

---

## Analytics & Optimization

### Key Metrics to Track
- **Reach**: How many saw it
- **Engagement Rate**: Interactions/Reach
- **Follower Growth**: Net new followers
- **Click-through Rate**: Link clicks/Reach
- **Save Rate**: Saves/Reach (Instagram)

### What to Test
- Posting times
- Content formats
- Hashtag combinations
- CTA styles
- Caption lengths

### Optimization Loop
1. Post content
2. Track metrics
3. Identify top performers
4. Analyze what worked
5. Apply learnings
6. Repeat

---

## Common Mistakes to Avoid

### Content Mistakes
- ❌ Only promotional content
- ❌ Posting without clear CTA
- ❌ Ignoring comments/messages
- ❌ Inconsistent posting schedule
- ❌ Not repurposing content

### Strategy Mistakes
- ❌ Chasing vanity metrics
- ❌ Ignoring analytics
- ❌ Not defining target audience
- ❌ Trying to be everywhere at once
- ❌ Not having a brand voice

### Engagement Mistakes
- ❌ Buying followers
- ❌ Using engagement pods
- ❌ Generic responses
- ❌ Not replying to DMs
- ❌ Only responding to positive feedback

---

## Pro Tips

### Content Repurposing
- 1 long-form content = 5+ social posts
- 1 video = Reel + Story + Twitter thread
- 1 blog post = Infographic + Quotes + Carousel

### Building Personal Brand
- Share professional journey
- Be consistent with posting
- Engage with industry leaders
- Provide value freely
- Show behind-the-scenes

### Automation Best Practices
- Automate scheduling (not engagement)
- Personalize automated responses
- Maintain human touch
- Don't over-automate
- Monitor all automated actions


path: references/platform_guide.md
content: # Platform Guide - Social Media Best Practices

A comprehensive reference for optimizing your content across major social media platforms.

---

## Table of Contents
1. [Twitter/X](#twitterx)
2. [Instagram](#instagram)
3. [LinkedIn](#linkedin)
4. [Facebook](#facebook)
5. [Cross-Platform Tips](#cross-platform-tips)

---

## Twitter/X

### Platform Overview
- **Monthly Active Users:** 400M+
- **Best For:** News, updates, conversations, threads, real-time engagement
- **Algorithm:** Recency + Engagement + Relevance

### Technical Specs
| Feature | Free Account | Premium |
|---------|--------------|---------|
| Character Limit | 280 | 25,000 |
| Images per tweet | 4 | 4 |
| Videos | 2:20 max | 2:20 max |
| Hashtag limit | No strict limit | No strict limit |
| Optimal hashtags | 2-3 | 2-3 |

### Best Posting Times (Local Time)
- **Weekdays:** 9:00 AM, 12:00 PM, 5:00 PM - 6:00 PM
- **Best Days:** Tuesday, Wednesday, Thursday
- **Frequency:** 3-5 tweets/day for active accounts

### Content Strategy
1. **Threads** - Use for longer content (up to 25 posts)
2. **Polls** - High engagement driver
3. **Quote Tweets** - Add value, don't just RT
4. **Replies** - Engage within first hour

### Do's and Don'ts
✅ **DO:**
- Keep hooks in first 280 characters
- Ask questions to drive replies
- Use 1-2 relevant hashtags
- Post consistently
- Engage with replies

❌ **DON'T:**
- Tweet only links without context
- Use more than 3 hashtags
- Over-promote (keep it 80/20 ratio)
- Ignore mentions
- Be overly promotional

### Engagement Tips
- Reply to trending topics when relevant
- Use GIFs strategically
- Pin important tweets
- Embed media directly (not links)
- Cross-promote with other accounts

---

## Instagram

### Platform Overview
- **Monthly Active Users:** 2B+
- **Best For:** Visual storytelling, brand awareness, community
- **Algorithm:** Engagement + Relationships + Timeliness + Profile Searches

### Technical Specs
| Feature | Limit |
|---------|-------|
| Caption length | 2,200 characters |
| Hashtags | 30 max (optimal: 5-15) |
| Image size | 1080 x 1080 (square), 1080 x 1350 (portrait) |
| Video length | 60 seconds (feed), 15 seconds (stories) |
| Reels | 90 seconds max |

### Best Posting Times (Local Time)
- **Weekdays:** 11:00 AM - 1:00 PM, 7:00 PM - 9:00 PM
- **Best Days:** Monday, Wednesday, Thursday
- **Frequency:** 3-5 feed posts/week, daily stories

### Content Types (Best Engagement)
1. **Reels** - Highest reach potential
2. **Carousels** - Highest save rate
3. **Single Images** - Good for consistency
4. **Stories** - Daily engagement, ephemeral

### Do's and Don'ts
✅ **DO:**
- Put key info in first 125 characters
- Use line breaks for readability
- End with CTA ("Save this", "Tag a friend")
- Use relevant hashtags (mix of sizes)
- Post Stories daily

❌ **DON'T:**
- Write novels in captions
- Use broken/irrelevant hashtags
- Post too frequently (flooding)
- Ignore DMs and comments
- Use watermarked content (Reels)

### Hashtag Strategy
```
Industry (2-3): #TechNews #Innovation
Niche (3-5): #StartupTips #FounderLife  
Branded (1-2): #YourBrand
Popular (2-3): #Trending #Explore
```

### Instagram Story Best Practices
- Post 3-5 stories daily
- Use stickers (polls, questions, sliders)
- Mix content: BTS, memes, product, engagement
- Add highlights to categorize

---

## LinkedIn

### Platform Overview
- **Monthly Active Users:** 900M+
- **Best For:** B2B, professional networking, thought leadership
- **Algorithm:** Engagement + Connections + Timeliness

### Technical Specs
| Feature | Limit |
|---------|-------|
| Post length | 3,000 characters (optimal: 1,500-2,000) |
| Hashtags | 10 max (optimal: 3-5) |
| Comments | Unlimited |
| Attachments | Documents, images, videos |

### Best Posting Times (Local Time)
- **Weekdays:** 8:00 AM, 12:00 PM, 5:00 PM
- **Best Days:** Tuesday, Wednesday, Thursday
- **Frequency:** 2-5 posts/week

### Content Strategy
1. **Personal Stories** - Authenticity wins
2. **Professional Insights** - Share expertise
3. **Industry News** - Commentary adds value
4. **How-To Posts** - Educational content
5. **Milestones** - Celebrate wins

### Post Structure (High Engagement)
```
[Personal hook or question]
-
[Main content with 2-3 key points]
Use bullet points or numbered lists
-
[Call to action / Question]
"What's your experience?" 👇
[3-5 relevant hashtags]
```

### Do's and Don'ts
✅ **DO:**
- Start with a hook in first line
- Use professional yet personal tone
- Add relevant media (images, documents)
- Engage with comments within first hour
- Post consistently (2-5x/week)

❌ **DON'T:**
- Be overly salesy
- Copy-paste everywhere
- Write walls of text
- Use excessive hashtags
- Auto-post without customization

### LinkedIn Newsletter
- Weekly or bi-weekly consistent schedule
- 1,500+ words per edition
- Build subscribers organically
- Repurpose blog content

---

## Facebook

### Platform Overview
- **Monthly Active Users:** 3B+
- **Best For:** Community building, local business, brand awareness
- **Algorithm:** Friends/Family > Groups > Pages

### Technical Specs
| Feature | Limit |
|---------|-------|
| Post length | 63,206 characters |
| Hashtag limit | Facebook discourages hashtags |
| Video length | 240 minutes (up to 4GB) |
| Image size | 1,200 x 630 (recommended) |

### Best Posting Times (Local Time)
- **Weekdays:** 1:00 PM - 4:00 PM
- **Evenings:** 8:00 PM - 9:00 PM
- **Weekends:** 10:00 AM - 1:00 PM
- **Frequency:** 1-2 posts/day

### Content Strategy
1. **Native Videos** - Highest engagement (not links)
2. **Questions** - Drive comments
3. **Behind-the-scenes** - Humanizes brand
4. **User-generated content** - Social proof
5. **Events** - If applicable

### Do's and Don'ts
✅ **DO:**
- Use native video (not YouTube links)
- Ask open-ended questions
- Share authentic content
- Engage in Groups
- Keep posts conversational

❌ **DON'T:**
- Use too many hashtags (1-2 max)
- Only post links without value
- Over-promote
- Ignore comments/messages
- Buy fake engagement

### Facebook Groups
- More reach than Pages
- Build community
- Consistent engagement required
- Valuable for local/niche markets

---

## Cross-Platform Tips

### Content Repurposing Matrix
| Original | Twitter | Instagram | LinkedIn | Facebook |
|----------|---------|-----------|----------|----------|
| Blog Post | Thread | Carousel | Article | Summary + Video |
| Video | Clips | Reels | Short | Native Video |
| Podcast | Clips | Reels | Highlights | Clips |
| Customer Quote | Tweet | Post | Article | Post |

### Universal Best Practices
1. **Know your audience** - Different platforms, different personas
2. **Be consistent** - Regular posting builds algorithm favor
3. **Engage authentically** - Real interactions > automated
4. **Use analytics** - Track what works, double down
5. **Stay current** - Adapt to platform changes

### Optimal Hashtag Summary
| Platform | Optimal | Max | Style |
|----------|---------|-----|-------|
| Twitter | 2-3 | 5 | Short, punchy |
| Instagram | 5-15 | 30 | Mix of sizes |
| LinkedIn | 3-5 | 10 | Professional |
| Facebook | 1-2 | 5 | Minimal |

### Best Times Summary (Local Time)
| Platform | Best Times |
|----------|------------|
| Twitter | 9AM, 12PM, 5-6PM |
| Instagram | 11AM-1PM, 7-9PM |
| LinkedIn | 8AM, 12PM, 5PM |
| Facebook | 1-4PM, 8-9PM |

---

## Quick Reference Card

### Twitter
- Hook in 280 chars
- 2-3 hashtags
- Threads for long content
- Reply to engage

### Instagram
- Reels > Carousels > Images
- 5-15 hashtags
- Stories daily
- CTA at end

### LinkedIn
- Hook in first line
- 3-5 hashtags
- Personal + Professional
- Question to engage

### Facebook
- Native video
- 1-2 hashtags
- Conversational tone
- Questions work well

---

*Last Updated: 2026-03-15*
*Part of social-media-manager skill*


path: references/platform_guidelines.md
content: # Platform Guidelines - Social Media Posting Rules

## Twitter/X

### Posting Rules
- **Character Limit**: 280 characters (hard limit)
- **Media Limit**: Up to 4 images, 1 GIF, or 1 video per tweet
- **Link Preview**: Automatically generated, counts as ~23 characters
- **Thread Limit**: Up to 25 tweets in a thread

### Best Practices
- Use hooks in first 50 characters
- Add 1-2 relevant hashtags
- Include 1 call-to-action
- Post 3-5 times daily maximum
- Optimal times: 9am, 12pm, 5pm (your audience's timezone)

### Content Guidelines
- Be concise and punchy
- Use emojis sparingly
- Share insights, not promotions
- Engage with replies within 1 hour
- Retweet relevant content daily

### What's Not Allowed
- Spam behavior (excessive posting, automation abuse)
- Duplicate content across accounts
- Misinformation
- Harassment or hate speech
- Copyrighted content without permission

---

## Instagram

### Posting Rules
- **Caption Limit**: 2,200 characters (hashtags included)
- **Hashtag Limit**: 30 hashtags maximum
- **Image Size**: 1080 x 1080 pixels (square), 1080 x 1350 (portrait)
- **Video Length**: 60 seconds (feed), 15 seconds (stories)
- **Reel Length**: 90 seconds maximum

### Best Practices
- Write hooks in first 125 characters (visible before "more")
- Use 11 hashtags for optimal reach
- Post to stories daily
- Use 5-10 relevant hashtags in first comment
- Respond to comments within 2 hours

### Content Guidelines
- High-quality, visually consistent images
- Carousel posts for educational content
- Reels for reach (favored by algorithm)
- User-generated content builds community
- Save-worthy content drives engagement

### Engagement Rate Benchmarks
- <1%: Low
- 1-3.5%: Average
- 3.5-6%: High
- >6%: Very High

### What's Not Allowed
- Mass following/unfollowing
- Comment pods (fake engagement)
- Watermarked content
- Misleading captions
- Excessive promotional content

---

## LinkedIn

### Posting Rules
- **Post Length**: 3,000 characters maximum
- **Optimal Length**: 700-1,500 characters
- **Hashtag Limit**: 3-5 hashtags recommended
- **Document Size**: PDF up to 100MB
- **Video Length**: 10 minutes maximum

### Best Practices
- Write personal stories or insights
- Use professional, authentic tone
- Post 2-5 times per week
- Include 3 relevant hashtags at end
- Engage with comments within 4 hours

### Content Types That Work
- Personal professional stories
- Industry insights and trends
- How-to guides and tips
- Company announcements
- Employee spotlights
- Industry memes (occasionally)

### Engagement Rate Benchmarks
- <1%: Low
- 1-2%: Average
- 2-4%: High
- >4%: Very High

### What's Not Allowed
- Fake engagement or bots
- Promotional spam
- Misleading content
- Harassment
- Copyright infringement

---

## Facebook

### Posting Rules
- **Post Length**: 63,206 characters (practically unlimited)
- **Optimal Length**: 80-150 words for organic reach
- **Video Length**: 240 minutes maximum
- **Hashtag Limit**: 1-3 hashtags (optional)
- **Image Size**: 1200 x 630 pixels (link), 1080 x 1080 (image)

### Best Practices
- Post 1-2 times daily maximum
- Use community-friendly tone
- Ask questions to drive comments
- Share behind-the-scenes content
- Respond within 2 hours

### Content Guidelines
- Short, scannable posts perform best
- Native video > shared links
- Images drive engagement
- Stories for daily presence
- Events for promotions

### Engagement Rate Benchmarks
- <0.5%: Low
- 0.5-1.5%: Average
- 1.5-3.5%: High
- >3.5%: Very High

### What's Not Allowed
- Engagement bait ("like if...")
- Misleading content
- Spam behavior
- False news
- Unauthorized copyrighted content

---

## Platform Comparison

| Feature | Twitter | Instagram | LinkedIn | Facebook |
|---------|---------|-----------|----------|----------|
| Character Limit | 280 | 2,200 | 3,000 | 63K |
| Optimal Hashtags | 1-3 | 5-15 | 3-5 | 1-3 |
| Posting Frequency | 3-5/day | 1-2/day | 2-5/week | 1-2/day |
| Video Max | 2:20 | 60s/90s | 10 min | 240 min |
| Best for | News, updates | Visual, lifestyle | B2B, professional | Community |

---

## Global Platform Rules

### Content That Violates All Platforms
- Hate speech and harassment
- Violence and gore
- Spam and scams
- Misinformation
- Copyrighted material (without license)
- Privacy violations
- Sexually explicit content
- Illegal activities

### General Best Practices
1. **Consistency** > Frequency
2. **Quality** > Quantity
3. **Engage** > Broadcast
4. **Authentic** > Perfect
5. **Value** > Promotion


path: scripts/calendar_planner.py
content: #!/usr/bin/env python3
"""
Content Calendar Planner - Plan and schedule social media content
Usage:
    python calendar_planner.py --month 2026-03
    python calendar_planner.py --week 12
    python calendar_planner.py --add "Monday" "tech tip"
    python calendar_planner.py --platforms twitter instagram linkedin
"""

import argparse
import json
import sys
from datetime import datetime, timedelta
from collections import defaultdict

# Content themes by day of week
WEEKLY_THEMES = {
    "monday": {"theme": "Motivation", "focus": "Goals, fresh starts", "type": "quote, inspiration"},
    "tuesday": {"theme": "Educational", "focus": "Tips, how-to content", "type": "tutorial, tips"},
    "wednesday": {"theme": "Product/Feature", "focus": "Showcase offerings", "type": "feature, product"},
    "thursday": {"theme": "Community", "focus": "User stories, UGC", "type": "testimonial, UGC"},
    "friday": {"theme": "Engagement", "focus": "Questions, polls", "type": "poll, question, fun"},
    "saturday": {"theme": "Behind-the-Scenes", "focus": "Team, culture", "type": "BTS, team"},
    "sunday": {"theme": "Curated/Planning", "focus": "Repurpose, reflect", "type": "repurpose, recap"}
}

# Monthly content themes
MONTHLY_THEMES = {
    1: "New Year, Goals, Fresh Starts",
    2: "Love, Relationships, Community",
    3: "Spring, Growth, New Beginnings",
    4: "Spring, Nature, Renewal",
    5: "Mother's Day, Appreciation",
    6: "Summer, Vacations, Travel",
    7: "Independence, Freedom",
    8: "Back to School, Preparation",
    9: "New Season, Transitions",
    10: "Halloween, Fall, Spooky",
    11: "Gratitude, Thanksgiving",
    12: "Holiday Season, Celebration"
}

# Platform best posting times (UTC - adjust for local)
BEST_TIMES = {
    "twitter": ["09:00", "12:00", "17:00"],
    "instagram": ["11:00", "14:00", "19:00"],
    "linkedin": ["08:00", "10:00", "12:00"],
    "facebook": ["09:00", "13:00", "16:00"]
}

# Content pillars
CONTENT_PILLARS = [
    "Educational", "Entertainment", "Promotional", 
    "Community", "Behind-the-Scenes", "User Generated"
]


def generate_weekly_calendar(week: int = None, year: int = None, platforms: list = None) -> dict:
    """Generate a weekly content calendar."""
    if not year:
        year = datetime.now().year
    if not week:
        week = datetime.now().isocalendar()[1]
    
    # Get Monday of the week
    jan1 = datetime(year, 1, 1)
    monday = jan1 + timedelta(weeks=week - 1)
    monday = monday - timedelta(days=monday.weekday())
    
    calendar = {
        "week": week,
        "year": year,
        "start_date": monday.strftime("%Y-%m-%d"),
        "platforms": platforms or ["twitter", "instagram", "linkedin"],
        "posts": []
    }
    
    for day_idx, (day_name, theme_info) in enumerate(WEEKLY_THEMES.items()):
        date = monday + timedelta(days=day_idx)
        day_posts = []
        
        for platform in calendar["platforms"]:
            post = {
                "day": day_name.capitalize(),
                "date": date.strftime("%Y-%m-%d"),
                "platform": platform,
                "theme": theme_info["theme"],
                "focus": theme_info["focus"],
                "content_type": theme_info["type"],
                "best_time": BEST_TIMES.get(platform, ["12:00"])[day_idx % 3],
                "content_pillars": CONTENT_PILLARS[day_idx % len(CONTENT_PILLARS)]
            }
            day_posts.append(post)
        
        calendar["posts"].extend(day_posts)
    
    return calendar


def generate_monthly_calendar(month: int = None, year: int = None, platforms: list = None) -> dict:
    """Generate a monthly content calendar."""
    if not year:
        year = datetime.now().year
    if not month:
        month = datetime.now().month
    
    # Get first day of month
    first_day = datetime(year, month, 1)
    # Get last day of month
    if month == 12:
        last_day = datetime(year + 1, 1, 1) - timedelta(days=1)
    else:
        last_day = datetime(year, month + 1, 1) - timedelta(days=1)
    
    days_in_month = last_day.day
    
    calendar = {
        "month": month,
        "year": year,
        "month_name": first_day.strftime("%B"),
        "theme": MONTHLY_THEMES.get(month, "General Content"),
        "platforms": platforms or ["twitter", "instagram", "linkedin", "facebook"],
        "posts": [],
        "stats": {"total_posts": 0, "by_platform": {}, "by_type": defaultdict(int)}
    }
    
    for day in range(1, days_in_month + 1):
        date = datetime(year, month, day)
        day_name = date.strftime("%A").lower()
        week_num = date.isocalendar()[1]
        
        # Skip weekends for daily posting (optional)
        # if day_name in ["saturday", "sunday"]:
        #     continue
        
        theme_info = WEEKLY_THEMES.get(day_name, WEEKLY_THEMES["monday"])
        
        for platform in calendar["platforms"]:
            # Adjust frequency based on platform
            freq = {"twitter": 2, "instagram": 1, "linkedin": 1, "facebook": 1}
            posts_today = freq.get(platform, 1)
            
            for p in range(posts_today):
                post = {
                    "day": day,
                    "date": date.strftime("%Y-%m-%d"),
                    "weekday": day_name.capitalize(),
                    "platform": platform,
                    "theme": theme_info["theme"],
                    "content_type": theme_info["type"],
                    "best_time": BEST_TIMES.get(platform, ["12:00"])[p % 3],
                    "content_pillar": CONTENT_PILLARS[(day + p) % len(CONTENT_PILLARS)]
                }
                calendar["posts"].append(post)
                calendar["stats"]["total_posts"] += 1
                calendar["stats"]["by_platform"][platform] = calendar["stats"]["by_platform"].get(platform, 0) + 1
                calendar["stats"]["by_type"][theme_info["type"]] += 1
    
    return calendar


def generate_content_ideas(topic: str, num_ideas: int = 10) -> dict:
    """Generate content ideas for a topic."""
    idea_templates = [
        f"5 Tips for {topic}",
        f"How {topic} Changed My Business",
        f"The Ultimate Guide to {topic}",
        f"Common Mistakes in {topic} (And How to Fix Them)",
        f"Why {topic} Matters in 2026",
        f"{topic}: What You Need to Know",
        f"Behind the Scenes: Our {topic} Process",
        f"Customer Success: How They Used {topic}",
        f"The Future of {topic}",
        f"Q&A: Your Questions About {topic}",
        f"{topic} vs Competition: Which is Better?",
        f"7 Facts About {topic} You Didn't Know"
    ]
    
    ideas = []
    for i, template in enumerate(idea_templates[:num_ideas]):
        ideas.append({
            "id": i + 1,
            "title": template,
            "format": ["blog", "social post", "video", "infographic"][i % 4],
            "platform": ["LinkedIn", "Twitter", "Instagram", "Facebook"][i % 4],
            "estimated_engagement": ["high", "medium", "high", "medium"][i % 4]
        })
    
    return {"topic": topic, "ideas": ideas, "count": len(ideas)}


def add_custom_post(calendar: dict, day: str, content: str, platform: str = None) -> dict:
    """Add a custom post to calendar."""
    post = {
        "day": day,
        "content": content,
        "platform": platform,
        "custom": True
    }
    if "custom_posts" not in calendar:
        calendar["custom_posts"] = []
    calendar["custom_posts"].append(post)
    return calendar


def main():
    parser = argparse.ArgumentParser(description="Content Calendar Planner")
    parser.add_argument("--week", type=int, help="Week number (1-52)")
    parser.add_argument("--month", help="Month in YYYY-MM format")
    parser.add_argument("--year", type=int, help="Year")
    parser.add_argument("--platforms", nargs="+", choices=["twitter", "instagram", "linkedin", "facebook"],
                        default=["twitter", "instagram", "linkedin"])
    parser.add_argument("--ideas", help="Generate content ideas for a topic")
    parser.add_argument("--output", "-o", help="Output JSON file")
    args = parser.parse_args()

    if args.month:
        try:
            year, month = map(int, args.month.split("-"))
            result = generate_monthly_calendar(month, year, args.platforms)
        except:
            print("Error: Use YYYY-MM format for month")
            sys.exit(1)
    elif args.ideas:
        result = generate_content_ideas(args.ideas)
    else:
        result = generate_weekly_calendar(args.week, args.year, args.platforms)

    result["generated_at"] = datetime.now().isoformat()
    
    if args.output:
        with open(args.output, "w") as f:
            json.dump(result, f, indent=2)
        print(f"✓ Calendar saved to {args.output}")
    else:
        print(json.dumps(result, indent=2))

if __name__ == "__main__":
    main()


path: scripts/content_generator.py
content: #!/usr/bin/env python3
"""
Social Media Content Generator
Generate platform-specific social media posts with customizable tone and content.
"""

import argparse
import json
import random
import re
from typing import Dict, List, Optional

PLATFORM_CONFIGS = {
    "twitter": {"max_length": 280, "optimal_hashtags": 3, "best_times": ["9AM", "12PM", "5PM"]},
    "instagram": {"max_length": 2200, "optimal_hashtags": 11, "best_times": ["11AM", "7PM"]},
    "linkedin": {"max_length": 3000, "optimal_hashtags": 5, "best_times": ["8AM", "12PM", "5PM"]},
    "facebook": {"max_length": 63206, "optimal_hashtags": 2, "best_times": ["1PM", "8PM"]}
}

CONTENT_TEMPLATES = {
    "announcement": {
        "twitter": ["Big news! {announcement}", "Announcement: {announcement}"],
        "instagram": ["{announcement}\n\nWe're thrilled to share this!", "BIG NEWS! {announcement}\nLink in bio!"],
        "linkedin": ["I'm excited to announce {announcement}\n\nThis is a milestone...", "Big News! {announcement}"],
        "facebook": ["Exciting news!\n\n{announcement}\n\nStay tuned!"]
    },
    "tip": {
        "twitter": ["Quick tip: {tip}", "Pro tip: {tip}"],
        "instagram": ["Daily Tip: {tip}\n\nSave for later! #Tips"],
        "linkedin": ["Tip of the day: {tip}\n\nHere's what I learned..."],
        "facebook": ["Today's Tip: {tip}\n\nShare with friends!"]
    },
    "question": {
        "twitter": ["What's your take on {topic}?", "I'd love to hear thoughts on {topic}"],
        "instagram": ["Question for you:\n{question}\nComment below!"],
        "linkedin": ["Question: {question}\nWhat's your experience?"],
        "facebook": ["Question of the day:\n{question}\nDrop answers below!"]
    },
    "testimonial": {
        "twitter": ["Client success: {testimonial} - {name}"],
        "instagram": ["Client Love\n\"{testimonial}\"\n— {name}\n#ClientSuccess"],
        "linkedin": ["Client Success Story\n\"{testimonial}\"\n— {name}, {title}"],
        "facebook": ["Client Love\n\"{testimonial}\"\n— {name}"]
    },
    "behind_scenes": {
        "twitter": ["Behind the scenes of {topic}..."],
        "instagram": ["Behind the Scenes\nA peek into our process...\n#BTS"],
        "linkedin": ["Behind the scenes\nHere's how we approach {topic}..."],
        "facebook": ["Behind the Scenes\nA peek behind the curtain..."]
    },
    "motivation": {
        "twitter": ["{quote} — {author}"],
        "instagram": ["Daily Motivation\n\"{quote}\"\n— {author}\n#Motivation"],
        "linkedin": ["Monday Motivation\n\"{quote}\"\n— {author}\nLet's make this week count!"],
        "facebook": ["Daily Reminder\n\"{quote}\"\n— {author}\nSave this!"]
    }
}

def generate_content(platform: str, category: str, topic: str, tone: str = "casual") -> str:
    platform, category, tone = platform.lower(), category.lower().replace(" ", "_"), tone.lower()
    templates = CONTENT_TEMPLATES.get(category, CONTENT_TEMPLATES["announcement"])
    platform_templates = templates.get(platform, templates.get("twitter", [""]))
    
    data = {"topic": topic, "announcement": topic, "tip": topic, "question": f"Thoughts on {topic}?",
            "testimonial": f"Great experience with {topic}!", "content": topic, "quote": f"Success with {topic}",
            "author": "Unknown", "product": topic, "description": f"Discover {topic}", "highlight1": "Easy",
            "highlight2": "Fast", "highlight3": "Quality", "link": "link.in.bio", "name": "Customer", "title": "Client"}
    
    template = random.choice(platform_templates)
    try:
        content = template.format(**data)
    except:
        content = template.replace("{topic}", topic)
    if tone == "professional":
        content = re.sub(r'[^\w\s,.\-!?;:\'"()]', '', content)
    return content

def generate_thread(topic: str, num_tweets: int = 5) -> List[str]:
    return [
        f"🧵 {topic}: Everything you need to know (1/{num_tweets})\nLet's dive in",
        f"Point #1: Understanding {topic} is crucial because... (2/{num_tweets})",
        f"Point #2: The biggest mistake with {topic} is... (3/{num_tweets})",
        f"Point #3: Here's what actually works: (4/{num_tweets})",
        f"Key takeaways:\n• {topic} matters\n• Start small\n• Stay consistent\n\nThanks for reading! (5/{num_tweets})"
    ][:num_tweets]

def generate_calendar(theme: str = "general", days: int = 7) -> List[Dict]:
    themes = {
        "general": [
            {"day": "Monday", "type": "Motivation", "suggestion": "Inspiring quote or goal-setting post"},
            {"day": "Tuesday", "type": "Educational", "suggestion": "Share a tip or industry insight"},
            {"day": "Wednesday", "type": "Product/Service", "suggestion": "Highlight a product feature"},
            {"day": "Thursday", "type": "Social Proof", "suggestion": "Share a testimonial or success story"},
            {"day": "Friday", "type": "Behind the Scenes", "suggestion": "Show team or company culture"},
            {"day": "Saturday", "type": "User-Generated", "suggestion": "Repost community content"},
            {"day": "Sunday", "type": "Engagement", "suggestion": "Ask questions, run polls"}
        ]
    }
    return themes.get(theme, themes["general"])[:days]

def main():
    parser = argparse.ArgumentParser(description="Social Media Content Generator")
    parser.add_argument("--platform", "-p", default="twitter", choices=["twitter", "instagram", "linkedin", "facebook"])
    parser.add_argument("--category", "-c", default="announcement", choices=["announcement", "tip", "question", "testimonial", "behind_scenes", "motivation"])
    parser.add_argument("--topic", "-t", required=True)
    parser.add_argument("--tone", default="casual", choices=["professional", "casual", "humorous", "inspirational"])
    parser.add_argument("--thread", action="store_true")
    parser.add_argument("--calendar", action="store_true")
    parser.add_argument("--theme", default="general")
    parser.add_argument("--days", type=int, default=7)
    args = parser.parse_args()
    
    if args.thread:
        print(json.dumps(generate_thread(args.topic), indent=2))
    elif args.calendar:
        print(json.dumps(generate_calendar(args.theme, args.days), indent=2))
    else:
        print(generate_content(args.platform, args.category, args.topic, args.tone))

if __name__ == "__main__":
    main()


path: scripts/example.py
content: #!/usr/bin/env python3
"""
Example helper script for social-media-manager

This is a placeholder script that can be executed directly.
Replace with actual implementation or delete if not needed.

Example real scripts from other skills:
- pdf/scripts/fill_fillable_fields.py - Fills PDF form fields
- pdf/scripts/convert_pdf_to_images.py - Converts PDF pages to images
"""

def main():
    print("This is an example script for social-media-manager")
    # TODO: Add actual script logic here
    # This could be data processing, file conversion, API calls, etc.

if __name__ == "__main__":
    main()


path: scripts/hashtag_tool.py
content: #!/usr/bin/env python3
"""
Hashtag Tool - Research and generate relevant hashtags
Usage:
    python hashtag_tool.py --niche "technology"
    python hashtag_tool.py --topic "AI productivity"
    python hashtag_tool.py --generate-mix --topic "digital marketing"
"""

import argparse
import json
import random
import sys
from datetime import datetime

# Hashtag database with reach estimates
HASHTAG_DATABASE = {
    "tech": {
        "broad": [("#Tech", 150000000), ("#Technology", 100000000), ("#Innovation", 80000000)],
        "medium": [("#Startup", 30000000), ("#AI", 25000000), ("#MachineLearning", 20000000)],
        "niche": [("#TechStartup", 2000000), ("#CodingLife", 800000), ("#DeveloperLife", 600000)]
    },
    "business": {
        "broad": [("#Business", 90000000), ("#Entrepreneur", 70000000), ("#Success", 60000000)],
        "medium": [("#Leadership", 25000000), ("#Growth", 20000000), ("#Marketing", 15000000)],
        "niche": [("#StartupLife", 1200000), ("#SideHustle", 250000), ("#OnlineBusiness", 200000)]
    },
    "lifestyle": {
        "broad": [("#Lifestyle", 150000000), ("#Life", 140000000), ("#Love", 130000000)],
        "medium": [("#Inspiration", 60000000), ("#Goals", 40000000), ("#Mindset", 35000000)],
        "niche": [("#LifestyleBlog", 3000000), ("#SelfLoveJourney", 1500000), ("#DailyInspiration", 300000)]
    },
    "food": {
        "broad": [("#Food", 500000000), ("#Foodie", 200000000), ("#Yummy", 150000000)],
        "medium": [("#FoodPhotography", 50000000), ("#FoodBlog", 30000000), ("#InstaFood", 12000000)],
        "niche": [("#HomeCooking", 1200000), ("#FoodBlogger", 400000), ("#RecipeShare", 300000)]
    },
    "travel": {
        "broad": [("#Travel", 600000000), ("#Adventure", 150000000), ("#Explore", 100000000)],
        "medium": [("#TravelPhotography", 40000000), ("#TravelBlog", 25000000), ("#Vacation", 20000000)],
        "niche": [("#TravelTips", 3000000), ("#SoloTravel", 2500000), ("#HiddenGems", 400000)]
    },
    "education": {
        "broad": [("#Education", 100000000), ("#Learning", 80000000), ("#Knowledge", 60000000)],
        "medium": [("#Teacher", 25000000), ("#OnlineLearning", 12000000), ("#EdTech", 10000000)],
        "niche": [("#StudentLife", 1000000), ("#StudyGram", 600000), ("#LearnToCode", 250000)]
    },
    "marketing": {
        "broad": [("#Marketing", 50000000), ("#DigitalMarketing", 35000000), ("#SocialMedia", 30000000)],
        "medium": [("#ContentMarketing", 15000000), ("#MarketingTips", 12000000), ("#GrowthHacking", 3500000)],
        "niche": [("#DigitalMarketer", 1500000), ("#SEOTips", 300000), ("#ContentTips", 250000)]
    },
    "fitness": {
        "broad": [("#Fitness", 500000000), ("#Health", 400000000), ("#Workout", 150000000)],
        "medium": [("#FitFam", 60000000), ("#Wellness", 50000000), ("#FitnessMotivation", 40000000)],
        "niche": [("#HomeWorkout", 3000000), ("#FitnessTips", 2500000), ("#FitnessGoals", 1500000)]
    },
    "fashion": {
        "broad": [("#Fashion", 1000000000), ("#Style", 800000000), ("#Ootd", 400000000)],
        "medium": [("#FashionStyle", 60000000), ("#StreetStyle", 50000000), ("#Trends", 25000000)],
        "niche": [("#FashionTips", 3000000), ("#StyleTips", 2500000), ("#OutfitIdeas", 2000000)]
    }
}

PLATFORM_LIMITS = {
    "twitter": {"optimal": 2}, "instagram": {"optimal": 11}, 
    "linkedin": {"optimal": 3}, "facebook": {"optimal": 2}
}

KEYWORDS_MAP = {
    "tech": ["tech", "ai", "software", "code", "digital"],
    "business": ["business", "entrepreneur", "startup", "money", "marketing"],
    "lifestyle": ["life", "style", "living", "inspiration", "motivation"],
    "food": ["food", "eat", "cook", "recipe", "coffee"],
    "travel": ["travel", "trip", "vacation", "adventure", "explore"],
    "education": ["learn", "study", "education", "school", "course"],
    "marketing": ["marketing", "social media", "brand", "content", "seo"],
    "fitness": ["fitness", "workout", "gym", "health", "exercise"],
    "fashion": ["fashion", "style", "clothes", "outfit", "trend"]
}

def detect_category(topic: str) -> str:
    topic_lower = topic.lower()
    for cat, kws in KEYWORDS_MAP.items():
        for kw in kws:
            if kw in topic_lower:
                return cat
    return "tech"

def generate_mixed_bundle(niche: str, platform: str = "instagram") -> list:
    if niche not in HASHTAG_DATABASE:
        niche = "tech"
    data = HASHTAG_DATABASE[niche]
    opt = PLATFORM_LIMITS.get(platform, {"optimal": 11})["optimal"]
    broad = random.sample(data["broad"], min(2, len(data["broad"])))
    medium = random.sample(data["medium"], min(4, len(data["medium"])))
    niche_tags = random.sample(data["niche"], min(opt - 2, len(data["niche"])))
    return [h[0] for h in broad + medium + niche_tags][:opt]

def generate_trending_mix(topic: str, platform: str = "instagram") -> dict:
    category = detect_category(topic)
    bundle = generate_mixed_bundle(category, platform)
    return {"topic": topic, "category": category, "hashtags": bundle, "platform": platform}

def main():
    parser = argparse.ArgumentParser(description="Hashtag Tool")
    parser.add_argument("--niche", help="Niche category")
    parser.add_argument("--topic", help="Topic for hashtag generation")
    parser.add_argument("--platform", choices=["twitter", "instagram", "linkedin", "facebook"], default="instagram")
    parser.add_argument("--generate-mix", action="store_true", help="Generate mixed hashtag bundle")
    parser.add_argument("--output", "-o", help="Output JSON file")
    args = parser.parse_args()

    if args.niche:
        result = get_hashtags_by_niche(args.niche, args.platform)
    elif args.topic and args.generate_mix:
        result = generate_trending_mix(args.topic, args.platform)
    elif args.topic:
        result = generate_trending_mix(args.topic, args.platform)
    else:
        print("Error: Specify --niche or --topic")
        sys.exit(1)

    result["generated_at"] = datetime.now().isoformat()
    
    if args.output:
        with open(args.output, "w") as f:
            json.dump(result, f, indent=2)
        print(f"✓ Saved to {args.output}")
    else:
        print(json.dumps(result, indent=2))

def get_hashtags_by_niche(niche: str, platform: str = None) -> dict:
    niche_lower = niche.lower()
    category = None
    for key in HASHTAG_DATABASE:
        if key in niche_lower or niche_lower in key:
            category = key
            break
    if not category:
        return {"error": f"Niche '{niche}' not found"}
    data = HASHTAG_DATABASE[category]
    result = {"niche": category, "hashtags": {"broad": [h[0] for h in data["broad"]], "medium": [h[0] for h in data["medium"]], "niche": [h[0] for h in data["niche"]]}}
    if platform:
        result["recommended"] = generate_mixed_bundle(category, platform)
    return result

if __name__ == "__main__":
    main()


path: scripts/post_generator.py
content: #!/usr/bin/env python3
"""
Social Media Post Generator
Generate platform-specific posts with AI-powered content creation

Usage:
    python post_generator.py --platform twitter --topic "AI productivity"
    python post_generator.py --platform instagram --topic "coffee shop"
    python post_generator.py --linkedin --topic "leadership"
    python post_generator.py --facebook --topic "event announcement"
"""

import argparse
import json
import sys
from datetime import datetime

# Platform-specific templates and rules
PLATFORM_CONFIGS = {
    "twitter": {
        "max_length": 280,
        "optimal_length": 200,
        "hashtag_limit": 3,
        "best_times": ["09:00", "12:00", "17:00"],
        "features": ["text", "image", "gif", "video", "poll", "thread"]
    },
    "instagram": {
        "max_length": 2200,
        "optimal_length": 150,
        "hashtag_limit": 30,
        "best_times": ["11:00", "14:00", "19:00"],
        "features": ["image", "carousel", "reel", "story", "igtv"]
    },
    "linkedin": {
        "max_length": 3000,
        "optimal_length": 1200,
        "hashtag_limit": 5,
        "best_times": ["08:00", "10:00", "12:00"],
        "features": ["text", "image", "document", "video", "article"]
    },
    "facebook": {
        "max_length": 63206,
        "optimal_length": 150,
        "hashtag_limit": 3,
        "best_times": ["09:00", "13:00", "16:00"],
        "features": ["text", "image", "video", "event", "poll", "live"]
    }
}

# Content type templates
CONTENT_TEMPLATES = {
    "twitter": {
        "announcement": "📢 {announcement}\n\n{context}\n\n{cta}\n\n{hashtags}",
        "question": "💭 {question}\n\n{context}\n\nReply below! 👇\n\n{hashtags}",
        "tip": "💡 {tip_title}:\n\n{point1}\n{point2}\n{point3}\n\n{cta}\n\n{hashtags}",
        "thread": "🧵 THREAD: {topic}\n\n{intro}\n\n1/ {point1}\n\n2/ {point2}\n\n3/ {point3}\n\n{conclusion}\n\n{hashtags}"
    },
    "instagram": {
        "product": "🌟 {product_name} 🌟\n\n{description}\n\n✨ {feature1}\n✨ {feature2}\n✨ {feature3}\n\n{cta}\n\n📍 {location}\n⏰ {hours}\n\n{hashtags}",
        "lifestyle": "✨ {lifestyle_theme}\n\n{story}\n\n{cta}\n\n{hashtags}",
        "educational": "📚 {topic}\n\n{content}\n\n💾 Save for later!\n\n{hashtags}",
        "bts": "👀 Behind the scenes...\n\n{bts_content}\n\n{cta}\n\n{hashtags}"
    },
    "linkedin": {
        "thought_leadership": "I {story}\n\nHere's what I learned:\n\n→ {lesson1}\n→ {lesson2}\n→ {lesson3}\n\nWhat's your experience? Drop your thoughts below 👇\n\n{hashtags}",
        "announcement": "Excited to announce {announcement}!\n\n{context}\n\nSpecial thanks to {team/partner} for making this possible.\n\nLearn more: {link}\n\n{hashtags}",
        "education": "Here's what nobody tells you about {topic}:\n\n{point1}\n\n{point2}\n\n{point3}\n\n{years_experience} years in {industry} have taught me that {insight}.\n\nWhat would you add?\n\n{hashtags}"
    },
    "facebook": {
        "community": "{hook}\n\n{content}\n\n{question}\n\nDrop your answers below! 💬\n\n{hashtags}",
        "event": "📅 SAVE THE DATE! 📅\n\n{event_name}\n\n📆 Date: {date}\n⏰ Time: {time}\n📍 Location: {location}\n\n{description}\n\n🔗 RSVP here: {link}\n\n{hashtags}",
        "offer": "🎉 {offer_title} 🎉\n\n{offer_details}\n\n⏰ Valid until: {date}\n\n{cta}\n\n{hashtags}"
    }
}

# Hashtag bundles by category
HASHTAG_BUNDLES = {
    "tech": ["#Tech", "#Innovation", "#Technology", "#Digital", "#Future", "#Startup", "#AI", "#ML"],
    "business": ["#Business", "#Entrepreneur", "#Success", "#Motivation", "#Leadership", "#Growth"],
    "lifestyle": ["#Lifestyle", "#Life", "#Inspiration", "#Goals", "#Mindset", "#Wellness"],
    "food": ["#Food", "#Foodie", "#Yummy", "#Delicious", "#FoodPhotography", "#Eat"],
    "travel": ["#Travel", "#Adventure", "#Explore", "#Wanderlust", "#TravelGram", "#Journey"],
    "education": ["#Education", "#Learning", "#Knowledge", "#Student", "#Teacher", "#EdTech"],
    "marketing": ["#Marketing", "#DigitalMarketing", "#SocialMedia", "#Branding", "#ContentMarketing"],
    "fitness": ["#Fitness", "#Health", "#Workout", "#Gym", "#FitFam", "#Wellness"]
}


def generate_tweet(topic: str, style: str = "informative") -> dict:
    """Generate a tweet about a given topic."""
    templates = {
        "informative": f"📢 Here's what you need to know about {topic}:\n\n1. First key point about {topic}\n2. Second important insight\n3. Third actionable takeaway\n\nWhich point resonates most? Comment below 👇\n\n#Trending #{topic.replace(' ', '')} #Learn",
        "question": f"💭 Question for you about {topic}:\n\nWhat's your biggest challenge with {topic}?\n\nReply and I'll share my thoughts 👇\n\n#{topic.replace(' ', '')} #Community",
        "tip": f"💡 3 Quick Tips for {topic}:\n\n✅ Tip 1: Start with why\n✅ Tip 2: Focus on consistency\n✅ Tip 3: Measure what matters\n\nSave this for later! 🔖\n\n#{topic.replace(' ', '')} #Tips #Productivity"
    }
    content = templates.get(style, templates["informative"])
    return {
        "platform": "twitter",
        "content": content,
        "length": len(content),
        "hashtags": content.count("#"),
        "best_times": PLATFORM_CONFIGS["twitter"]["best_times"]
    }


def generate_instagram_post(topic: str, post_type: str = "product") -> dict:
    """Generate an Instagram post."""
    templates = CONTENT_TEMPLATES["instagram"]
    content = templates.get(post_type, templates["product"])
    
    # Replace placeholders
    content = content.format(
        product_name=f"✨ {topic.title()}",
        description=f"Discover the magic of {topic}!",
        feature1="Premium quality",
        feature2="Unique experience",
        feature3="Limited availability",
        cta="💬 Comment below!",
        location="📍 Your Location",
        hours="⏰ Open Daily",
        lifestyle_theme=f"Living my best {topic} life",
        story=f"Every moment with {topic} is a memory in the making.",
        cta_ig="💾 Save for later!",
        topic=f"Everything about {topic}",
        content=f"Swipe ➡️ to learn more about {topic}",
        bts_content=f"See how we create {topic}...",
        hashtags="#InstaGood #PhotoOfTheDay #Love #Beautiful #Happy #Cute #TBT #FollowMe"
    )
    
    return {
        "platform": "instagram",
        "content": content,
        "length": len(content),
        "hashtags": content.count("#"),
        "best_times": PLATFORM_CONFIGS["instagram"]["best_times"],
        "tips": "Add 5-15 hashtags in comments for better reach"
    }


def generate_linkedin_post(topic: str, post_type: str = "thought_leadership") -> dict:
    """Generate a LinkedIn post."""
    templates = CONTENT_TEMPLATES["linkedin"]
    content = templates.get(post_type, templates["thought_leadership"])
    
    content = content.format(
        story=f"just spent 5 years in the {topic} space, and here's what I've learned",
        lesson1="Lesson one about " + topic,
        lesson2="Lesson two about " + topic,
        lesson3="Lesson three about " + topic,
        announcement=f"something exciting about {topic}",
        context=f"We're thrilled to share this update about {topic}.",
        team_partner="our amazing team",
        link="Learn more →",
        topic=topic,
        point1=f"Key insight about {topic}",
        point2=f"Another perspective on {topic}",
        point3=f"Final thought on {topic}",
        years_experience="10",
        industry=topic,
        insight=f"{topic} is about consistency and patience",
        hashtags="#Professional #Career #Industry #Leadership #Growth"
    )
    
    return {
        "platform": "linkedin",
        "content": content,
        "length": len(content),
        "hashtags": content.count("#"),
        "best_times": PLATFORM_CONFIGS["linkedin"]["best_times"],
        "tips": "Write 700-1500 chars for optimal reach on LinkedIn"
    }


def generate_facebook_post(topic: str, post_type: str = "community") -> dict:
    """Generate a Facebook post."""
    templates = CONTENT_TEMPLATES["facebook"]
    content = templates.get(post_type, templates["community"])
    
    content = content.format(
        hook=f"✨ Something exciting about {topic}",
        content=f"Here's everything you need to know about {topic}",
        question=f"What's your take on {topic}?",
        event_name=f"🎉 {topic.title()} Event",
        date="This Saturday",
        time="2:00 PM",
        location="Your Venue",
        description=f"Join us for an amazing {topic} experience!",
        link="RSVP Link",
        offer_title=f"Special {topic} Offer",
        offer_details=f"Get exclusive access to {topic}!",
        cta="Click to learn more →",
        hashtags="#Community #Event #Special"
    )
    
    return {
        "platform": "facebook",
        "content": content,
        "length": len(content),
        "hashtags": content.count("#"),
        "best_times": PLATFORM_CONFIGS["facebook"]["best_times"],
        "tips": "Keep posts under 150 words for better organic reach"
    }


def generate_thread(topic: str, num_tweets: int = 5) -> dict:
    """Generate a Twitter thread."""
    tweets = []
    for i in range(num_tweets):
        if i == 0:
            tweet = f"🧵 {num_tweets}-Part Thread: {topic}\n\nI've spent years studying {topic}. Here's what I learned:\n\n1/{num_tweets}"
        elif i == num_tweets - 1:
            tweet = f"{i+1}/{num_tweets} Key takeaway: {topic} is about consistency.\n\nDid you find this useful? Like and retweet to share! 🚀\n\n#{topic.replace(' ', '')} #Thread"
        else:
            tweet = f"{i+1}/{num_tweets} {topic}:\n\nPoint {i+1} about {topic} that changed my perspective..."
        tweets.append(tweet)
    
    return {
        "platform": "twitter",
        "type": "thread",
        "tweets": tweets,
        "total_length": sum(len(t) for t in tweets),
        "best_times": PLATFORM_CONFIGS["twitter"]["best_times"]
    }


def main():
    parser = argparse.ArgumentParser(description="Social Media Post Generator")
    parser.add_argument("--platform", "-p", choices=["twitter", "instagram", "linkedin", "facebook"],
                        help="Target platform")
    parser.add_argument("--topic", "-t", required=True, help="Topic for the post")
    parser.add_argument("--type", choices=["announcement", "question", "tip", "thread", 
                                           "product", "lifestyle", "educational", "bts",
                                           "thought_leadership", "education", "community", "event", "offer"],
                        help="Type of post to generate")
    parser.add_argument("--style", choices=["informative", "question", "tip"],
                        help="Style for Twitter posts")
    parser.add_argument("--num-tweets", type=int, default=5, help="Number of tweets in a thread")
    parser.add_argument("--output", "-o", help="Output JSON file")
    
    # Convenience flags
    parser.add_argument("--twitter", action="store_true", help="Shorthand for --platform twitter")
    parser.add_argument("--instagram", action="store_true", help="Shorthand for --platform instagram")
    parser.add_argument("--linkedin", action="store_true", help="Shorthand for --platform linkedin")
    parser.add_argument("--facebook", action="store_true", help="Shorthand for --platform facebook")
    parser.add_argument("--thread", action="store_true", help="Generate a Twitter thread")
    
    args = parser.parse_args()
    
    # Determine platform
    platform = args.platform
    if not platform:
        if args.twitter or args.thread:
            platform = "twitter"
        elif args.instagram:
            platform = "instagram"
        elif args.linkedin:
            platform = "linkedin"
        elif args.facebook:
            platform = "facebook"
    
    if not platform:
        print("Error: Please specify a platform (--platform or --twitter/--instagram/--linkedin/--facebook)")
        sys.exit(1)
    
    # Generate content
    if args.thread and platform == "twitter":
        result = generate_thread(args.topic, args.num_tweets)
    elif platform == "twitter":
        result = generate_tweet(args.topic, args.style or "informative")
    elif platform == "instagram":
        result = generate_instagram_post(args.topic, args.type or "product")
    elif platform == "linkedin":
        result = generate_linkedin_post(args.topic, args.type or "thought_leadership")
    elif platform == "facebook":
        result = generate_facebook_post(args.topic, args.type or "community")
    
    result["topic"] = args.topic
    result["generated_at"] = datetime.now().isoformat()
    
    # Output
    if args.output:
        with open(args.output, "w") as f:
            json.dump(result, f, indent=2)
        print(f"✓ Post generated and saved to {args.output}")
    else:
        print(json.dumps(result, indent=2))
    
    return result


if __name__ == "__main__":
    main()


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)