trakt-readonly_skill

Overview

This skill is a read-only Trakt.tv integration that retrieves a user’s current watching item, recent episode history, watched shows list, profile, stats, and playback progress using the Trakt API. It requires a Trakt Client ID and username, and optionally an access token for playback queries. The skill focuses on safe, read-only queries and avoids modifying account data.

How this skill works

The skill calls the Trakt API endpoints at api.trakt.tv using a small shell wrapper script. It reads configuration from environment variables (Client ID, username, optional access token and client secret) and supports a device OAuth flow for read-only playback queries. Responses are validated and empty or 404 results are handled gracefully.

When to use it

• Ask what you are currently watching on Trakt.
• Fetch recent episode history for a user or analysis.
• List recently watched shows or check watch progress.
• Retrieve public profile details or aggregated stats.
• Request playback progress within a date range (requires OAuth).

Best practices

• Provide TRAKT_CLIENT_ID and TRAKT_USERNAME as environment variables before running.
• Only use TRAKT_ACCESS_TOKEN when requesting playback; never store or log tokens.
• Keep recent query limits numeric and between 1 and 100.
• Use the device OAuth flow for read-only access; do not request write scopes.
• Always validate API responses and handle empty/404 gracefully.

Example use cases

• Quickly check what a user is currently watching with the watching command.
• Retrieve the last 10 episodes watched to populate a recent activity feed.
• Generate a watched-shows list for a profile page or export.
• Fetch user stats for charts (play counts, watched time).
• Request playback records for a date range using an OAuth access token.