trakt – OpenClaw Skill

---

name: trakt description: Interact with the Trakt API to manage your watchlist, collection, ratings, and discover content metadata: {"openclaw": {"requires": {"env": ["TRAKT_CLIENT_ID", "TRAKT_CLIENT_SECRET", "TRAKT_ACCESS_TOKEN"]}, "primaryEnv": "TRAKT_ACCESS_TOKEN", "homepage": "https://trakt.tv"}}

Trakt API Integration

Interact with Trakt.tv to manage your watchlist, track viewing history, maintain your collection, rate content, and discover new movies and shows.

Authentication

Before using this skill, you need to set up Trakt API credentials:

1. Create a Trakt application at https://trakt.tv/oauth/applications
2. Get your Client ID and Client Secret
3. Complete OAuth flow to get an access token
4. Set environment variables in ~/.openclaw/openclaw.json:

{
  "skills": {
    "entries": {
      "trakt": {
        "enabled": true,
        "env": {
          "TRAKT_CLIENT_ID": "your_client_id",
          "TRAKT_CLIENT_SECRET": "your_client_secret",
          "TRAKT_ACCESS_TOKEN": "your_access_token",
          "TRAKT_REFRESH_TOKEN": "your_refresh_token"
        }
      }
    }
  }
}

Available Commands

Watchlist Management

Add to watchlist:

curl -X POST https://api.trakt.tv/sync/watchlist \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TRAKT_ACCESS_TOKEN" \
  -H "trakt-api-version: 2" \
  -H "trakt-api-key: $TRAKT_CLIENT_ID" \
  -d '{"movies":[{"title":"Inception","year":2010}]}'

Get watchlist:

curl https://api.trakt.tv/sync/watchlist/movies \
  -H "Authorization: Bearer $TRAKT_ACCESS_TOKEN" \
  -H "trakt-api-version: 2" \
  -H "trakt-api-key: $TRAKT_CLIENT_ID"

Remove from watchlist:

curl -X POST https://api.trakt.tv/sync/watchlist/remove \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TRAKT_ACCESS_TOKEN" \
  -H "trakt-api-version: 2" \
  -H "trakt-api-key: $TRAKT_CLIENT_ID" \
  -d '{"movies":[{"ids":{"trakt":12601}}]}'

Search

Search movies:

curl "https://api.trakt.tv/search/movie?query=inception" \
  -H "trakt-api-version: 2" \
  -H "trakt-api-key: $TRAKT_CLIENT_ID"

Search shows:

curl "https://api.trakt.tv/search/show?query=breaking+bad" \
  -H "trakt-api-version: 2" \
  -H "trakt-api-key: $TRAKT_CLIENT_ID"

History

Get watch history:

curl https://api.trakt.tv/sync/history \
  -H "Authorization: Bearer $TRAKT_ACCESS_TOKEN" \
  -H "trakt-api-version: 2" \
  -H "trakt-api-key: $TRAKT_CLIENT_ID"

Add to history (mark as watched):

curl -X POST https://api.trakt.tv/sync/history \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TRAKT_ACCESS_TOKEN" \
  -H "trakt-api-version: 2" \
  -H "trakt-api-key: $TRAKT_CLIENT_ID" \
  -d '{"movies":[{"title":"The Matrix","year":1999,"watched_at":"2024-01-15T20:00:00.000Z"}]}'

Collection

Get collection:

curl https://api.trakt.tv/sync/collection/movies \
  -H "Authorization: Bearer $TRAKT_ACCESS_TOKEN" \
  -H "trakt-api-version: 2" \
  -H "trakt-api-key: $TRAKT_CLIENT_ID"

Add to collection:

curl -X POST https://api.trakt.tv/sync/collection \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TRAKT_ACCESS_TOKEN" \
  -H "trakt-api-version: 2" \
  -H "trakt-api-key: $TRAKT_CLIENT_ID" \
  -d '{"movies":[{"title":"Blade Runner 2049","year":2017,"collected_at":"2024-01-15T20:00:00.000Z","media_type":"bluray","resolution":"uhd_4k"}]}'

Ratings

Get ratings:

curl https://api.trakt.tv/sync/ratings/movies \
  -H "Authorization: Bearer $TRAKT_ACCESS_TOKEN" \
  -H "trakt-api-version: 2" \
  -H "trakt-api-key: $TRAKT_CLIENT_ID"

Add rating:

curl -X POST https://api.trakt.tv/sync/ratings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TRAKT_ACCESS_TOKEN" \
  -H "trakt-api-version: 2" \
  -H "trakt-api-key: $TRAKT_CLIENT_ID" \
  -d '{"movies":[{"title":"The Shawshank Redemption","year":1994,"rating":10}]}'

Discovery

Get recommendations:

curl https://api.trakt.tv/recommendations/movies?limit=10 \
  -H "Authorization: Bearer $TRAKT_ACCESS_TOKEN" \
  -H "trakt-api-version: 2" \
  -H "trakt-api-key: $TRAKT_CLIENT_ID"

Get trending:

curl https://api.trakt.tv/movies/trending \
  -H "trakt-api-version: 2" \
  -H "trakt-api-key: $TRAKT_CLIENT_ID"

Get popular:

curl https://api.trakt.tv/movies/popular \
  -H "trakt-api-version: 2" \
  -H "trakt-api-key: $TRAKT_CLIENT_ID"

Data Format

Movie Object

{
  "title": "Inception",
  "year": 2010,
  "ids": {
    "trakt": 16662,
    "slug": "inception-2010",
    "imdb": "tt1375666",
    "tmdb": 27205
  }
}

Show Object

{
  "title": "Breaking Bad",
  "year": 2008,
  "ids": {
    "trakt": 1,
    "slug": "breaking-bad",
    "tvdb": 81189,
    "imdb": "tt0903747",
    "tmdb": 1396
  }
}

Episode Object

{
  "season": 1,
  "number": 1,
  "title": "Pilot",
  "ids": {
    "trakt": 73482,
    "tvdb": 349232,
    "imdb": "tt0959621",
    "tmdb": 62085
  }
}

Usage Instructions

When the user asks to interact with Trakt:

1. Always use curl with proper headers including the access token

2. Required headers for all requests:

   • trakt-api-version: 2
   • trakt-api-key: $TRAKT_CLIENT_ID
   • Authorization: Bearer $TRAKT_ACCESS_TOKEN (for authenticated endpoints)
   • Content-Type: application/json (for POST/PUT/DELETE)

3. Identify the item using title and year, or IDs if available

4. Use appropriate endpoint based on the action:

   • Watchlist: /sync/watchlist (POST to add, /sync/watchlist/remove to remove)
   • History: /sync/history (GET for viewing, POST for adding)
   • Collection: /sync/collection (GET for viewing, POST for adding)
   • Ratings: /sync/ratings (GET for viewing, POST for adding)
   • Search: /search/{type}?query={q} (no auth required)
   • Trending: /{type}/trending (no auth required)
   • Popular: /{type}/popular (no auth required)
   • Recommendations: /recommendations/{type} (requires auth)

5. Handle responses appropriately:

   • Success: 200/201 status codes
   • Not found: 404
   • Unauthorized: 401 (token may need refresh)
   • Rate limited: 429

Rate Limits

• Authenticated: 1000 GET requests per 5 minutes, 1 POST/PUT/DELETE per second
• Unauthenticated: 1000 GET requests per 5 minutes

Getting OAuth Token

To get an access token, use this helper script:

#!/bin/bash
# Save as get_trakt_token.sh

CLIENT_ID="your_client_id"
CLIENT_SECRET="your_client_secret"
REDIRECT_URI="urn:ietf:wg:oauth:2.0:oob"

echo "1. Open this URL in your browser:"
echo "https://trakt.tv/oauth/authorize?response_type=code&client_id=$CLIENT_ID&redirect_uri=$REDIRECT_URI"
echo ""
echo "2. Authorize the app and copy the code"
echo -n "3. Paste the code here: "
read CODE

echo ""
echo "Exchanging code for token..."

RESPONSE=$(curl -s -X POST https://api.trakt.tv/oauth/token \
  -H "Content-Type: application/json" \
  -d "{
    \"code\": \"$CODE\",
    \"client_id\": \"$CLIENT_ID\",
    \"client_secret\": \"$CLIENT_SECRET\",
    \"redirect_uri\": \"$REDIRECT_URI\",
    \"grant_type\": \"authorization_code\"
  }")

echo ""
echo "Response:"
echo "$RESPONSE" | jq .
echo ""
echo "Add these to your OpenClaw config:"
echo "TRAKT_ACCESS_TOKEN=$(echo $RESPONSE | jq -r .access_token)"
echo "TRAKT_REFRESH_TOKEN=$(echo $RESPONSE | jq -r .refresh_token)"

Make it executable: chmod +x get_trakt_token.sh

Examples

User: "Add Dune to my Trakt watchlist"

Assistant: I'll add Dune to your Trakt watchlist.

curl -X POST https://api.trakt.tv/sync/watchlist \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TRAKT_ACCESS_TOKEN" \
  -H "trakt-api-version: 2" \
  -H "trakt-api-key: $TRAKT_CLIENT_ID" \
  -d '{"movies":[{"title":"Dune","year":2021}]}'

---

User: "What movies are trending on Trakt?"

Assistant: Let me check the trending movies on Trakt.

curl "https://api.trakt.tv/movies/trending?limit=10" \
  -H "trakt-api-version: 2" \
  -H "trakt-api-key: $TRAKT_CLIENT_ID"

---

User: "Rate Breaking Bad 10/10 on Trakt"

Assistant: I'll rate Breaking Bad 10/10 on Trakt.

curl -X POST https://api.trakt.tv/sync/ratings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TRAKT_ACCESS_TOKEN" \
  -H "trakt-api-version: 2" \
  -H "trakt-api-key: $TRAKT_CLIENT_ID" \
  -d '{"shows":[{"title":"Breaking Bad","year":2008,"rating":10}]}'

Notes

• Items are automatically removed from watchlist when marked as watched
• You can use IDs instead of title/year for more accuracy
• Extended info can be requested with ?extended=full parameter
• All dates should be in UTC ISO 8601 format
• The API supports batch operations - you can add multiple items in one request

Trakt AgentSkill for OpenClaw

An AgentSkills-compatible skill that enables OpenClaw agents to interact with the Trakt API for managing watchlists, tracking viewing history, maintaining collections, rating content, and discovering movies and shows.

What is AgentSkills?

AgentSkills is a standardized format for teaching AI agents how to use tools. Each skill is a folder containing a SKILL.md file with YAML frontmatter and usage instructions. OpenClaw loads these skills and makes them available to the agent.

This is NOT an MCP server - it's a simple skill file that teaches the agent how to use the Trakt API via curl commands.

Installation

Option 1: Install via ClawHub (Recommended)

npm install -g clawhub
clawhub install trakt

Option 2: Manual Installation

1. Clone or download this repository to your OpenClaw skills directory:

# For workspace-specific (highest priority)
cd your-workspace
git clone https://github.com/yourusername/trakt-openclaw.git skills/trakt

# For user-wide (shared across all agents)
git clone https://github.com/yourusername/trakt-openclaw.git ~/.openclaw/skills/trakt

2. OpenClaw will automatically detect the skill in the next session.

Setup

Step 1: Create a Trakt Application

1. Go to https://trakt.tv/oauth/applications
2. Click "New Application"
3. Fill in:
   • Name: OpenClaw Trakt Integration (or your preferred name)
   • Description: AI agent access to Trakt
   • Redirect URI: urn:ietf:wg:oauth:2.0:oob
4. Save and note your Client ID and Client Secret

Step 2: Get OAuth Access Token

Run the included helper script:

chmod +x get_trakt_token.sh
./get_trakt_token.sh

Follow the prompts to:

1. Open the authorization URL
2. Approve the application
3. Copy the code
4. Paste it into the script

The script will output the configuration you need.

Step 3: Configure OpenClaw

Add the configuration to ~/.openclaw/openclaw.json:

{
  "skills": {
    "entries": {
      "trakt": {
        "enabled": true,
        "env": {
          "TRAKT_CLIENT_ID": "your_client_id_here",
          "TRAKT_CLIENT_SECRET": "your_client_secret_here",
          "TRAKT_ACCESS_TOKEN": "your_access_token_here",
          "TRAKT_REFRESH_TOKEN": "your_refresh_token_here"
        }
      }
    }
  }
}

Step 4: Restart OpenClaw

Skills are loaded at session start, so restart your OpenClaw agent to pick up the new skill.

Usage

Once configured, you can ask your OpenClaw agent to interact with Trakt:

Watchlist:

• "Add Inception to my Trakt watchlist"
• "Show me my Trakt watchlist"
• "Remove The Matrix from my watchlist"

Search:

• "Search Trakt for movies about space"
• "Find shows similar to Breaking Bad on Trakt"

History:

• "Mark Dune as watched on Trakt"
• "Show my Trakt watch history"

Collection:

• "Add Blade Runner 2049 to my Trakt collection as 4K Blu-ray"
• "Show my movie collection on Trakt"

Ratings:

• "Rate The Shawshank Redemption 10/10 on Trakt"
• "Show my Trakt ratings"

Discovery:

• "What movies are trending on Trakt?"
• "Get personalized movie recommendations from Trakt"
• "Show me popular shows on Trakt"

Features

• ✅ Watchlist Management: Add, remove, and view watchlist items
• ✅ Search: Find movies and shows by title
• ✅ History Tracking: Mark items as watched and view history
• ✅ Collection Management: Track your physical and digital media
• ✅ Ratings: Rate content on a 1-10 scale
• ✅ Discovery: Get trending, popular, and personalized recommendations
• ✅ OAuth Authentication: Secure API access
• ✅ Rate Limiting: Respects Trakt API limits

How It Works

The skill teaches the OpenClaw agent to:

1. Use curl commands with proper Trakt API headers
2. Format requests with correct JSON payloads
3. Handle authentication using OAuth tokens
4. Parse responses and present information to users

The agent automatically:

• Injects environment variables into commands
• Constructs appropriate API requests
• Handles errors and rate limits
• Formats responses in a user-friendly way

Skill Structure

trakt-openclaw/
├── SKILL.md              # Main skill file (AgentSkills format)
├── get_trakt_token.sh    # OAuth helper script
└── README.md             # This file

API Endpoints

The skill covers these main Trakt API endpoints:

• Sync: /sync/watchlist, /sync/history, /sync/collection, /sync/ratings
• Search: /search/movie, /search/show
• Discovery: /movies/trending, /movies/popular, /recommendations/movies
• Shows: /shows/trending, /shows/popular, /recommendations/shows

Full API documentation: https://trakt.docs.apiary.io/

Rate Limits

• Authenticated (per user): 1000 GET requests per 5 minutes, 1 POST/PUT/DELETE per second
• Unauthenticated (per app): 1000 GET requests per 5 minutes

Token Refresh

Access tokens expire after 3 months. To refresh:

curl -X POST https://api.trakt.tv/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "'"$TRAKT_REFRESH_TOKEN"'",
    "client_id": "'"$TRAKT_CLIENT_ID"'",
    "client_secret": "'"$TRAKT_CLIENT_SECRET"'",
    "redirect_uri": "urn:ietf:wg:oauth:2.0:oob",
    "grant_type": "refresh_token"
  }'

Update your config with the new tokens.

Publishing to ClawHub

To share this skill with the community:

npm install -g clawhub
clawhub login
clawhub publish . --slug trakt --name "Trakt" --version 1.0.0 --tags latest

Troubleshooting

Skill not loading:

• Check ~/.openclaw/skills/trakt/SKILL.md exists
• Verify permissions: chmod +r SKILL.md
• Restart OpenClaw session

Authentication errors:

• Verify environment variables are set in config
• Check token hasn't expired (3 month lifetime)
• Re-run get_trakt_token.sh if needed

Rate limiting:

• Wait 5 minutes before retrying
• Reduce request frequency
• Check Trakt API status

Resources

• Trakt API Documentation
• Trakt Applications
• AgentSkills Specification
• OpenClaw Documentation
• ClawHub Registry

License

MIT

Contributing

Contributions welcome! This is an AgentSkill, so improvements to the SKILL.md file - better examples, clearer instructions, or additional API coverage - are most valuable.