twentythree-skills 1.0.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twentythree-skills",
-  "version": "1.0.0",
+  "version": "1.3.0",
   "description": "AI agent skills for the TwentyThree CLI",
   "license": "MIT",
   "author": "TwentyThree",

package/skills/SKILL.md

@@ -4,7 +4,7 @@ description: |
   Full TwentyThree video platform CLI. Use when the user asks to upload or manage
   videos, run webinars, query analytics, manage audiences, configure players,
   create categories, manage tags, spots, thumbnails, webhooks, collectors, polls,
-  presentations, or any TwentyThree platform operation. Covers 235+ API commands
+  presentations, or any TwentyThree platform operation. Covers 238+ API commands
   across 22 resource groups plus meta commands (auth, workspace, autocomplete, doctor).
   Every command supports --json for machine-readable output and --agent for
   self-describing metadata (api_endpoint, auth_scope, output_shape, side_effects).
@@ -25,7 +25,7 @@ compatibility: Requires twentythree-cli installed globally (npm install -g twent
 
 # TwentyThree CLI
 
-> Terminal access to the full TwentyThree video platform API — videos, webinars, analytics, audiences, and every related resource. 235+ commands across 22 resource groups.
+> Terminal access to the full TwentyThree video platform API — videos, webinars, analytics, audiences, and every related resource. 238+ commands across 22 resource groups.
 >
 > Always use `--json` in agentic contexts for structured output. Always run `twentythree <command> --agent` before calling an unfamiliar command to discover its flags, API endpoint, auth scope, and side effects.
 
@@ -121,6 +121,16 @@ Always check `auth_scope` and `side_effects` before write/admin operations.
 - **After upload or create, the CLI prints the new resource ID and its admin URL.** Use the ID for follow-up updates (e.g. setting thumbnail, publishing).
 - **On persistent errors, run `twentythree doctor`** to diagnose auth, connectivity, and dependency issues.
 
+## Behavioral Guide
+
+Before executing multi-step workflows, read [`guide.md`](guide.md) for cross-cutting rules.
+The guide covers two categories:
+
+- **Correctness Rules** — must-follow rules that prevent API errors (object type differentiation, no `webinar get`, webinar creation defaults, timezone handling, admin link construction)
+- **Preference Rules** — best-practice rules that improve output quality (thumbnails from listing responses, analytics via listing flags, filtering/sorting on listing endpoints)
+
+> See [`guide.md`](guide.md) for the full rule list with examples.
+
 ## Resource Index
 
 All 22 resource groups. Every topic supports `--agent`, `--json`, and `--workspace`.
@@ -135,11 +145,11 @@ All 22 resource groups. Every topic supports `--agent`, `--json`, and `--workspa
 | `action` | `list`, `create`, `get`, `update`, `delete` + subtypes | Interactive overlays, CTAs inside videos |
 | `collector` | `list`, `create`, `delete` | Lead capture forms |
 | `comment` | `list`, `create`, `get`, `update`, `delete` | Video comments moderation |
-| `player` | `list`, `create`, `get`, `update`, `delete` | Player configuration and theming |
+| `player` | `list`, `create`, `get`, `update`, `delete`, `set-thumbnail`, `remove-thumbnail` | Player configuration, theming, and custom thumbnails |
 | `poll` | `list`, `create`, `get`, `update`, `delete` | In-video polls |
 | `spot` | `list`, `create`, `get`, `update`, `delete` | Hotspot annotations on videos |
 | `tag` | `list`, `create` | Content tagging |
-| `thumbnail` | `list`, `create`, `get`, `update`, `delete` | Video thumbnail management |
+| `thumbnail` | `list`, `create`, `get`, `update`, `delete`, `preview-scss` | Video thumbnail and template management |
 | `webhook` | `list`, `create`, `get`, `update`, `delete` | Event webhooks |
 | `app` | `list`, `thumbnail`, `create`, `get`, `update`, `delete` | App/integration management |
 | `presentation` | `list` + page/setting subtopics | Presentation content |
@@ -168,7 +178,7 @@ These are not in the 22 resource groups — they are CLI-local utilities:
 ```bash
 # 1. Upload (chunked upload is automatic)
 twentythree video upload ./video.mp4 --title "Product Demo" --json
-#    => prints { "id": "<video-id>", "admin_url": "..." }
+#    => prints { "data": { "id": "<video-id>", "admin_url": "..." } }
 
 # 2. Assign to a category (API: album)
 twentythree video update <video-id> --category-id <cat-id> --json
@@ -177,18 +187,20 @@ twentythree video update <video-id> --category-id <cat-id> --json
 twentythree thumbnail create --video-id <video-id> --time 5 --json
 
 # 4. Publish
-twentythree video update <video-id> --published 1 --json
+twentythree video update <video-id> --publish --json
 ```
 
 ### Webinar Setup
 
 ```bash
 # 1. Create the webinar (API: live)
-twentythree webinar create --title "Q2 Kickoff" --scheduled-at "2026-05-01T14:00:00Z" --json
-#    => prints { "id": "<webinar-id>", "admin_url": "..." }
+twentythree webinar create --title "Q2 Kickoff" --live-date "2026-05-01T14:00:00Z" --json
+#    => prints { "data": { "id": "<webinar-id>", "admin_url": "..." } }
 
-# 2. Fetch room URL and stream key
-twentythree webinar get <webinar-id> --json
+# 2. Fetch room URL and stream key — use webinar list --search since there is no webinar get
+twentythree webinar list --search "Q2 Kickoff" --json
+# Then use webinar room connect for the stream key specifically:
+twentythree webinar room connect <webinar-id> --json
 
 # 3. Start an associated session when the event begins
 twentythree session list --webinar-id <webinar-id> --json

package/skills/guide.md

@@ -0,0 +1,116 @@
+---
+name: guide
+description: Cross-cutting behavioral rules for the TwentyThree CLI — correctness rules that prevent API errors and preference rules that improve output quality.
+---
+
+# TwentyThree CLI — Behavioral Guide
+
+> Cross-cutting rules for agentic CLI use. Rules in this guide apply across all resource topics.
+> **Correctness Rules** prevent API errors. **Preference Rules** improve output quality.
+
+## Correctness Rules
+
+These rules must be followed to avoid API errors or incorrect data.
+
+### Object Type Differentiation
+
+Use `--object-type photo` for videos and `--object-type live` for webinars when calling `comment`, `poll`, `spot`, or other multi-object topics.
+
+```bash
+# Comments on a video — object-type is photo (CLI maps video -> API photo)
+twentythree comment list --object-id <video-id> --object-type photo --json
+
+# Comments on a webinar — object-type is live (CLI maps webinar -> API live)
+twentythree comment list --object-id <webinar-id> --object-type live --json
+```
+
+---
+
+### Retrieve Webinars with webinar list --search
+
+There is no `webinar get` command. Retrieve a specific webinar by passing its title to `webinar list --search`, or fetch all and filter by ID client-side.
+
+```bash
+twentythree webinar list --search "Q2 Town Hall" --json
+```
+
+---
+
+### Webinar Creation Defaults
+
+Verify publication and draft flags when creating webinars — the defaults may not match your intent. Pass `--publish` to make the webinar immediately visible or `--draft` to hold it unpublished. Run `twentythree webinar create --agent` to confirm all available access flags before creating.
+
+```bash
+# Create a published webinar explicitly
+twentythree webinar create --title "Product Launch" --live-date "2026-06-01T14:00:00Z" --publish --json
+
+# Create a draft webinar for review before publishing
+twentythree webinar create --title "Internal Update" --draft --json
+```
+
+---
+
+### Timezone Handling
+
+Always specify `--live-date` in ISO 8601 UTC format (ending in `Z`) to avoid timezone ambiguity when scheduling webinars or time-sensitive events.
+
+```bash
+twentythree webinar create --title "Launch Event" --live-date "2026-06-01T14:00:00Z" --json
+```
+
+---
+
+### Admin Link Construction
+
+The `--json` response after every upload or create includes `data.admin_url`. Use that value directly for admin deep links — never construct admin URLs by concatenating domain and ID.
+
+```bash
+# Upload a video and capture the admin URL from the response
+RESPONSE=$(twentythree video upload ./video.mp4 --title "Demo" --json)
+echo "Admin URL: $(echo $RESPONSE | jq -r '.data.admin_url')"
+```
+
+---
+
+## Preference Rules
+
+These rules are best practice. Following them improves output quality and agent efficiency.
+
+### Thumbnails from Listing Response
+
+When you need a video's thumbnail URL, prefer `video list --json` — the response includes thumbnail fields. Avoid a separate `thumbnail list` call when the listing data is sufficient.
+
+```bash
+# Thumbnail fields (thumbnail_*) are embedded in list output — no extra call needed
+twentythree video list --limit 10 --json | jq '.data[] | {id, title, thumbnail_small_url, thumbnail_medium_url}'
+```
+
+---
+
+### Prefer Listing Endpoints for Richer Data
+
+Combine `--limit`, `--all`, and available filter flags to retrieve exactly the data you need in a single call, reducing round trips. Check `--agent` output to discover all available filter flags before writing client-side filtering logic.
+
+```bash
+# Fetch all videos with filtering and extraction in one pipeline
+twentythree video list --all --json | jq '.data[] | {id, title, status}'
+
+# List upcoming webinars in one call — no client-side status filtering needed
+twentythree webinar list --status upcoming --all --json
+```
+
+---
+
+### Filtering and Sorting on Listing Endpoints
+
+Apply filtering and sorting via CLI flags on listing commands rather than fetching all results and filtering client-side. Check `--agent` output for available filter flags before writing client-side filtering logic.
+
+```bash
+# Filter webinars by status on the server — avoid fetching all and filtering locally
+twentythree webinar list --status upcoming --limit 10 --json
+
+# Include unpublished videos using a listing flag
+twentythree video list --limit 20 --include-unpublished --json
+```
+
+---

package/skills/reference/video.md

@@ -27,6 +27,8 @@ Verify: `twentythree auth status --json`
 
 After upload the CLI prints the new video ID and its admin URL. Capture `data.id` and `data.admin_url` from the `--json` response.
 
+> **Note:** The `--json` response includes `data.admin_url` — read it from the response directly. Do not construct admin URLs manually. See [guide.md](../guide.md) for the Admin Link Construction rule.
+
 | Flag | Required | Default | Description |
 |------|----------|---------|-------------|
 | `--title` | no | — | Title for the uploaded video |
@@ -51,6 +53,8 @@ twentythree video upload ./video.mp4 --title "Q2 Keynote" --category-id <cat-id>
 
 **Auth scope:** read  **Side effects:** none  **Output:** table (ID, Title, Duration, Status, Published, Updated)
 
+> **Note:** For analytics and thumbnail data, prefer including them in the listing call rather than making separate command calls. See [guide.md](../guide.md) for Preference Rules.
+
 | Flag | Required | Default | Description |
 |------|----------|---------|-------------|
 | `--limit` | no | — | Maximum number of videos to return (default: all) |
@@ -70,6 +74,8 @@ twentythree video list --limit 20 --include-unpublished --json
 
 **Auth scope:** read  **Side effects:** none  **Output:** key-value
 
+> **Note:** Thumbnail URLs are included in `video list --json` output — prefer the listing response when you already have it. See [guide.md](../guide.md) for the Thumbnails from Listing Response rule.
+
 No additional flags — pass the video ID as a positional argument.
 
 ```bash

package/skills/reference/webinar.md

@@ -26,6 +26,8 @@ Verify: `twentythree auth status --json`
 
 **Auth scope:** write  **Side effects:** creates  **Output:** key-value (id + admin_url)
 
+> **Note:** Set access visibility explicitly when creating webinars — defaults may not match your intent. Pass `--publish` or `--draft` to control visibility. The `--json` response includes `data.admin_url`; read it from the response rather than constructing URLs. See [guide.md](../guide.md) for Webinar Creation Defaults and Admin Link Construction rules.
+
 After create, the CLI prints the new webinar ID and its admin URL. Capture `data.id` and `data.admin_url` from the `--json` response.
 
 | Flag | Required | Default | Description |
@@ -52,6 +54,8 @@ twentythree webinar create --title "Product Launch" --live-date "2026-05-15T16:0
 
 **Auth scope:** read  **Side effects:** none  **Output:** table (ID, Title, Status, Date, Private)
 
+> **Note:** To retrieve a specific webinar, use `--search "<title>"` and filter client-side — there is no `webinar get` command. See [guide.md](../guide.md).
+
 | Flag | Required | Default | Description |
 |------|----------|---------|-------------|
 | `--limit` | no | 20 | Maximum number of webinars to return |