twentythree-skills 1.0.0 → 1.1.0

package/package.json

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

package/skills/SKILL.md

@@ -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`.
@@ -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 |