twentythree-skills 1.0.0

package/skills/reference/site.md

@@ -0,0 +1,94 @@
+---
+name: site
+description: Query workspace-level information (domain, quotas) and run cross-content search.
+---
+
+# TwentyThree Site Commands
+
+> Retrieve workspace-level configuration and run cross-content search across videos, webinars,
+> and categories in a single call. Always use `--json` in agentic contexts for structured output.
+
+## Prerequisites
+
+Auth scope required: read (both commands).
+Run `twentythree auth credentials` if not already configured.
+Verify: `twentythree auth status --json`
+
+> For any flag not listed here, run `twentythree site <cmd> --agent` to get the complete flag list, types, and defaults.
+
+## Commands
+
+### site get
+
+**Auth scope:** read  **Side effects:** none  **Output:** key-value
+
+Returns workspace-level configuration including domain, settings, and optional quota and
+presentation data. Use `--include-quota` to check storage and bandwidth usage.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--include-presentation` | no | Include presentation settings in the response |
+| `--include-quota` | no | Include quota (storage and bandwidth) information in the response |
+
+```bash
+# Get basic workspace info
+twentythree site get --json
+
+# Get workspace info including quotas and presentation settings
+twentythree site get --include-presentation --include-quota --json
+```
+
+### site search
+
+**Auth scope:** read  **Side effects:** none  **Output:** table (Type, Title, ID)
+
+Searches across all content types (videos, webinars, categories) in the workspace in a single
+call. Returns a mixed result set with a `Type` column identifying each result's content type.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--search` | no | Search query string |
+| `--search-in` | no | Scope the search field: `title`, `description`, or `tags` (repeatable) |
+| `--selection` | no | Filter by content selection |
+| `--size` | no | Number of results to return |
+
+```bash
+# Search all content types for a keyword
+twentythree site search --search "product demo" --json
+
+# Scoped search: title and tags only, with result limit
+twentythree site search --search "q2" --search-in title --search-in tags --size 20 --json
+```
+
+## Common Patterns
+
+### Workspace health check
+
+```bash
+# Check workspace status and quota usage in one call
+twentythree site get --include-quota --json
+```
+
+### Cross-content discovery in one call
+
+```bash
+# Find all content (videos + webinars + categories) matching a term
+twentythree site search --search "onboarding" --json
+
+# Refine to title matches only, returning up to 50 results
+twentythree site search --search "onboarding" --search-in title --size 50 --json
+```
+
+### Review workspace configuration before bulk operations
+
+```bash
+# Inspect full workspace settings including presentation config
+twentythree site get --include-presentation --include-quota --json
+
+# Search for content to confirm what is available
+twentythree site search --search "webinar" --json
+```

package/skills/reference/spot.md

@@ -0,0 +1,188 @@
+---
+name: spot
+description: Create and manage embeddable video widgets (spots) that reference one or more videos.
+---
+
+# TwentyThree Spot Commands
+
+> Create and manage spots — embeddable video widgets that display curated sets of videos.
+> Always use `--json` in agentic contexts for structured output.
+
+## Prerequisites
+
+Auth scope required: read (list, check), write (create, update, delete, set-videos, reset-version).
+Run `twentythree auth credentials` if not already configured.
+Verify: `twentythree auth status --json`
+
+> Use `spot check <id>` rather than `spot get` — there is no `spot get` command.
+> For any flag not listed here, run `twentythree spot <cmd> --agent` to get the complete flag list, types, and defaults.
+
+## Commands
+
+### spot list
+
+**Auth scope:** read  **Side effects:** none  **Output:** table (ID, Name, Type, Active)
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--page` | no | Page number |
+| `--size` | no | Number of results per page |
+| `--search` | no | Search term |
+| `--spot-type` | no | Filter by spot type |
+| `--active` | no | Filter by active status (boolean) |
+| `--orderby` | no | Field to order results by |
+| `--order` | no | Sort order (asc or desc) |
+
+```bash
+# List all spots in the workspace
+twentythree spot list --json
+
+# List only active spots
+twentythree spot list --active --json
+```
+
+### spot create
+
+**Auth scope:** write  **Side effects:** creates  **Output:** key-value
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--spot-name` | yes | Name for the new spot |
+| `--spot-type` | no | Type of spot |
+| `--spot-design` | no | Design for the spot |
+| `--spot-layout` | no | Layout for the spot |
+
+```bash
+# Create a basic spot
+twentythree spot create --spot-name "Homepage Widget" --json
+
+# Create a spot with type and layout specified
+twentythree spot create --spot-name "Featured Videos" --spot-type video --spot-layout grid --json
+```
+
+### spot check
+
+**Auth scope:** read  **Side effects:** none  **Output:** key-value
+
+Takes `<spot-id>` as positional argument. Use this to retrieve spot details — there is no `spot get` command.
+
+No additional flags.
+
+```bash
+# Get details of a specific spot
+twentythree spot check <spot-id> --json
+
+# Inspect a spot before updating it
+twentythree spot check <spot-id> --json
+```
+
+### spot update
+
+**Auth scope:** write  **Side effects:** updates  **Output:** key-value
+
+Takes `<spot-id>` as positional argument.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--spot-name` | no | New name for the spot |
+| `--active` | no | Set active status (boolean) |
+
+```bash
+# Rename a spot
+twentythree spot update <spot-id> --spot-name "Updated Widget Name" --json
+
+# Deactivate a spot
+twentythree spot update <spot-id> --no-active --json
+```
+
+### spot delete
+
+**Auth scope:** write  **Side effects:** destructive  **Output:** key-value
+
+Takes `<spot-id>` as positional argument. No additional flags.
+
+```bash
+# Delete a spot
+twentythree spot delete <spot-id> --json
+
+# Delete a spot that is no longer in use
+twentythree spot delete <spot-id> --json
+```
+
+### spot set-videos
+
+**Auth scope:** write  **Side effects:** updates  **Output:** key-value
+
+Takes `<spot-id>` as positional argument. Assigns the video playlist shown in the spot.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--videos` | yes | Comma-separated video IDs to assign to the spot |
+
+```bash
+# Assign a single video to a spot
+twentythree spot set-videos <spot-id> --videos "<video-id>" --json
+
+# Assign multiple videos to a spot
+twentythree spot set-videos <spot-id> --videos "<video-id-1>,<video-id-2>,<video-id-3>" --json
+```
+
+### spot reset-version
+
+**Auth scope:** write  **Side effects:** updates  **Output:** key-value
+
+Takes `<spot-id>` as positional argument. Resets the spot to its initial version state. No additional flags.
+
+```bash
+# Reset a spot's version
+twentythree spot reset-version <spot-id> --json
+
+# Use after a spot update goes wrong to restore default state
+twentythree spot reset-version <spot-id> --json
+```
+
+## Common Patterns
+
+### Create a spot and attach videos
+
+```bash
+# Step 1: Create the spot
+twentythree spot create --spot-name "Homepage Videos" --json
+
+# Step 2: Assign videos to the spot using the ID from step 1
+twentythree spot set-videos <spot-id> --videos "<video-id-1>,<video-id-2>,<video-id-3>" --json
+
+# Step 3: Verify the spot configuration
+twentythree spot check <spot-id> --json
+```
+
+### Find and inspect active spots
+
+```bash
+# List only active spots
+twentythree spot list --active --json
+
+# Get full details of a specific spot
+twentythree spot check <spot-id> --json
+```
+
+### Update a spot's video playlist
+
+```bash
+# Get current spot details to see existing video assignment
+twentythree spot check <spot-id> --json
+
+# Replace the video playlist with a new set
+twentythree spot set-videos <spot-id> --videos "<new-video-id-1>,<new-video-id-2>" --json
+
+# Activate the spot if it was inactive
+twentythree spot update <spot-id> --active --json
+```

package/skills/reference/tag.md

@@ -0,0 +1,93 @@
+---
+name: tag
+description: List and discover content tags. Tags are created implicitly via video update --tags.
+---
+
+# TwentyThree Tag Commands
+
+> Discover and explore content tags on TwentyThree. The tag topic is read-only — tags are created
+> implicitly when applied to videos. Always use `--json` in agentic contexts for structured output.
+
+## Prerequisites
+
+Auth scope required: anonymous (both commands — no auth token required).
+Run `twentythree auth credentials` if not already configured.
+Verify: `twentythree auth status --json`
+
+> For any flag not listed here, run `twentythree tag <cmd> --agent` to get the complete flag list, types, and defaults.
+
+> **Note:** To add or remove tags from content, use `video update --tags` or `webinar update --tags`. The `tag` topic itself is read-only.
+
+## Commands
+
+### tag list
+
+**Auth scope:** anonymous  **Side effects:** none  **Output:** table (Tag, Count)
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--search` | no | Filter tags by a search string |
+| `--exclude-machine-tags` | no | Exclude machine-generated tags from the results |
+| `--only-machine-tags` | no | Return only machine tags (overrides --exclude-machine-tags) |
+| `--only-published` | no | Return only tags from published videos |
+| `--orderby` | no | Order tags by this value |
+| `--order` | no | Sort order for the results |
+
+```bash
+# List all tags in the workspace
+twentythree tag list --json
+
+# Find tags matching a search term, ordered by usage count
+twentythree tag list --search "product" --orderby count --order desc --json
+```
+
+### tag related
+
+**Auth scope:** anonymous  **Side effects:** none  **Output:** table (Tag)
+
+Takes `<tag>` as a positional argument. No additional flags.
+
+```bash
+# Discover tags related to a specific tag
+twentythree tag related "product" --json
+
+# Find tags related to a topic for content discovery
+twentythree tag related "webinar" --json
+```
+
+## Common Patterns
+
+### Content discovery by tag
+
+```bash
+# Step 1: Find tags that match a topic
+twentythree tag list --search "onboarding" --only-published --json
+
+# Step 2: Explore related tags to broaden content discovery
+twentythree tag related "onboarding" --json
+
+# Step 3: Use found tags to filter video search via video list
+twentythree video list --json | jq '.[] | select(.tags | contains("onboarding"))'
+```
+
+### Audit all tags in the workspace
+
+```bash
+# List all tags sorted by usage count (most used first)
+twentythree tag list --orderby count --order desc --json
+
+# List only human-authored tags (exclude machine-generated)
+twentythree tag list --exclude-machine-tags --orderby count --order desc --json
+```
+
+### Apply tags to a video (write operation — not a tag command)
+
+```bash
+# Tags are managed via video update, not the tag topic
+twentythree video update <video-id> --tags "product demo tutorial" --json
+
+# Then verify the tags were applied
+twentythree tag list --search "demo" --only-published --json
+```

package/skills/reference/thumbnail.md

@@ -0,0 +1,224 @@
+---
+name: thumbnail
+description: Manage thumbnail templates (Liquid-based) used to render video thumbnails with metadata variables.
+---
+
+# TwentyThree Thumbnail Commands
+
+> Create and manage Liquid-based thumbnail templates for rendering video and webinar thumbnails.
+> Always use `--json` in agentic contexts for structured output.
+
+## Prerequisites
+
+Auth scope required: read (list, data, file list), write (add, update, delete, duplicate, file upload, file delete).
+Run `twentythree auth credentials` if not already configured.
+Verify: `twentythree auth status --json`
+
+Thumbnail templates use Liquid templating with video metadata variables. Use `thumbnail data` to preview the render variables before authoring a template.
+
+> For any flag not listed here, run `twentythree thumbnail <cmd> --agent` to get the complete flag list, types, and defaults.
+
+## Commands
+
+### thumbnail list
+
+**Auth scope:** read  **Side effects:** none  **Output:** table (ID, Name, Type, Width, Height)
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--search` | no | Filter by template name |
+| `--object-type` | no | Filter by object type (photo, live, liveseries) |
+
+```bash
+# List all thumbnail templates
+twentythree thumbnail list --json
+
+# List templates scoped to video objects
+twentythree thumbnail list --object-type photo --json
+```
+
+### thumbnail add
+
+**Auth scope:** write  **Side effects:** creates  **Output:** key-value (template ID)
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--name` | yes | Name for the new thumbnail template |
+| `--liquid-template` | yes | Liquid template HTML content |
+
+```bash
+# Create a minimal thumbnail template
+twentythree thumbnail add --name "Simple Title" --liquid-template "<div>{{ photo.title }}</div>" --json
+
+# Create a branded template with metadata
+twentythree thumbnail add --name "Brand Template" --liquid-template "<html><body><h1>{{ photo.title }}</h1><p>{{ photo.one }}</p></body></html>" --json
+```
+
+### thumbnail update
+
+**Auth scope:** write  **Side effects:** updates  **Output:** key-value
+
+Takes `<template-id>` as positional argument.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--name` | no | New name for the template |
+| `--liquid-template` | no | New Liquid template HTML content |
+| `--object-type` | no | Object type (photo, live, liveseries) |
+| `--width` | no | Template width in pixels |
+| `--height` | no | Template height in pixels |
+
+```bash
+# Rename a thumbnail template
+twentythree thumbnail update <template-id> --name "Brand Template v2" --json
+
+# Update template content and dimensions
+twentythree thumbnail update <template-id> --liquid-template "<div>{{ photo.title }}</div>" --width 1280 --height 720 --json
+```
+
+### thumbnail delete
+
+**Auth scope:** write  **Side effects:** destructive  **Output:** key-value
+
+Takes `<template-id>` as positional argument. No additional flags.
+
+```bash
+# Delete a thumbnail template
+twentythree thumbnail delete <template-id> --json
+
+# Delete an unused template
+twentythree thumbnail delete <template-id> --json
+```
+
+### thumbnail duplicate
+
+**Auth scope:** write  **Side effects:** creates  **Output:** key-value (new template ID)
+
+Takes `<template-id>` as positional argument.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--name` | no | Name for the duplicate |
+
+```bash
+# Duplicate a template (uses auto-generated name)
+twentythree thumbnail duplicate <template-id> --json
+
+# Duplicate a template with a new name
+twentythree thumbnail duplicate <template-id> --name "Brand v2" --json
+```
+
+### thumbnail data
+
+**Auth scope:** read  **Side effects:** none  **Output:** key-value (Liquid render variables)
+
+Takes `<template-id>` as positional argument. Returns the variables available for use in the template's Liquid markup when rendering for a given object.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--object-id` | yes | Video or webinar ID to get render data for |
+
+```bash
+# Preview Liquid render data for a video
+twentythree thumbnail data <template-id> --object-id <video-id> --json
+
+# Inspect render variables before authoring a template
+twentythree thumbnail data <template-id> --object-id <video-id> --json
+```
+
+## Subtopic: thumbnail file
+
+Manage image files attached to thumbnail templates. These files can be referenced inside Liquid templates as static assets.
+
+### thumbnail file list
+
+**Auth scope:** read  **Side effects:** none  **Output:** table (Filename, Size, URL)
+
+Takes `<template-id>` as positional argument. No additional flags.
+
+```bash
+# List files attached to a thumbnail template
+twentythree thumbnail file list <template-id> --json
+
+# View all assets available to a template
+twentythree thumbnail file list <template-id> --json
+```
+
+### thumbnail file upload
+
+**Auth scope:** write  **Side effects:** creates  **Output:** key-value
+
+Takes `<file-path>` as positional argument.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--template-id` | yes | Thumbnail template ID to attach the file to |
+
+```bash
+# Upload a logo image to a template
+twentythree thumbnail file upload ./logo.png --template-id <template-id> --json
+
+# Upload a banner image
+twentythree thumbnail file upload ./banner.jpg --template-id <template-id> --json
+```
+
+### thumbnail file delete
+
+**Auth scope:** write  **Side effects:** destructive  **Output:** key-value
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--template-id` | yes | Thumbnail template ID |
+| `--filename` | yes | Filename to delete |
+
+```bash
+# Delete a file from a thumbnail template
+twentythree thumbnail file delete --template-id <template-id> --filename logo.png --json
+
+# Remove an outdated banner image
+twentythree thumbnail file delete --template-id <template-id> --filename old-banner.jpg --json
+```
+
+## Common Patterns
+
+### Author a new thumbnail template
+
+Use `thumbnail data` to discover available Liquid variables before writing the template:
+
+```bash
+# Step 1: Preview render variables for a specific video
+twentythree thumbnail data <template-id> --object-id <video-id> --json
+
+# Step 2: Create the template using discovered variables
+twentythree thumbnail add --name "Brand Template" --liquid-template "<html><body><h1>{{ photo.title }}</h1></body></html>" --json
+```
+
+### Duplicate an existing template as a starting point
+
+```bash
+twentythree thumbnail duplicate <template-id> --name "Brand v2" --json
+```
+
+### List templates scoped to object type
+
+```bash
+# List templates for videos only
+twentythree thumbnail list --object-type photo --json
+
+# List templates for webinars
+twentythree thumbnail list --object-type live --json
+```