| id | ailey-soc-threads |
| name | Threads Content Manager |
| description | Comprehensive Threads integration with account type detection, OAuth authentication, post publishing (text/images/videos/carousels), analytics, engagement management, and automatic API tier detection. Adapts features based on account type (Personal, Creator, Business). Use when managing Threads content, automating posts, analyzing performance, or engaging with audiences. |
| keywords | ["threads","social media","meta","instagram","posting","analytics","engagement","oauth","content management","creator tools","business tools"] |
| tools | ["threads-client","content-posting","analytics","engagement","account-detection"] |
Threads Content Manager
Comprehensive Threads integration with intelligent account type detection and feature adaptation. Automatically detects account capabilities and provides guidance for upgrades.
Overview
Threads by Meta has different features based on account type. This skill:
- Automatically detects account type (Personal, Creator, Business)
- Adapts features based on account capabilities
- Provides upgrade paths for enhanced features
- Works immediately with Personal accounts
- Scales up with Creator and Business accounts
When to Use
- Managing Threads content and posts
- Automating Threads publishing
- Analyzing post performance
- Engaging with audience through replies
- Checking account capabilities
- Multi-platform content distribution
- Creator and business workflows
- Building social media tools
Installation
cd .github/skills/ailey-soc-threads
npm install
Configuration
1. Prerequisites
Required:
- Instagram account (Threads uses Instagram Graph API)
- Facebook Page linked to your Instagram account
- Facebook Developer Account
- Meta App with Threads permissions
Note: Threads API is built on Instagram's infrastructure, so you need an Instagram Business/Creator account.
2. Create Meta App
- Visit Meta for Developers
- Click My Apps → Create App
- Choose Business or Consumer type
- Fill in app details
- Copy App ID and App Secret
3. Add Threads Product
- In app dashboard → Add Products
- Find Instagram → Click Set Up
- Under Instagram settings, enable Threads
- Configure OAuth redirect:
https://localhost:3000/auth/callback
4. Configure Permissions
Request these permissions:
threads_basic - Basic profile accessthreads_content_publish - Post contentthreads_manage_insights - Analyticsthreads_manage_replies - Reply managementthreads_read_replies - Read replies
5. Environment Setup
Create .env file:
THREADS_APP_ID=your_app_id_here
THREADS_APP_SECRET=your_app_secret_here
THREADS_ACCESS_TOKEN=your_access_token_here
THREADS_USER_ID=your_threads_user_id_here
THREADS_INSTAGRAM_ACCOUNT_ID=your_ig_account_id_here
6. Add to AI-ley Configuration
Edit .github/aicc/aicc.yaml:
integrations:
threads:
enabled: true
appId: ${THREADS_APP_ID}
appSecret: ${THREADS_APP_SECRET}
accessToken: ${THREADS_ACCESS_TOKEN}
userId: ${THREADS_USER_ID}
instagramAccountId: ${THREADS_INSTAGRAM_ACCOUNT_ID}
accountType: auto-detect
Account Types
Personal Account (Default)
What you get:
- ✅ Basic profile information
- ✅ Post text, images, videos
- ✅ Reply to conversations
- ✅ Basic post insights
- ✅ Up to 500 posts per day
No approval required - available immediately.
Features:
- Text posts (up to 500 characters)
- Image posts (single/multiple)
- Video posts (up to 5 minutes)
- Link sharing
- Reply to your posts
- Basic analytics
Creator Account
Additional features:
- ✅ Enhanced analytics
- ✅ Reply management tools
- ✅ Conversation insights
- ✅ Audience demographics
- ✅ Creator tools and badges
How to upgrade:
- Convert Instagram to Creator account
- Enable Threads in Instagram settings
- Reconnect API with creator permissions
Additional insights:
- Follower growth tracking
- Engagement rate analysis
- Top-performing posts
- Audience activity times
- Reply analytics
Business Account
Additional features:
- ✅ Full business analytics
- ✅ Ad integration (future)
- ✅ Advanced moderation tools
- ✅ Team management
- ✅ Business inbox
How to upgrade:
- Convert Instagram to Business account
- Link Facebook Business Page
- Enable Threads for business
- Reconnect API with business permissions
Business features:
- Comprehensive analytics
- Multi-user access
- Advanced reporting
- CRM integration
- Business verification badge
Quick Start
Detect Your Account Type
npm run threads detect
This will show:
- Your account type (Personal/Creator/Business)
- Available features
- Upgrade recommendations
- API permissions granted
Output example:
🎯 Threads Account Status
Account Type: Creator
User ID: 12345678
Username: @yourhandle
✅ Available Features:
📝 Text & media posting
📊 Enhanced analytics
💬 Reply management
👥 Audience insights
📈 Next Level: Business Account
Unlock: Advanced analytics, team tools, ad integration
How to upgrade:
1. Switch Instagram to Business account
2. Link Facebook Business Page
3. Reconnect Threads API
Setup Help
npm run threads setup
Displays comprehensive setup instructions including:
- Meta app creation
- Instagram account linking
- Threads API enablement
- OAuth configuration
- AI-ley integration
Test Connection
npm run threads test
Verifies API connection and shows your profile information.
Workflows
Workflow 1: Check Account Capabilities (All Accounts)
Use when: Starting work, checking account status, verifying permissions.
npm run threads detect
What it does:
- Tests API connection
- Retrieves account information
- Detects account type
- Lists available features
- Suggests upgrade path if applicable
Account-specific guidance:
- Personal: Shows how to upgrade to Creator
- Creator: Shows how to upgrade to Business
- Business: All features available
Workflow 2: OAuth Authentication
Use when: First setup, token expired, re-authorizing account.
npm run threads auth start
npm run threads auth token <CODE>
npm run threads test
OAuth Flow:
- Generate authorization URL with required scopes
- User visits URL and logs into Instagram
- User grants Threads permissions
- Meta redirects with authorization code
- Exchange code for access token
- Store token in
.env
Required scopes:
- Personal:
threads_basic, threads_content_publish
- Creator: +
threads_manage_insights, threads_manage_replies
- Business: +
threads_read_replies, advanced permissions
Workflow 3: Post to Threads
Use when: Publishing content, automating posts, cross-posting.
npm run threads post "Just shipped a new feature! 🚀"
npm run threads post "Excited to share this with @username #developer #tech"
npm run threads post "Check out this view!" \
--image photo.jpg
npm run threads post "Quick tutorial" \
--video tutorial.mp4
npm run threads post "Behind the scenes 📸" \
--images "photo1.jpg,photo2.jpg,photo3.jpg"
npm run threads post "New blog post is live!" \
--link "https://example.com/post"
npm run threads post "Scheduled announcement" \
--schedule "2026-02-05T10:00:00Z"
Post Options:
--image PATH - Single image--images PATHS - Multiple images (comma-separated, max 10)--video PATH - Video file (max 5 minutes)--link URL - Attach link--schedule TIME - Schedule post (Business only)--alt-text TEXT - Image alt text for accessibility
Post Limits:
- Text: 500 characters
- Images: Max 10 per post
- Video: Max 5 minutes
- Daily posts: 500 (personal), 1000 (business)
Upload Process:
- Skill validates post content
- Uploads media if included
- Creates post with metadata
- Returns post ID and URL
- Tracks post in analytics
Workflow 4: View Analytics (Creator/Business Required)
Use when: Tracking performance, analyzing engagement, optimizing content.
npm run threads analytics post POST_ID
npm run threads analytics account --days 30
npm run threads analytics audience
npm run threads analytics top --days 7 --metric likes
Available Metrics:
Post Level:
- Likes, replies, reposts, quotes
- Views, reach, impressions
- Engagement rate
- Click-through rate (if link)
- Save count
Account Level:
- Follower count and growth
- Post frequency
- Total engagement
- Average engagement rate
- Top-performing content
Audience Insights (Creator/Business):
- Demographics (age, gender, location)
- Active hours
- Follower sources
- Interest categories
If Personal Account:
❌ Enhanced analytics require Creator or Business account
To unlock:
1. Switch to Creator or Business account in Instagram
2. Reconnect Threads API
3. Grant insights permissions
Workflow 5: Manage Replies (Creator/Business Recommended)
Use when: Engaging with audience, moderating conversations, customer service.
npm run threads replies list POST_ID
npm run threads replies create POST_ID \
--text "Thanks for the feedback! 🙏"
npm run threads replies thread REPLY_ID
npm run threads replies hide REPLY_ID
npm run threads replies unhide REPLY_ID
npm run threads replies delete REPLY_ID
npm run threads replies moderate POST_ID \
--filter spam \
--action hide
Reply Management:
- Personal: Basic reply capabilities
- Creator: Enhanced moderation tools
- Business: Advanced filtering and automation
Moderation Options:
- Hide/unhide replies
- Filter by keywords
- Bulk operations
- Auto-moderation rules (Business)
Workflow 6: Search & Discovery
Use when: Finding conversations, researching topics, monitoring brand mentions.
npm run threads search "keyword" --mine
npm run threads search "#developer"
npm run threads search "@yourhandle"
npm run threads posts list --limit 50
npm run threads trending
Workflow 7: User Profile Management
Use when: Updating profile, checking stats, managing account settings.
npm run threads profile
npm run threads profile update \
--bio "New bio text" \
--link "https://example.com"
npm run threads followers count
npm run threads following count
Workflow 8: Batch Operations
Use when: Bulk posting, scheduled campaigns, content automation.
npm run threads batch-post posts.csv
npm run threads batch-analytics post_ids.txt \
--output analytics.csv
npm run threads queue list
npm run threads queue cancel POST_ID
API Rate Limits
Rate Limit Tiers
Personal Account:
- 200 requests per hour
- 500 posts per day
- 1,000 replies per day
Creator Account:
- 500 requests per hour
- 1,000 posts per day
- 5,000 replies per day
Business Account:
- 1,000 requests per hour
- Unlimited posts (within reason)
- Unlimited replies
Rate Limit Handling
The skill automatically:
- Tracks request count
- Waits when limits approached
- Retries with exponential backoff
- Warns when nearing limits
npm run threads rate-limit
Content Guidelines
Text Posts
Best practices:
- Keep under 500 characters
- Use line breaks for readability
- Include relevant hashtags (max 5)
- Tag relevant accounts with @
- Add emoji for personality
- Ask questions to drive engagement
Example:
Just shipped a major update! 🚀
New features:
• Dark mode
• Better performance
• Bug fixes
What feature do you want next? 👇
#developer #coding
Image Posts
Requirements:
- Format: JPG, PNG, WebP
- Max size: 8MB per image
- Aspect ratio: 4:5 to 1.91:1
- Resolution: 1080px width minimum
- Max 10 images per post
Best practices:
- Use high-quality images
- Optimize for mobile viewing
- Add alt text for accessibility
- First image is preview thumbnail
- Consider carousel for stories
Video Posts
Requirements:
- Format: MP4, MOV
- Max duration: 5 minutes
- Max size: 500MB
- Aspect ratio: 4:5 to 16:9
- Frame rate: 30fps or 60fps
- Audio: AAC, 128kbps+
Best practices:
- First 3 seconds grab attention
- Include captions/subtitles
- Optimize for sound-off viewing
- Keep under 1 minute for engagement
- Use vertical or square format
Error Handling
Common Errors
Invalid Access Token:
Error: OAuthException
Message: Invalid OAuth access token.
Solution:
- Run: npm run threads auth start
- Ensure token hasn't expired
- Check .env configuration
Insufficient Permissions:
Error: PermissionsError
Message: Requires threads_manage_insights permission.
Solution:
- Upgrade to Creator/Business account
- Re-authenticate with required scopes
- Run: npm run threads auth start
Rate Limit Exceeded:
Error: RateLimitError
Message: Application request limit reached.
Solution:
- Wait until rate limit resets
- Upgrade account tier for higher limits
- Implement request batching
Post Too Long:
Error: ValidationError
Message: Text exceeds 500 characters.
Solution:
- Reduce text to 500 characters
- Split into multiple posts
- Use thread feature (if available)
Automatic Retry
The skill automatically retries:
- Rate limit errors (with backoff)
- Temporary network errors (3 attempts)
- Server errors (exponential backoff)
Advanced Features
Cross-Posting
npm run threads cross-post "My announcement!" \
--platforms "instagram,twitter,facebook"
Content Templates
npm run threads template save daily-update \
--text "Daily Update - {{date}}: {{content}}"
npm run threads template post daily-update \
--vars "content=Shipped new features"
Hashtag Research
npm run threads hashtags analyze "#developer"
npm run threads hashtags trending --category tech
npm run threads hashtags track "#coding" --days 30
Audience Targeting
npm run threads audience activity
npm run threads audience best-time
npm run threads audience demographics
Automated Workflows
npm run threads auto-reply \
--trigger "mention" \
--template "Thanks for the mention! 🙏"
npm run threads auto-moderate \
--filter spam \
--action hide
npm run threads rss-feed "https://blog.example.com/feed" \
--interval 1h \
--template "New post: {{title}} {{link}}"
Integration with AI-ley
Workflow Automation
Auto-post workflow:
name: Threads Auto Post
trigger:
type: file_created
pattern: ./content/threads/*.txt
actions:
- name: Post to Threads
skill: ailey-soc-threads
command: post
args:
text: ${file.content}
image: ${file.path.replace('.txt', '.jpg')}
Analytics monitoring:
name: Threads Analytics Monitor
trigger:
type: schedule
cron: "0 9 * * *"
actions:
- name: Get daily analytics
skill: ailey-soc-threads
command: analytics
args:
type: account
days: 1
- name: Alert on growth
conditions:
- ${threads.follower_growth} > 100
actions:
- notify: slack
message: "🎉 Gained ${threads.follower_growth} followers!"
Custom Agents
# .github/agents/threads-manager.agent.md
# Threads Manager Agent
**Role:** Specialized Threads content and engagement agent
**Capabilities:**
- Post optimization and scheduling
- Audience engagement management
- Analytics and performance tracking
- Content strategy recommendations
**Skills:**
- ailey-soc-threads (primary)
- ailey-tools-image (for media)
- ailey-tools-seo-report (for hashtags)
Best Practices
Content Strategy
- Post consistently - Daily or several times per week
- Engage authentically - Reply to comments and mentions
- Use multimedia - Images and videos get more engagement
- Optimal timing - Post when your audience is active
- Hashtag wisely - 3-5 relevant hashtags per post
- Ask questions - Drive conversations
- Be conversational - Threads is about dialogue
Growth Tactics
- Reply to others - Engage in your niche
- Share insights - Provide value
- Be timely - Comment on trending topics
- Cross-promote - Link from Instagram/other platforms
- Collaborate - Engage with other creators
- Track analytics - Learn what resonates
- Iterate quickly - Test different content types
Analytics Optimization
- Track engagement rate - More important than follower count
- Identify top content - Replicate what works
- Monitor reply rate - Indicates conversation quality
- Analyze timing - Post when audience is active
- A/B test - Try different formats and styles
- Follow trends - But stay authentic
- Review weekly - Adjust strategy based on data
Troubleshooting
Setup Issues
Problem: Can't find Threads in Meta App
Solution:
1. Ensure Instagram product is added first
2. Look for Threads under Instagram settings
3. May need to request access if not visible
Problem: Instagram account not linking
Solution:
1. Convert Instagram to Business/Creator account
2. Link Facebook Page to Instagram
3. Ensure Page has Instagram access
4. Reconnect in Meta App settings
Connection Issues
npm run threads diagnose
Missing Features
npm run threads detect
Examples
Example 1: Daily Posting Schedule
#!/bin/bash
MORNING="Good morning! ☀️ Starting the day with coffee and code."
EVENING="Wrapping up for the day. What did you ship today? 🚀"
if [ $(date +%H) -eq 9 ]; then
npm run threads post "$MORNING"
fi
if [ $(date +%H) -eq 18 ]; then
npm run threads post "$EVENING"
fi
Example 2: Content Series
#!/bin/bash
SERIES_HASHTAG="#30DayChallenge"
for day in {1..30}; do
TEXT="Day $day/$30: $(cat day-$day.txt) $SERIES_HASHTAG"
IMAGE="tutorials/day-$day.jpg"
npm run threads post "$TEXT" --image "$IMAGE"
sleep 86400
done
Example 3: Engagement Bot
#!/bin/bash
REPLIES=$(npm run threads replies list --recent)
echo "$REPLIES" | grep "?" | while read REPLY_ID; do
npm run threads replies create $REPLY_ID \
--text "Great question! Let me think about that and get back to you. 🤔"
done
Example 4: Analytics Dashboard
#!/bin/bash
WEEK_START=$(date -v-mon -v-7d +%Y-%m-%d)
WEEK_END=$(date -v-mon -v-1d +%Y-%m-%d)
npm run threads analytics report \
--start "$WEEK_START" \
--end "$WEEK_END" \
--output "reports/week-$(date +%Y%U).html"
mail -s "Weekly Threads Report" team@example.com < "reports/week-$(date +%Y%U).html"
API Reference
Authentication
auth.start() - Begin OAuth flowauth.token(code) - Exchange code for tokenauth.refresh() - Refresh access token
Posts
posts.create(text, options) - Create postposts.get(postId) - Get post detailsposts.list(options) - List postsposts.delete(postId) - Delete post
Analytics (Creator/Business)
analytics.post(postId) - Post metricsanalytics.account(days) - Account metricsanalytics.audience() - Audience insightsanalytics.top(metric, days) - Top posts
Replies
replies.list(postId) - List repliesreplies.create(postId, text) - Reply to postreplies.hide(replyId) - Hide replyreplies.delete(replyId) - Delete reply
Profile
profile.get() - Get profile infoprofile.update(data) - Update profileprofile.stats() - Profile statistics
Account
account.detect() - Detect account typeaccount.limits() - Get rate limitsaccount.permissions() - List permissions
Support
Getting Help
Setup Issues:
npm run threads setup
Diagnostics:
npm run threads diagnose
Documentation:
Community:
version: 1.0.0
updated: 2026-02-01
reviewed: 2026-02-01
score: 4.7
