ryot - SKILL.md Agent Skill

name: ryot description: Complete Ryot media tracker with progress tracking, reviews, collections, analytics, calendar, and automated daily/weekly reports. Track TV shows, movies, books, anime, games with full GraphQL API integration. metadata: credentials: required: - name: RYOT_CONFIG description: Config file at /home/node/clawd/config/ryot.json with "url" (Ryot instance URL) and "api_token" (API authentication token) path: /home/node/clawd/config/ryot.json format: | { "url": "https://your-ryot-instance.com", "api_token": "your_api_token_here" }

Ryot Media Tracker - Complete Suite

Full-featured Ryot integration with progress tracking, reviews, collections, analytics, calendar, and automated reports.

Setup (Required)

Before using this skill, you must configure your Ryot instance:

Create config file at /home/node/clawd/config/ryot.json:

{
  "url": "https://your-ryot-instance.com",
  "api_token": "your_api_token_here"
}

Set your Ryot instance URL - Replace https://your-ryot-instance.com with your actual Ryot server address
Get your API token from your Ryot instance settings
Save the config - The skill will read this file automatically

Usage

Use scripts/ryot_api.py for all Ryot operations.

🚀 Quick Start - Automated Setup

cd /home/node/clawd/skills/ryot/scripts
./setup-automation.sh

This will:

✅ Set up daily upcoming episodes notification (07:30)
✅ Set up weekly stats report (Monday 08:00)
✅ Set up daily recent activity (20:00)
✅ Configure WhatsApp delivery

Common Tasks

1. Progress Tracking 📊

# Check your progress on a TV show
python3 scripts/ryot_api.py progress met_XXXXX

# Example output:
# Galaxy Express 999
# Season 1, Episode 35/113 (30%)

2. Reviews & Ratings ⭐

# Add review with rating (0-100)
python3 scripts/ryot_reviews.py add met_XXXXX 85 "Amazing show!"

# Rating only
python3 scripts/ryot_reviews.py add met_XXXXX 90

3. Collections 📚

# List your collections
python3 scripts/ryot_collections.py list

# Create new collection
python3 scripts/ryot_collections.py create "Top Anime 2026" "My favorite anime of the year"

# Add media to collection
python3 scripts/ryot_collections.py add <collection_id> met_XXXXX

4. Analytics & Stats 📈

# View your statistics
python3 scripts/ryot_stats.py analytics
# Output: Total media, shows, movies, watch time

# Recently consumed
python3 scripts/ryot_stats.py recent
# Output: Last 10 media you watched/read

5. Calendar & Upcoming 📅

# Upcoming episodes this week
python3 scripts/ryot_calendar.py upcoming

# Calendar for next 30 days
python3 scripts/ryot_calendar.py calendar 30

6. Search & Details 🔍

# Search for TV shows
python3 scripts/ryot_api.py search "The Wire" --type SHOW

# Search for movies
python3 scripts/ryot_api.py search "Inception" --type MOVIE

# Get details
python3 scripts/ryot_api.py details met_XXXXX

7. Mark as Completed ✅

# Mark media as completed
python3 scripts/ryot_api.py complete met_XXXXX

8. Bulk Episode Marking 🎬

# Search for a show to get metadata_id
python3 scripts/ryot-mark-episodes.py search "Galaxy Express 999"
# Output: Found: met_huCCEo1Pu0xM (source: TMDB, type: SHOW)

# Mark range of episodes as watched (e.g., episodes 1-46 of season 1)
python3 scripts/ryot-mark-episodes.py met_huCCEo1Pu0xM 1 1 46
# Marks all episodes from 1 to 46 in season 1

# Mark single season episodes
python3 scripts/ryot-mark-episodes.py met_XXXXX 2 1 24
# Marks season 2, episodes 1-24

Use cases:

Catching up on a series you've already watched elsewhere
Bulk importing viewing history
Marking entire seasons at once

Note: Each episode is marked individually with createNewInProgress + showSeasonNumber/showEpisodeNumber.

Workflow

User request → "How many episodes of Galaxy Express 999 have I watched?"
Search → Find the correct metadata ID
Check progress → python3 scripts/ryot_api.py progress met_XXX
Mark complete → When finished, deploy bulk progress update

Media Types

Supported lot values:

SHOW - TV series
MOVIE - Films
BOOK - Books
ANIME - Anime series
GAME - Video games

Important Notes

Before first use: Check if /home/node/clawd/config/ryot.json exists. If not, ask the user for their Ryot instance URL and API token, then create the config file.
Always search first to get the correct metadata ID
Verify the year if multiple results match the title
The API uses GraphQL at /backend/graphql
Metadata IDs start with met_

Resources

scripts/ryot_api.py

Python script for Ryot GraphQL operations. Supports:

search - Find media by title
details - Get metadata details
complete - Mark as completed