@datatamer.ai/agentdev 1.0.6 → 1.0.8

package/skills/agentdev-linkedin.md

@@ -0,0 +1,425 @@
+# agentdev linkedin — LinkedIn CLI
+
+Use `agentdev linkedin` for ALL LinkedIn operations. Do NOT attempt to use LinkedIn APIs directly.
+
+## Prerequisites
+
+User must connect their LinkedIn account first:
+1. Visit /profile page on AgentDev
+2. Click "Connect LinkedIn"
+3. Complete OAuth authorization flow
+
+If LinkedIn is not connected, all commands will fail with instructions to connect.
+
+**IMPORTANT:** After new scopes are added, users must reconnect their LinkedIn account at /profile to grant new permissions.
+
+## Post Commands
+
+### Create Posts
+
+#### Text-only post
+
+```bash
+agentdev linkedin post create --text "Your message here"
+```
+
+#### Share article/URL
+
+```bash
+agentdev linkedin post create \
+  --text "Check out this article about AI agents" \
+  --url "https://example.com/article" \
+  --url-title "AI Agents in 2026" \
+  --url-description "A comprehensive guide to AI agents"
+```
+
+**Note:** `--url-title` is required when using `--url`
+
+#### Post with image
+
+```bash
+agentdev linkedin post create \
+  --text "Great photo from the conference" \
+  --image /path/to/image.png \
+  --image-title "Conference 2026"
+```
+
+**Note:** Only PNG and JPG images are supported
+
+#### Post with video
+
+```bash
+agentdev linkedin post create \
+  --text "Check out this video!" \
+  --video /path/to/video.mp4 \
+  --thumbnail /path/to/thumbnail.jpg
+```
+
+**Video Requirements:**
+- Format: MP4 only
+- Size: 75KB - 5GB (organic posts)
+- Duration: 3 seconds to 30 minutes
+- Thumbnail: Optional, JPG format
+
+#### Visibility options
+
+```bash
+# Public post (default)
+agentdev linkedin post create --text "Hello LinkedIn!" --visibility PUBLIC
+
+# Connections only
+agentdev linkedin post create --text "Hello connections!" --visibility CONNECTIONS
+```
+
+### Manage Posts
+
+#### List your posts
+
+```bash
+agentdev linkedin post list --count 20 --sort LAST_MODIFIED
+```
+
+**Options:**
+- `--count` - Number of posts to retrieve (default: 10)
+- `--sort` - Sort order: LAST_MODIFIED or CREATED (default: LAST_MODIFIED)
+
+#### View post details
+
+```bash
+agentdev linkedin post view "urn:li:share:123456"
+```
+
+Returns full post details including text, visibility, and lifecycle state.
+
+#### Edit a post
+
+```bash
+agentdev linkedin post edit "urn:li:share:123456" --text "Updated text content"
+```
+
+**Note:** Only commentary/text can be edited. Media cannot be changed after posting.
+
+#### Delete a post
+
+```bash
+agentdev linkedin post delete "urn:li:share:123456" --confirm
+```
+
+**Important:** Requires `--confirm` flag to prevent accidental deletions.
+
+## Analytics & Engagement
+
+### Post analytics
+
+```bash
+agentdev linkedin analytics post "urn:li:share:123456"
+```
+
+Returns:
+- Total reactions by type (LIKE, PRAISE, EMPATHY, INTEREST, APPRECIATION)
+- Total comments
+- Comments state (OPEN, CLOSED, etc.)
+
+### Reactions breakdown
+
+```bash
+# All reactions
+agentdev linkedin analytics reactions "urn:li:share:123456"
+
+# Filter by type
+agentdev linkedin analytics reactions "urn:li:share:123456" --type LIKE
+```
+
+**Reaction Types:**
+- LIKE 👍
+- PRAISE 👏
+- MAYBE 💡
+- EMPATHY ❤️
+- INTEREST 💭
+- APPRECIATION 🙌
+
+### Post comments
+
+```bash
+agentdev linkedin analytics comments "urn:li:share:123456" --count 20
+```
+
+Returns comment text, authors, and metadata.
+
+## Connections Management
+
+### List connections
+
+```bash
+agentdev linkedin connections list --count 50
+```
+
+**Note:** Maximum 50 connections per request (LinkedIn limit)
+
+### Send connection request
+
+```bash
+# By person URN
+agentdev linkedin connections send \
+  --person "urn:li:person:ABC123" \
+  --message "Let's connect!"
+
+# By email
+agentdev linkedin connections send \
+  --email "user@example.com" \
+  --message "Great meeting you at the conference!"
+```
+
+### Accept connection request
+
+```bash
+agentdev linkedin connections accept <invitation-id> --token <validation-token>
+```
+
+**Note:** Validation token is provided in the invitation notification.
+
+### Reject connection request
+
+```bash
+agentdev linkedin connections reject <invitation-id> --token <validation-token>
+```
+
+### View person profile
+
+```bash
+agentdev linkedin person ABC123
+```
+
+Returns name, headline, and person ID.
+
+## Organization/Company Pages
+
+**Requirements:**
+- User must have ADMINISTRATOR, CONTENT_ADMIN, or DIRECT_SPONSORED_CONTENT_POSTER role
+- Organization ID must be valid and accessible by the user
+
+### Post as organization
+
+```bash
+agentdev linkedin org post \
+  --id 12345 \
+  --text "Company announcement: New product launch!" \
+  --visibility PUBLIC
+```
+
+### View organization profile
+
+```bash
+agentdev linkedin org view 12345
+```
+
+Returns organization name, vanity name, website, and ID.
+
+### Organization analytics
+
+```bash
+agentdev linkedin org analytics "urn:li:organization:12345" --days 30
+```
+
+Returns:
+- Total followers (organic + paid)
+- Follower gains/losses
+- Demographics (by country, industry, function)
+
+**Note:** Requires `rw_organization_admin` scope and ADMINISTRATOR role.
+
+### List organization posts
+
+```bash
+agentdev linkedin org posts "urn:li:organization:12345" --count 20
+```
+
+## Profile Commands
+
+### View your profile
+
+```bash
+agentdev linkedin profile
+```
+
+Returns: Name, email, person ID, and profile picture URL
+
+## Authentication Commands
+
+### Check auth status
+
+```bash
+agentdev linkedin auth
+```
+
+Verifies that LinkedIn is connected and token is valid.
+
+## Rate Limits
+
+- **150 posts per day** per user (LinkedIn limit)
+- **100,000 API requests per day** per application
+- **Comment creation:** 1-minute cooldown between comments
+- **Connection requests:** LinkedIn may throttle excessive sending
+
+If rate limit is exceeded, you'll receive a clear error message with retry-after information.
+
+## Error Handling
+
+| Error | Meaning | Action |
+|-------|---------|--------|
+| "LinkedIn not connected" | User hasn't connected LinkedIn | Direct user to /profile to connect |
+| "Token expired" | OAuth token expired | User must reconnect at /profile |
+| "Missing required scope" | New permissions needed | User must reconnect at /profile |
+| "Rate limit exceeded" | Hit API rate limits | Wait for retry-after period |
+| "Permission denied" | Insufficient org permissions | User needs ADMINISTRATOR or CONTENT_ADMIN role |
+| "Image/Video file not found" | Invalid file path | Check file path and permissions |
+| "Video file too large" | Video exceeds 5GB | Reduce video size |
+
+## Required OAuth Scopes
+
+The following scopes are automatically requested during OAuth flow:
+- `openid` - User authentication
+- `profile` - Access to profile information
+- `email` - Access to user email
+- `w_member_social` - Create posts and share content
+- `r_member_social` - Read posts, analytics, engagement data
+- `r_1st_connections` - View connections list
+- `r_liteprofile` - View person profiles
+- `w_organization_social` - Post as organization
+- `r_organization_social` - Read organization posts
+- `rw_organization_admin` - Manage organization, view analytics
+
+## Agent Task Examples
+
+### Example 1: Post completion update
+
+When asked to "post to LinkedIn about completing ticket #123":
+
+```bash
+agentdev linkedin post create --text "✅ Completed ticket #123: Fixed authentication bug in the login flow"
+```
+
+### Example 2: Share blog post
+
+When asked to "share this blog post on LinkedIn":
+
+```bash
+agentdev linkedin post create \
+  --text "New blog post about our latest features! 🚀" \
+  --url "https://blog.example.com/new-features" \
+  --url-title "Latest Features Update - February 2026"
+```
+
+### Example 3: Post with video
+
+When asked to "share the demo video on LinkedIn":
+
+```bash
+agentdev linkedin post create \
+  --text "Check out our new feature demo!" \
+  --video ./demos/feature-demo.mp4 \
+  --thumbnail ./demos/thumbnail.jpg
+```
+
+### Example 4: Check post performance
+
+When asked to "how is my latest LinkedIn post performing?":
+
+```bash
+# First, get the post URN
+agentdev linkedin post list --count 1
+
+# Then get analytics
+agentdev linkedin analytics post "urn:li:share:123456"
+```
+
+### Example 5: Post as company
+
+When asked to "post this announcement on the company LinkedIn page":
+
+```bash
+agentdev linkedin org post \
+  --id 12345 \
+  --text "We're hiring! Join our amazing team of engineers."
+```
+
+### Example 6: Grow network
+
+When asked to "send a connection request to john@example.com":
+
+```bash
+agentdev linkedin connections send \
+  --email "john@example.com" \
+  --message "I enjoyed our conversation at the conference. Let's stay in touch!"
+```
+
+### Example 7: Clean up old posts
+
+When asked to "delete my LinkedIn post from last week":
+
+```bash
+# First, find the post
+agentdev linkedin post list --count 10
+
+# Then delete it (with confirmation)
+agentdev linkedin post delete "urn:li:share:123456" --confirm
+```
+
+### Example 8: Monitor engagement
+
+When asked to "show me who reacted to my latest post":
+
+```bash
+# Get the latest post
+agentdev linkedin post list --count 1
+
+# Check reactions breakdown
+agentdev linkedin analytics reactions "urn:li:share:123456"
+
+# Check comments
+agentdev linkedin analytics comments "urn:li:share:123456"
+```
+
+## Notes
+
+- All posts are created as the authenticated user (unless using org commands)
+- Image uploads use a 2-step process (register → upload → attach to post)
+- Video uploads use multi-part chunked upload (4MB chunks)
+- Post IDs are returned on successful creation
+- Token refresh is handled automatically when tokens expire
+- Organization features require appropriate roles and permissions
+- Analytics data may take time to populate after posting
+- Deleted posts cannot be recovered
+- Edited posts show as "Edited" on LinkedIn
+
+## Troubleshooting
+
+### "Missing required scope: r_member_social"
+
+User needs to reconnect LinkedIn at /profile to grant new permissions. The OAuth scopes were recently expanded to support analytics and advanced features.
+
+### "You don't have permission to post as this organization"
+
+User must have one of these roles on the organization:
+- ADMINISTRATOR
+- CONTENT_ADMIN
+- DIRECT_SPONSORED_CONTENT_POSTER
+
+Ask the organization admin to grant appropriate permissions.
+
+### Video upload fails
+
+Check:
+1. File format is MP4
+2. File size is between 75KB and 5GB
+3. File path is correct and accessible
+4. Video duration is between 3 seconds and 30 minutes
+
+### Connection request fails
+
+LinkedIn may throttle connection requests if:
+- Too many requests sent in a short period
+- Recipient has blocked connection requests
+- Account is flagged for suspicious activity
+
+Wait before sending more requests and ensure requests are personalized.