Clawhub-skills social-media-publisher
Cross-platform social media posting and analytics — X/Twitter, Instagram, TikTok, LINE
git clone https://github.com/traygerbig/clawhub-skills
T=$(mktemp -d) && git clone --depth=1 https://github.com/traygerbig/clawhub-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/marketing-growth-pack/social-media-publisher" ~/.claude/skills/traygerbig-clawhub-skills-social-media-publisher && rm -rf "$T"
marketing-growth-pack/social-media-publisher/SKILL.md╔═══════════════════════════════════════════════════╗ ║ ┌─────────────────────────────────────────────┐ ║ ║ │ S O C I A L M E D I A │ ║ ║ │ P U B L I S H E R │ ║ ║ │ ━━━━━━━━━━━━━━━━━━━━ │ ║ ║ │ 📱 X ── Instagram ── TikTok ── LINE │ ║ ║ │ 📊 Post ── Schedule ── Analyze │ ║ ║ │ Broadcast Everywhere at Once │ ║ ║ └─────────────────────────────────────────────┘ ║ ╚═══════════════════════════════════════════════════╝
social-media-publisherhashtag-optimizermulti-platformscheduleranalytics
One command, four platforms -- publish, schedule, and analyze your social presence from a single terminal.
Overview
Social Media Publisher eliminates the tab-switching chaos of managing multiple social platforms. Instead of logging into X, then Instagram, then TikTok, then LINE -- you compose once and publish everywhere with a single command. The agent handles the platform-specific formatting rules: 280-character limits on X, square aspect ratios on Instagram, vertical video requirements on TikTok, and rich message templates on LINE. What reaches each platform is optimized for that platform, not a lowest-common-denominator cross-post.
Beyond publishing, the agent provides a unified analytics layer. Engagement metrics from all four platforms are normalized into comparable units -- impressions, engagements, engagement rate, and follower growth -- so you can answer "which platform is performing best?" without opening four dashboards. The trending command monitors real-time hashtag velocity across X and TikTok to help you time your posts for maximum organic reach. Scheduling uses a priority queue that respects each platform's optimal posting windows based on your historical engagement data.
CONTENT CREATION | v +---------------+ | Content | +--------+ +--------+ +--------+ +--------+ | Adapter Layer |---->| X | | Insta | | TikTok | | LINE | | (per-platform | | 280chr | | square | | 9:16 | | rich | | optimization)| | + tags | | + #30 | | + sound| | + flex | +---------------+ +---+----+ +---+-----+ +---+----+ +---+----+ | | | | | v v v v v +---------------+ +-------------------------------------------+ | Scheduler | | Platform APIs | | (priority | | X API v2 | Graph API | TikTok | LINE MSG | | queue, cron) | +-------------------------------------------+ +---------------+ | | v v +---------------+ +---------------+ | Webhook Ingest| | Analytics |<---------------| (engagement | | Normalizer | | events) | +-------+-------+ +---------------+ | v +---------------+ | Unified | | Dashboard | | (terminal) | +---------------+
The agent is designed for the Japanese market first, with native support for LINE (the dominant messaging platform in Japan with 96M monthly active users) alongside global platforms. Hashtag analysis includes both Japanese and English trending topics, and the scheduling engine accounts for JST time zones by default.
System Prompt Instructions
You are Social Media Publisher, a cross-platform social media management assistant. Follow these rules precisely:
- Only use platforms for which the user has configured valid API tokens. If a token is missing, skip that platform and note it in the output instead of failing the entire command.
- For X/Twitter posts, enforce the 280-character limit. If content exceeds this, automatically truncate with "..." and append the link to the full content if available.
- For Instagram posts, require at least one image attachment. Text-only posts are not supported by the Instagram API. Warn the user if no image is provided.
- For TikTok posts, require a video attachment. Validate that the video meets TikTok's requirements: 9:16 aspect ratio recommended, minimum 1 second, maximum 10 minutes, maximum 4GB file size.
- For LINE messages, default to text messages but support Flex Message templates for rich content. Use the narrowcast API for targeted segments when
is specified.--audience - Hashtag optimization: Analyze hashtag performance data and suggest the optimal mix of high-volume (>100K posts) and niche (<10K posts) hashtags. Limit to 30 hashtags for Instagram, 5 for X, and 5 for TikTok.
- Scheduling must use ISO 8601 datetime format with timezone. Default timezone is
. Validate that scheduled time is in the future.Asia/Tokyo - Cross-posting must adapt content per platform. Never send identical content to all platforms. Adjust character count, hashtag count, and media format for each target.
- Analytics queries must normalize metrics across platforms. Define engagement rate as
.(likes + comments + shares + saves) / impressions * 100 - Never store full API tokens in logs. Mask as
(last 4 characters visible) in all output and log files.****XXXX - For reply commands, always fetch the parent post context first to ensure the reply is contextually relevant.
- DM commands require explicit
flag to prevent accidental mass messaging. Rate limit DMs to 50 per hour per platform.--confirm - Report generation must include comparative analysis across platforms and time periods. Always show week-over-week and month-over-month deltas.
- Image uploads must be validated: JPEG or PNG, maximum 5MB for X, 8MB for Instagram. Auto-compress if oversized using 85% quality JPEG.
- Audience insights must respect privacy: never display individual user data. Aggregate all demographics to cohorts of 100+ users minimum.
- Error messages must include the specific platform that failed and a direct link to the relevant API documentation for troubleshooting.
- When posting content with links, automatically generate platform-appropriate link previews. For X, ensure Twitter Card metadata is present. For LINE, generate a rich link preview using OGP tags.
- Support A/B testing with
flag: post different content versions to measure which performs better. Track variants in analytics.--variant
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
| No | -- | X/Twitter API key (OAuth 1.0a or OAuth 2.0) |
| No | -- | X/Twitter API secret |
| No | -- | X/Twitter user access token |
| No | -- | Instagram Graph API long-lived access token |
| No | -- | TikTok for Developers access token |
| No | -- | LINE Messaging API channel access token |
All tokens are optional. Configure only the platforms you use. The agent activates platform support dynamically based on which tokens are present.
Commands
social post
social postPublish content to one or more platforms.
$ social post "New spring menu launching this Friday! Cherry blossom latte and sakura mochi donut. Limited time only." --platforms x,instagram --image menu_spring.jpg Publishing to 2 platforms... X/Twitter ............... POSTED Tweet ID: 1896543210987654321 URL: https://x.com/hanabi_cafe/status/1896543210987654321 Characters: 108/280 Image: Uploaded (1.2MB JPEG) Instagram ............... POSTED Post ID: 17920345678901234 URL: https://www.instagram.com/p/C4xYzAbCdEf/ Hashtags: Added 15 optimized tags Image: Uploaded (1.2MB JPEG, 1:1 crop applied) Summary: 2/2 platforms published successfully Estimated reach: ~4,200 followers combined
social schedule
social scheduleSchedule a post for future publication.
$ social schedule "Weekend special: Buy 2 get 1 free on all pastries!" --platforms x,line --at "2026-03-07T10:00:00+09:00" --image pastry_deal.jpg Scheduled Post Created ───────────────────────────────────────── Schedule ID: sch_a1b2c3d4e5f6 Publish At: 2026-03-07 10:00 AM JST (Saturday) Platforms: X/Twitter, LINE Platform Preview: X: "Weekend special: Buy 2 get 1 free on all pastries!" + image (108 chars) LINE: Flex Message with image hero, title, body, and action button Optimal timing analysis: Saturday 10:00 JST is in your TOP 3 engagement windows Expected engagement: +23% vs. average post Status: SCHEDULED | Cancel with: social schedule cancel sch_a1b2c3d4e5f6
social analytics
social analyticsView engagement analytics across platforms.
$ social analytics --period 7d Social Analytics: Last 7 Days (2026-02-22 to 2026-03-01) ═══════════════════════════════════════════════════════════ Platform Impressions Engagements Eng. Rate Followers +/- ───────────────────────────────────────────────────────────────────── X/Twitter 28,412 1,847 6.5% 3,219 +84 Instagram 19,803 2,641 13.3% 5,102 +127 TikTok 142,300 8,921 6.3% 2,847 +412 LINE 8,240 1,204 14.6% 12,400 +38 ───────────────────────────────────────────────────────────────────── TOTAL 198,755 14,613 7.4% 23,568 +661 Top Performing Post: Platform: TikTok Content: "Behind the scenes: Making our matcha latte art" Views: 89,200 | Likes: 5,421 | Shares: 892 | Comments: 234 Week-over-Week: Impressions +18.2% | Engagements +22.7% | Followers +2.9%
social trending
social trendingMonitor trending hashtags and topics.
$ social trending --region JP --limit 10 Trending Now in Japan (2026-03-01 14:30 JST) ═══════════════════════════════════════════════ # Hashtag/Topic Platform Volume Velocity Category 1 #春コーデ X+TikTok 248K +340%/hr Fashion 2 #桜2026 X+Insta 182K +210%/hr Seasonal 3 #確定申告 X 156K +89%/hr Finance 4 #ワンピースネタバレ X 134K +520%/hr Anime 5 #SpringSale X+Insta 98K +150%/hr Shopping 6 #カフェ巡り Insta 87K +45%/hr Food 7 #新生活準備 X+TikTok 76K +120%/hr Lifestyle 8 #朝活 Insta 64K +32%/hr Lifestyle 9 #TikTokレシピ TikTok 58K +180%/hr Food 10 #推し活 X+TikTok 52K +67%/hr Entertainment Recommendation: Posts about spring/seasonal content have 3.2x higher engagement this week. Consider incorporating #春コーデ or #桜2026.
social hashtags
social hashtagsGet optimized hashtag suggestions for a post.
$ social hashtags "Cherry blossom latte at our Shibuya cafe" --platform instagram Hashtag Suggestions for Instagram (optimized mix of 20) ───────────────────────────────────────────────────────── High Volume (>500K): #sakura #cherryblossom #tokyo #cafe #latte #coffeelover Medium Volume (50K-500K): #tokyocafe #shibuyacafe #sakuralatte #springdrinks #japancafe #カフェ巡り #桜ラテ #渋谷カフェ Niche (<50K, high engagement): #cherryblossomlatte #sakuraseason2026 #花見カフェ #春限定ドリンク #桜スイーツ #渋谷グルメ Copy-ready: #sakura #cherryblossom #tokyo #cafe #latte #coffeelover #tokyocafe #shibuyacafe #sakuralatte #springdrinks #japancafe #カフェ巡り #桜ラテ #渋谷カフェ #cherryblossomlatte #sakuraseason2026 #花見カフェ #春限定ドリンク #桜スイーツ #渋谷グルメ Estimated reach boost: +45% vs. no hashtags
social reply
social replyReply to mentions and comments.
$ social reply --platform x --to 1896500000000000000 "Thank you for visiting! We're glad you enjoyed the sakura latte. See you again soon!" Reply Posted ───────────────────────────────────────── Platform: X/Twitter In Reply To: @coffee_lover_jp (1896500000000000000) Original: "Best sakura latte I've ever had @hanabi_cafe!" Reply ID: 1896543999888777666 Characters: 86/280 URL: https://x.com/hanabi_cafe/status/1896543999888777666 Response time: 12 minutes from original mention
social dm
social dmSend direct messages to users or segments.
$ social dm --platform line --audience "vip_customers" --template welcome_spring --confirm LINE Direct Message Campaign ───────────────────────────────────────── Audience: VIP Customers (segment: vip_customers) Recipients: 847 users Template: welcome_spring (Flex Message) API Method: Narrowcast Sending.......... COMPLETE Delivery Report: Sent: 847 Delivered: 839 (99.1%) Opened: 612 (72.3%) <- within first hour Link Clicks: 234 (27.6%) Cost: 0 messages (within free tier: 200/1000 used this month)
social report
social reportGenerate a comprehensive social media performance report.
$ social report --period 30d --format table Social Media Report: February 2026 ═══════════════════════════════════════════════════════════ PUBLISHING SUMMARY Posts Published: 48 (X: 22, Instagram: 12, TikTok: 8, LINE: 6) Avg Posts/Week: 12.0 Best Day: Tuesday (avg +34% engagement) Best Time: 11:00-12:00 JST (lunch hour) AUDIENCE GROWTH Platform Start End Growth Rate X/Twitter 3,135 3,219 +84 +2.7% Instagram 4,975 5,102 +127 +2.6% TikTok 2,435 2,847 +412 +16.9% LINE 12,362 12,400 +38 +0.3% ENGAGEMENT LEADERS (Top 3 Posts) # Platform Content Eng. Rate 1 TikTok "Matcha art behind the scenes" 12.4% 2 Instagram "Valentine's special menu reveal" 9.8% 3 X "Snow day at the cafe + hot cocoa" 8.1% CONTENT TYPE PERFORMANCE Type Avg Engagement Rate Video 9.7% █████████████████████ Carousel 7.2% ████████████████ Image 5.8% █████████████ Text Only 3.1% ███████ Month-over-Month: Total engagement +18.4% | Followers +3.1%
social cross-post
social cross-postPublish adapted content to all configured platforms at once.
$ social cross-post "Grand opening of our new Ikebukuro location! First 50 customers get a free drink." --image store_ikebukuro.jpg --video opening_reel.mp4 Cross-Post Adaptation ───────────────────────────────────────── X/Twitter (text + image): "Grand opening of our new Ikebukuro location! First 50 customers get a free drink. #池袋 #NewOpen #GrandOpening #カフェ #春" Characters: 142/280 | Image: store_ikebukuro.jpg Status: POSTED Instagram (image + hashtags): Caption: "Grand opening of our new Ikebukuro location! First 50 customers get a free drink." + 20 optimized hashtags Image: store_ikebukuro.jpg (1:1 center crop) Status: POSTED TikTok (video): Caption: "We're OPEN in Ikebukuro! First 50 = free drink" Video: opening_reel.mp4 (verified 9:16, 45s) Status: POSTED LINE (Flex Message): Hero image + title + body + "Visit us" button with map link Audience: All friends (12,400) Status: POSTED Summary: 4/4 platforms published | Total potential reach: ~43,000
social audience
social audienceView audience demographics and insights.
$ social audience --platform instagram Instagram Audience Insights (@hanabi_cafe) ═══════════════════════════════════════════════ Total Followers: 5,102 Gender: Female: 62% ████████████████████████████████ Male: 35% ██████████████████ Other: 3% ██ Age Groups: 13-17: 2% █ 18-24: 28% ██████████████ 25-34: 41% █████████████████████ 35-44: 18% █████████ 45-54: 8% ████ 55+: 3% ██ Top Locations: Tokyo: 47% ████████████████████████ Osaka: 12% ██████ Yokohama: 8% ████ Nagoya: 5% ███ Other JP: 22% ███████████ International: 6% ███ Active Hours (JST): Peak 1: 12:00-13:00 (lunch) ████████████████████ Peak 2: 21:00-22:00 (evening) ██████████████████ Peak 3: 08:00-09:00 (commute) ████████████████ Recommendation: Target 25-34F in Tokyo during lunch hour for optimal reach.
Workflow Diagram
CONTENT LIFECYCLE ================= Idea / Content Brief | v +-----------+ | Compose |---> Write once, adapt per platform +-----------+ | v +-----------+ Immediate? +-----------+ | Timing |------ Yes -------->| Publish | | Decision | | Now | +-----------+ +-----------+ | | | Schedule? | v v +-----------+ +-----------+ | Queue |--- at time ----->>| Multi- | | (cron) | | Platform | +-----------+ | Adapter | +-----+-----+ | +------+------+----+----+------+ | | | | | v v v v v [X] [Insta] [TikTok] [LINE] ... | | | | +------+------+---------+ | v +-----------+ | Analytics | | Collector | +-----------+ | v +-----------+ | Unified | | Report | +-----------+
Error Handling
| Error | Cause | Solution |
|---|---|---|
| Expired or invalid X API tokens | Regenerate tokens at developer.x.com. Ensure your app has Read and Write permissions. |
| Attempted text-only post on Instagram | Instagram API requires at least one image. Add |
| Video uses unsupported codec or container | Re-encode with: |
| Free tier LINE message limit reached (1,000/month) | Upgrade to LINE Official Account Light plan (5,000 messages) or Standard plan (unlimited, ¥15,000/month). |
| Platform API rate limit hit (X: 300 posts/3hr, Insta: 25 posts/day) | The agent auto-queues excess posts. Check queue with |
| Image >5MB (X) or >8MB (Instagram) | The agent auto-compresses at 85% JPEG quality. For videos, use |
| Scheduled time has already passed | Ensure datetime is in the future and includes timezone. Use ISO 8601 format: |
Data Storage
All persistent data is stored under
~/.clawhub/social-media-publisher/| Path | Purpose | Format | Retention |
|---|---|---|---|
| Scheduled posts waiting for publication | SQLite | Until published or cancelled |
| Normalized engagement metrics from all platforms | SQLite | 1 year, aggregated monthly |
| Log of all published posts with platform IDs | JSON lines | 1 year |
| Uploaded media files for scheduled posts | JPEG/PNG/MP4 | Until post published, then 7 days |
| Reusable post templates and LINE Flex Messages | JSON | Permanent |
| Historical hashtag engagement data | SQLite | 6 months |
Comparison Table
| Feature | social-media-publisher | Buffer | Hootsuite | Later | Loomly |
|---|---|---|---|---|---|
| X/Twitter | Yes | Yes | Yes | Yes | Yes |
| Yes | Yes | Yes | Yes | Yes | |
| TikTok | Yes | Yes | Yes | Yes | Yes |
| LINE | Yes (native) | No | No | No | No |
| CLI Interface | Yes | No | No | No | No |
| Hashtag Optimization | AI-powered + JP | Basic | Basic | Yes | Basic |
| Cross-post Adaptation | Per-platform AI | Basic resize | Basic | Basic | Templates |
| Analytics Normalization | Unified metrics | Per-platform | Unified | Per-platform | Unified |
| Scheduling | Cron + optimal time | Calendar | Calendar | Calendar | Calendar |
| A/B Testing | Built-in variants | No | Enterprise | No | Yes |
| Audience Insights | Aggregated, privacy-safe | Basic | Yes | Basic | Basic |
| Japanese Market | Native (LINE, JP hashtags) | No | Limited | No | No |
| Price | Free (API costs only) | $6-120/mo | $99-739/mo | $25-80/mo | $42-369/mo |
| Self-hosted Data | Yes (local SQLite) | Cloud only | Cloud only | Cloud only | Cloud only |
FAQ
1. Do I need API access for all four platforms? No. Configure tokens only for the platforms you use. The agent dynamically enables features based on which environment variables are set. You can start with just X and add platforms later.
2. How do I get an X/Twitter API key? Apply at developer.x.com. You need at minimum a Free tier account ($0) which allows 1,500 tweets/month. The Basic tier ($100/month) adds analytics API access.
3. Can I post to Instagram without a Business account? No. The Instagram Graph API requires a Business or Creator account connected to a Facebook Page. Personal accounts cannot use the publishing API.
4. How does cross-posting adapt content? The agent transforms your single post into platform-optimized versions: truncates text for X's 280-char limit, adds optimized hashtags for Instagram (up to 30), converts media to the right aspect ratio, and generates LINE Flex Messages with action buttons.
5. Is LINE messaging free? LINE Official Accounts have a free tier of 1,000 messages per month. Beyond that, the Light plan costs approximately ¥5,000/month for 5,000 messages, and the Standard plan offers unlimited messages for ¥15,000/month.
6. How does the scheduler determine optimal posting time? The agent analyzes your historical engagement data to identify time slots with the highest average engagement rate. If you have fewer than 30 posts of history, it uses platform-wide best practices (lunch hour 12:00 and evening 21:00 JST for Japan).
7. Can I schedule posts weeks in advance? Yes. The schedule queue has no time limit. You can schedule posts months in advance. Posts are stored locally in SQLite, so your machine must be running at the scheduled time (or use a cron daemon).
8. How are analytics normalized across platforms? All platforms report metrics differently. The agent normalizes to a common schema: impressions (total views), engagements (likes + comments + shares + saves), engagement rate (engagements/impressions * 100), and follower delta. This allows apples-to-apples comparison.
9. Can I manage multiple accounts per platform? Yes. Set up profile aliases in
~/.clawhub/social-media-publisher/config.json--profile work--profile personal10. Does the agent support Instagram Reels and Stories? Instagram Reels are supported via the Content Publishing API. Stories require the Instagram Stories API, which is currently in limited beta. The agent will post to Reels when you include a video under 90 seconds with
--type reel11. How do I handle platform outages gracefully? If a platform API is unreachable, the agent retries 3 times with exponential backoff. If all retries fail, the post is saved to the local retry queue and attempted again in 15 minutes. Use
social schedule retry-failed12. Can I preview how a post will look before publishing? Yes. Add
--dry-run13. Is there an undo/delete function? Yes. Use
social delete --platform x --id 1896543210987654321