@datatamer.ai/agentdev 1.0.5 → 1.0.7

package/skills/agentdev-twitter.md

@@ -0,0 +1,430 @@
+# agentdev twitter — Twitter/X CLI
+
+Use `agentdev twitter` (or `agentdev x`) for ALL Twitter/X operations. Do NOT attempt to use Twitter APIs directly.
+
+## Prerequisites
+
+User must connect their Twitter/X account first:
+1. Visit /profile page on AgentDev
+2. Click "Connect Twitter"
+3. Complete OAuth authorization flow
+
+If Twitter is not connected, all commands will fail with instructions to connect.
+
+**IMPORTANT:** Twitter API v2 requires specific OAuth scopes. If you see permission errors, reconnect at /profile.
+
+## Tweet Commands
+
+### Create Tweet
+
+```bash
+agentdev twitter tweet create --text "Hello Twitter!"
+```
+
+**Character Limit:** 280 characters (validation enforced)
+
+### Create Reply
+
+```bash
+agentdev twitter tweet create \
+  --text "Great point!" \
+  --reply-to <tweet-id>
+```
+
+### Quote Tweet
+
+```bash
+agentdev twitter tweet create \
+  --text "This is insightful!" \
+  --quote <tweet-id>
+```
+
+**Or use the dedicated quote command:**
+
+```bash
+agentdev twitter quote <tweet-id> --text "Amazing thread!"
+```
+
+### Create Thread
+
+```bash
+agentdev twitter tweet thread --text "First tweet
+---
+Second tweet
+---
+Third tweet"
+```
+
+**Thread Format:**
+- Separate tweets with `---`
+- Each tweet must be ≤ 280 characters
+- Minimum 2 tweets per thread
+
+### List Your Tweets
+
+```bash
+agentdev twitter tweet list --count 20
+```
+
+### View Tweet Details
+
+```bash
+agentdev twitter tweet view <tweet-id>
+```
+
+Shows:
+- Tweet text
+- Author information
+- Metrics (replies, retweets, likes, views)
+- Timestamp
+- Tweet URL
+
+### Search Tweets
+
+```bash
+agentdev twitter tweet search "AI agents" --count 10
+```
+
+### Delete Tweet
+
+```bash
+agentdev twitter tweet delete <tweet-id> --confirm
+```
+
+**Important:** Requires `--confirm` flag to prevent accidental deletions.
+
+## Timeline Commands
+
+### View Home Timeline
+
+```bash
+agentdev twitter timeline home --count 10
+```
+
+Shows tweets from people you follow (chronological order).
+
+### View Mentions
+
+```bash
+agentdev twitter timeline mentions --count 10
+```
+
+Shows tweets that mention your @ handle.
+
+## Profile Commands
+
+### View Your Profile
+
+```bash
+agentdev twitter profile
+```
+
+### View Another User's Profile
+
+```bash
+agentdev twitter profile --username elonmusk
+```
+
+Shows:
+- Name and username
+- Bio
+- Follower/following counts
+- Tweet count
+- Verification status
+
+## Follow/Unfollow
+
+### Follow User
+
+```bash
+agentdev twitter follow @username
+```
+
+### Unfollow User
+
+```bash
+agentdev twitter unfollow @username
+```
+
+**Note:** Username can be provided with or without @ symbol.
+
+## Engagement Commands
+
+### Like Tweet
+
+```bash
+agentdev twitter like <tweet-id>
+```
+
+### Unlike Tweet
+
+```bash
+agentdev twitter unlike <tweet-id>
+```
+
+### Retweet
+
+```bash
+agentdev twitter retweet <tweet-id>
+```
+
+### Remove Retweet
+
+```bash
+agentdev twitter unretweet <tweet-id>
+```
+
+## Rate Limits
+
+Twitter API v2 has the following rate limits:
+
+**Tweets:**
+- **200 tweets per 15 minutes** (user context)
+- **50 tweet deletions per 15 minutes**
+
+**Timeline:**
+- **180 requests per 15 minutes**
+
+**Search:**
+- **180 requests per 15 minutes**
+
+**User Lookups:**
+- **900 requests per 15 minutes**
+
+**Engagement:**
+- **1000 likes per 24 hours**
+- **50 retweets per 15 minutes**
+- **400 follows per day**
+
+If rate limit is exceeded, you'll receive an error with reset time.
+
+## Error Handling
+
+| Error | Meaning | Action |
+|-------|---------|--------|
+| "Twitter not connected" | User hasn't connected Twitter | Direct user to /profile |
+| "Token expired" | OAuth token expired | User must reconnect at /profile |
+| "Rate limit exceeded" | Hit API rate limits | Wait until reset time |
+| "Duplicate tweet" | Posted same content recently | Wait or change content |
+| "Insufficient permissions" | Missing OAuth scopes | Reconnect at /profile |
+| "Resource not found" | Invalid tweet/user ID | Check ID and try again |
+| "Tweet exceeds 280 characters" | Text too long | Shorten tweet |
+
+## Agent Task Examples
+
+### Example 1: Daily Update
+
+When asked to "post a status update on Twitter":
+
+```bash
+agentdev twitter tweet create --text "Working on exciting AI features today! 🚀 #AI #Development"
+```
+
+### Example 2: Thread About Progress
+
+When asked to "create a thread about today's accomplishments":
+
+```bash
+agentdev twitter tweet thread --text "Today's accomplishments (🧵):
+---
+1. ✅ Shipped new Twitter integration for agentdev
+---
+2. ✅ Added comprehensive error handling
+---
+3. ✅ Created detailed documentation
+---
+Excited to see what tomorrow brings! #BuildInPublic"
+```
+
+### Example 3: Engage with Mentions
+
+When asked to "check my Twitter mentions":
+
+```bash
+agentdev twitter timeline mentions --count 20
+```
+
+### Example 4: Search and Engage
+
+When asked to "find tweets about AI agents and engage":
+
+```bash
+# Search for relevant tweets
+agentdev twitter tweet search "AI agents" --count 10
+
+# Like interesting tweets
+agentdev twitter like <tweet-id>
+
+# Retweet great content
+agentdev twitter retweet <tweet-id>
+
+# Reply with value
+agentdev twitter tweet create \
+  --text "Great insights! We're building similar capabilities at AgentDev" \
+  --reply-to <tweet-id>
+```
+
+### Example 5: Follow Thought Leaders
+
+When asked to "follow AI thought leaders":
+
+```bash
+agentdev twitter follow @AndrewYNg
+agentdev twitter follow @ylecun
+agentdev twitter follow @karpathy
+```
+
+### Example 6: Daily Analytics
+
+When asked to "how did my latest tweet perform?":
+
+```bash
+# Get your recent tweets
+agentdev twitter tweet list --count 1
+
+# View detailed metrics
+agentdev twitter tweet view <tweet-id>
+```
+
+### Example 7: Clean Up Old Tweets
+
+When asked to "delete that embarrassing tweet":
+
+```bash
+# Find the tweet
+agentdev twitter tweet list --count 20
+
+# Delete it
+agentdev twitter tweet delete <tweet-id> --confirm
+```
+
+### Example 8: Engage with Timeline
+
+When asked to "catch up on Twitter":
+
+```bash
+# View home timeline
+agentdev twitter timeline home --count 20
+
+# Like good content
+agentdev twitter like <tweet-id>
+
+# Retweet great finds
+agentdev twitter retweet <tweet-id>
+```
+
+## Required OAuth Scopes
+
+The following scopes are automatically requested during OAuth flow:
+
+**Read Scopes:**
+- `tweet.read` - Read tweets and timelines
+- `users.read` - Read user profiles
+- `follows.read` - Read followers/following
+- `like.read` - Read likes
+
+**Write Scopes:**
+- `tweet.write` - Create and delete tweets
+- `follows.write` - Follow/unfollow users
+- `like.write` - Like/unlike tweets
+
+**Additional:**
+- `offline.access` - Long-lived refresh tokens
+
+## Command Aliases
+
+The Twitter command group supports an alias for convenience:
+
+```bash
+agentdev x tweet create --text "Using the x alias!"
+```
+
+Both `agentdev twitter` and `agentdev x` work identically.
+
+## Notes
+
+- All tweets are posted as the authenticated user
+- Tweet IDs can be found in URLs: `twitter.com/user/status/<tweet-id>`
+- Twitter URLs work for both twitter.com and x.com
+- Deleted tweets cannot be recovered
+- Rate limits reset every 15 minutes (for most endpoints)
+- Character count includes URLs (which are shortened to ~23 chars)
+- Media uploads coming in Phase 2
+- Threads are created by replying to previous tweet in chain
+
+## Troubleshooting
+
+### "Duplicate tweet" Error
+
+Twitter prevents posting identical content too frequently.
+
+**Solutions:**
+- Wait a few minutes before posting again
+- Modify the tweet text slightly
+- Add a timestamp or unique identifier
+
+### "Token expired" Error
+
+OAuth tokens expire after a period of inactivity.
+
+**Solution:**
+- Visit /profile and reconnect Twitter account
+- Tokens will refresh automatically going forward
+
+### "Insufficient permissions" Error
+
+Your OAuth scopes may be outdated.
+
+**Solution:**
+- Disconnect Twitter at /profile
+- Reconnect to grant updated scopes
+- Try the command again
+
+### Tweet Not Appearing
+
+Tweets may take a few seconds to propagate.
+
+**Solutions:**
+- Wait 10-30 seconds
+- Check Twitter app/website directly
+- Verify tweet wasn't caught by spam filters
+
+### Can't Find Tweet ID
+
+Tweet IDs are in the URL.
+
+**Example:**
+```
+URL: https://twitter.com/user/status/1234567890
+Tweet ID: 1234567890
+```
+
+**Or use search:**
+```bash
+agentdev twitter tweet search "your tweet text" --count 1
+```
+
+## Best Practices
+
+### Avoid Rate Limits
+- Don't post more than 50 tweets in short succession
+- Space out bulk operations (likes, follows)
+- Cache timeline data instead of frequent fetches
+
+### Engagement
+- Reply with value, not spam
+- Like genuinely interesting content
+- Only retweet what your followers would find useful
+- Personalize connection requests
+
+### Content Quality
+- Proofread before posting (no edit feature in API)
+- Use threads for complex topics
+- Include relevant hashtags (2-3 max)
+- Add context to quote tweets
+
+### Safety
+- Never share sensitive information
+- Review tweets before posting
+- Use `--confirm` flag for deletions
+- Keep API tokens secure