twentythree-skills 1.0.0

package/README.md

@@ -0,0 +1,47 @@
+# twentythree-skills
+
+AI agent skills for the [TwentyThree CLI](https://github.com/23/twentythree-cli) — installable markdown skill definitions for Claude Code, OpenAI Codex, GitHub Copilot, and Cursor.
+
+## Install
+
+```bash
+npx twentythree-skills
+```
+
+Detects your agent runtime and copies skill files into the right location automatically. Run again at any time to update — it's idempotent.
+
+**Project-local install:**
+
+```bash
+npx twentythree-skills --project
+```
+
+Installs into `.claude/skills/`, `.agents/skills/`, `.github/skills/`, or `.cursor/skills/` relative to the current directory.
+
+## What's included
+
+- `skills/SKILL.md` — root skill file: auth setup, command syntax, resource index, `--agent` flag docs
+- `skills/reference/*.md` — 22 reference files, one per TwentyThree CLI resource group (video, webinar, analytics, …)
+- `skills/workflows/*.md` — workflow files for high-value automation patterns (video upload, webinar lifecycle)
+
+## Supported runtimes
+
+| Runtime | Detection | Global install path |
+|---------|-----------|---------------------|
+| Claude Code | `~/.claude/` | `~/.claude/skills/twentythree/` |
+| OpenAI Codex | `~/.codex/` | `~/.codex/skills/twentythree/` |
+| GitHub Copilot | `~/.github/copilot/` | `~/.github/skills/twentythree/` |
+| Cursor | `~/.cursor/` | `~/.cursor/skills/twentythree/` |
+
+## Prerequisites
+
+The skills document the [twentythree-cli](https://www.npmjs.com/package/twentythree-cli). Install and authenticate it first:
+
+```bash
+npm install -g twentythree-cli
+twentythree auth credentials
+```
+
+## License
+
+MIT

package/bin/add.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// bin/add.js — TwentyThree Skills installer
+// Node.js built-ins only. ESM. No build step. Target: < 150 lines.
+
+import { existsSync, mkdirSync, cpSync, readdirSync } from 'node:fs'
+import { join, dirname, relative } from 'node:path'
+import { homedir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const skillsSource = join(__dirname, '..', 'skills')
+const home = homedir()
+const cwd = process.cwd()
+const isProject = process.argv.includes('--project')
+
+const RUNTIMES = [
+  {
+    name: 'Claude Code',
+    detect: join(home, '.claude'),
+    globalDest: join(home, '.claude', 'skills', 'twentythree'),
+    projectDest: join(cwd, '.claude', 'skills', 'twentythree'),
+  },
+  {
+    name: 'OpenAI Codex',
+    detect: join(home, '.codex'),
+    globalDest: join(home, '.codex', 'skills', 'twentythree'),
+    projectDest: join(cwd, '.agents', 'skills', 'twentythree'),
+  },
+  {
+    name: 'GitHub Copilot',
+    detect: join(home, '.github', 'copilot'),
+    globalDest: join(home, '.github', 'skills', 'twentythree'),
+    projectDest: join(cwd, '.github', 'skills', 'twentythree'),
+  },
+  {
+    name: 'Cursor',
+    detect: join(home, '.cursor'),
+    globalDest: join(home, '.cursor', 'skills', 'twentythree'),
+    projectDest: join(cwd, '.cursor', 'skills', 'twentythree'),
+  },
+]
+
+function walkDir(dir) {
+  const files = []
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isSymbolicLink()) continue
+    const full = join(dir, entry.name)
+    if (entry.isDirectory()) {
+      files.push(...walkDir(full))
+    } else {
+      files.push(full)
+    }
+  }
+  return files
+}
+
+function shortPath(abs) {
+  if (abs.startsWith(home)) return '~' + abs.slice(home.length)
+  if (abs.startsWith(cwd + '/')) return '.' + abs.slice(cwd.length)
+  if (abs === cwd) return '.'
+  return abs
+}
+
+function installTo(destRoot, label) {
+  mkdirSync(destRoot, { recursive: true })
+  console.log(`\n${label}`)
+  for (const absFile of walkDir(skillsSource)) {
+    const rel = relative(skillsSource, absFile)
+    const destFile = join(destRoot, rel)
+    mkdirSync(dirname(destFile), { recursive: true })
+    try {
+      cpSync(absFile, destFile, { dereference: false })
+      console.log(`  ✓ ${rel}`)
+    } catch (err) {
+      console.error(`  ✗ Error installing ${rel}: ${err.message}`)
+      process.exitCode = 1
+    }
+  }
+}
+
+if (!existsSync(skillsSource)) {
+  console.error('Skills source directory not found. The package may be corrupted.')
+  process.exit(1)
+}
+
+const detected = RUNTIMES.filter(r => existsSync(r.detect))
+
+if (detected.length === 0) {
+  const checked = RUNTIMES.map(r => shortPath(r.detect)).join('  ')
+  console.log('No supported agent runtime detected.\n')
+  console.log(`Checked: ${checked}\n`)
+  console.log('Install manually or see: https://www.npmjs.com/package/twentythree-skills')
+  process.exit(0)
+}
+
+for (const runtime of detected) {
+  const dest = isProject ? runtime.projectDest : runtime.globalDest
+  const label = `${runtime.name} (${shortPath(dest)}/)`
+  installTo(dest, label)
+}
+
+console.log('\nDone.')
+process.exit(process.exitCode ?? 0)

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "twentythree-skills",
+  "version": "1.0.0",
+  "description": "AI agent skills for the TwentyThree CLI",
+  "license": "MIT",
+  "author": "TwentyThree",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/23/twentythree-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/23/twentythree-cli/issues"
+  },
+  "homepage": "https://github.com/23/twentythree-cli#readme",
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "bin": {
+    "twentythree-skills": "./bin/add.js"
+  },
+  "files": [
+    "/bin",
+    "/skills",
+    "/README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "ai",
+    "skills",
+    "twentythree",
+    "cli",
+    "agent",
+    "claude",
+    "claude-code",
+    "copilot",
+    "cursor",
+    "codex",
+    "ai-agent"
+  ],
+  "scripts": {
+    "test": "node scripts/validate-skills.mjs"
+  }
+}

package/skills/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: twentythree
+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
+  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).
+triggers:
+  - upload video
+  - manage videos
+  - webinar
+  - live event
+  - analytics
+  - twentythree
+  - video platform
+  - TwentyThree CLI
+invocable: true
+argument-hint: "<topic> <verb> [flags]"
+allowed-tools: Bash(twentythree *)
+compatibility: Requires twentythree-cli installed globally (npm install -g twentythree-cli). Node.js >=22.
+---
+
+# 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.
+>
+> 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.
+
+## Prerequisites: Authentication
+
+Before any command, configure credentials once per workspace:
+
+```bash
+twentythree auth credentials
+```
+
+Prompts interactively for:
+- **Domain** — your workspace domain (e.g. `company.video.twentythree.com`)
+- **Bearer token** — copy from `Settings → API` inside your TwentyThree workspace admin
+
+Credentials are stored in the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) — never in plaintext files.
+
+Verify auth is working:
+
+```bash
+twentythree auth status
+```
+
+### Multi-Workspace
+
+The CLI supports multiple workspaces simultaneously:
+
+```bash
+twentythree workspace list                   # Show all configured workspaces
+twentythree workspace use <domain>           # Set the active workspace
+twentythree <command> --workspace <domain>   # One-off override for a single call
+```
+
+## Command Syntax
+
+```
+twentythree <topic> <verb> [flags]
+```
+
+Global flags available on every command:
+
+| Flag | Purpose |
+|------|---------|
+| `--json` | Machine-readable JSON output — always use in agentic contexts |
+| `--agent` | Return machine-readable command metadata (no API call made) |
+| `--workspace <domain>` | Target a specific workspace for this call only |
+
+## Self-Discovery: The `--agent` Flag
+
+Before calling any command you haven't used recently, introspect it:
+
+```bash
+twentythree video upload --agent
+```
+
+Returns JSON:
+
+```json
+{
+  "command": "video:upload",
+  "description": "Upload a video file",
+  "flags": [
+    { "name": "title", "type": "option", "required": true, "description": "..." },
+    { "name": "category-id", "type": "option", "required": false, "description": "..." }
+  ],
+  "examples": ["twentythree video upload ./file.mp4 --title \"Demo\""],
+  "api_endpoint": "POST /photo/redeem-upload-token",
+  "auth_scope": "write",
+  "output_shape": { "type": "key-value" },
+  "side_effects": "creates"
+}
+```
+
+Key fields returned by `--agent`:
+
+- **`api_endpoint`** — the underlying REST endpoint (note terminology mapping below)
+- **`auth_scope`** — one of `anonymous`, `none`, `read`, `write`, `admin`, `super`
+- **`output_shape`** — `{ type: "table", columns: [...] }`, `{ type: "key-value" }`, or `{ type: "none" }`
+- **`side_effects`** — `none`, `creates`, `updates`, or `destructive`
+- **`flags`** — the complete flag list with types, defaults, and required-ness
+
+Always check `auth_scope` and `side_effects` before write/admin operations.
+
+## Key Invariants
+
+- **Use `--json` in agentic contexts.** Human-formatted tables are the default; agents should always request JSON.
+- **File uploads use chunked upload automatically.** Never construct multipart requests directly — `twentythree video upload <file>` handles chunking under the hood.
+- **Terminology mapping** — the CLI uses product-domain names while the API uses legacy names:
+  - CLI `video` ↔ API `photo`
+  - CLI `category` ↔ API `album`
+  - CLI `webinar` ↔ API `live`
+  - The `api_endpoint` field in `--agent` output shows the actual API path.
+- **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.
+
+## Resource Index
+
+All 22 resource groups. Every topic supports `--agent`, `--json`, and `--workspace`.
+
+| Topic | Representative verbs | Use for |
+|-------|---------------------|---------|
+| `video` | `upload`, `list`, `get`, `update`, `delete`, `replace`, `frame`, `transcoding-progress` | Video file management, upload, metadata, thumbnails |
+| `webinar` | `create`, `list`, `get`, `update`, `delete`, `repeat`, `highlights`, `clips`, `metrics`, `log` + attachment/mail/queued-video/recording/room/section/series/speaker/transcription subtopics | Live events, scheduling, recordings, attendee comms |
+| `analytics` | `conversions`, `live`, `usage`, `video` subtopics (many verbs each) | Reporting, viewer data, playback metrics, conversion tracking |
+| `audience` | `list`, `create`, `get`, `update`, `delete` + segment ops | Audience segmentation and targeting |
+| `category` | `list`, `create`, `get`, `update`, `delete` | Content organization (API: albums) |
+| `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 |
+| `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 |
+| `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 |
+| `protection` | `list`, `create`, `delete` | Access protection |
+| `session` | `list`, `get` | Viewer session data |
+| `setting` | `get` | Workspace settings |
+| `site` | `list`, `search` | Site-level operations |
+| `openupload` | `list`, `create`, `delete` | Open upload tokens |
+| `user` | `list`, `create`, `get`, `update`, `delete` | User management |
+
+## Meta Commands
+
+These are not in the 22 resource groups — they are CLI-local utilities:
+
+| Topic | Commands | Purpose |
+|-------|----------|---------|
+| `auth` | `credentials`, `status` | Configure and verify bearer-token auth |
+| `workspace` | `list`, `use` | Multi-workspace selection |
+| `autocomplete` | `bash`, `zsh` | Shell completion (`twentythree autocomplete bash | source`) |
+| `doctor` | (top-level: `twentythree doctor`) | Diagnose auth, connectivity, dependency issues |
+
+## Common Workflows
+
+### Upload and Publish a Video
+
+```bash
+# 1. Upload (chunked upload is automatic)
+twentythree video upload ./video.mp4 --title "Product Demo" --json
+#    => prints { "id": "<video-id>", "admin_url": "..." }
+
+# 2. Assign to a category (API: album)
+twentythree video update <video-id> --category-id <cat-id> --json
+
+# 3. Set a thumbnail at second 5
+twentythree thumbnail create --video-id <video-id> --time 5 --json
+
+# 4. Publish
+twentythree video update <video-id> --published 1 --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": "..." }
+
+# 2. Fetch room URL and stream key
+twentythree webinar get <webinar-id> --json
+
+# 3. Start an associated session when the event begins
+twentythree session list --webinar-id <webinar-id> --json
+```
+
+## Diagnostics
+
+```bash
+twentythree doctor        # Check auth, connectivity, Node version, keychain access
+twentythree --version     # Print CLI version
+twentythree <cmd> --help  # Human-readable help for any command
+twentythree <cmd> --agent # Machine-readable metadata for any command (preferred for agents)
+```
+
+If a command fails unexpectedly, in order:
+1. `twentythree auth status` — confirm credentials are present and the workspace matches
+2. `twentythree <cmd> --agent` — confirm required flags and auth scope
+3. `twentythree doctor` — catch environmental issues
+
+See [twentythree-cli on npm](https://www.npmjs.com/package/twentythree-cli) for installation, and the GitHub repo for docs and issue reporting.

package/skills/reference/action.md

@@ -0,0 +1,233 @@
+---
+name: action
+description: Manage calls-to-action (CTAs) and interactive overlays on videos and webinars.
+---
+
+# TwentyThree Action Commands
+
+> Attach, configure, and manage interactive CTA overlays on video and webinar timelines.
+> Always use `--json` in agentic contexts for structured output.
+
+## Prerequisites
+
+Auth scope required: read (list, get, types), write (add, update, delete, exclude, include, upload).
+Run `twentythree auth credentials` if not already configured.
+Verify: `twentythree auth status --json`
+
+> For any flag not listed here, run `twentythree action <cmd> --agent` to get the complete flag list, types, and defaults.
+
+## Commands
+
+### action list
+
+**Auth scope:** read  **Side effects:** none  **Output:** table (ID, Name, Type, Start, End)
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--object-id` | no | Object ID to filter actions by |
+| `--video-id` | no | Video ID to filter actions by (maps to photo_id) |
+| `--webinar-id` | no | Webinar ID to filter actions by (maps to live_id) |
+| `--player-id` | no | Player ID to filter actions by |
+| `--exclude-internal` | no | Exclude internal actions |
+| `--exclude-pending` | no | Exclude pending actions |
+| `--exclude-items` | no | Exclude action items |
+
+```bash
+# List all actions in the workspace
+twentythree action list --json
+
+# List actions for a specific video
+twentythree action list --video-id <video-id> --json
+```
+
+### action add
+
+**Auth scope:** write  **Side effects:** creates  **Output:** key-value
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--type` | yes | Action type (use `action types` to list valid values) |
+| `--object-id` | yes | Object ID (video or webinar) to attach the action to |
+| `--fields` | no | Additional fields for the action (key=value pairs) |
+
+```bash
+# Add a basic CTA action to a video
+twentythree action add --type overlay --object-id <video-id> --json
+
+# Add a CTA with custom field values
+twentythree action add --type overlay --object-id <video-id> --fields "title=Buy Now" --json
+```
+
+### action get
+
+**Auth scope:** read  **Side effects:** none  **Output:** key-value
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--object-id` | no | Object ID context |
+| `--video-id` | no | Video ID context (maps to photo_id) |
+| `--webinar-id` | no | Webinar ID context (maps to live_id) |
+| `--token` | no | Object token for authentication |
+| `--player-id` | no | Player ID context |
+| `--exclude-internal` | no | Exclude internal actions |
+| `--exclude-pending` | no | Exclude pending actions |
+| `--exclude-items` | no | Exclude action items |
+
+```bash
+# Get details of a specific action by ID
+twentythree action get <action-id> --json
+
+# Get action in the context of a video
+twentythree action get <action-id> --video-id <video-id> --json
+```
+
+### action update
+
+**Auth scope:** write  **Side effects:** updates  **Output:** key-value
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--name` | yes | Display name for the action |
+| `--start-time` | yes | Start time of the action (seconds) |
+| `--end-time` | yes | End time of the action (seconds) |
+| `--time-relative-to` | no | What the timing is relative to (default: duration) |
+| `--return-url` | no | Return URL for the action |
+
+```bash
+# Update action timing and name
+twentythree action update <action-id> --name "Buy Now" --start-time 10 --end-time 20 --json
+
+# Update action with a click-through URL
+twentythree action update <action-id> --name "Learn More" --start-time 30 --end-time 60 --return-url "https://example.com" --json
+```
+
+### action delete
+
+**Auth scope:** write  **Side effects:** destructive  **Output:** key-value
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| (none) | — | Takes action ID as positional argument |
+
+```bash
+# Delete a CTA action
+twentythree action delete <action-id> --json
+
+# Delete with confirmation
+twentythree action delete <action-id> --json
+```
+
+### action types
+
+**Auth scope:** read  **Side effects:** none  **Output:** table (Type, Name / Description)
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--exclude-internal` | no | Exclude internal action types from the list |
+
+```bash
+# List all available action types
+twentythree action types --json
+
+# List only public action types (excluding internal)
+twentythree action types --exclude-internal --json
+```
+
+### action exclude
+
+**Auth scope:** write  **Side effects:** updates  **Output:** key-value
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--object-id` | yes | Object ID to exclude the action from |
+| `--undo` | no | Remove the exclusion (reverse this operation) |
+
+```bash
+# Exclude a CTA from a specific video
+twentythree action exclude <action-id> --object-id <video-id> --json
+
+# Undo the exclusion (re-enable the action on the video)
+twentythree action exclude <action-id> --object-id <video-id> --undo --json
+```
+
+### action include
+
+**Auth scope:** write  **Side effects:** updates  **Output:** key-value
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--object-id` | yes | Object ID to include the action on |
+| `--undo` | no | Remove the inclusion (reverse this operation) |
+
+```bash
+# Include an action on a specific video
+twentythree action include <action-id> --object-id <video-id> --json
+
+# Undo the inclusion
+twentythree action include <action-id> --object-id <video-id> --undo --json
+```
+
+### action upload
+
+**Auth scope:** write  **Side effects:** creates  **Output:** key-value
+
+Takes positional arguments: `<action-id> <variable> <file>` — no additional flags.
+
+```bash
+# Upload a banner image to an action's image variable
+twentythree action upload <action-id> image ./banner.png --json
+
+# Upload a video clip to an action's video variable
+twentythree action upload <action-id> video ./clip.mp4 --json
+```
+
+## Common Patterns
+
+### Discover types, create, and configure an action
+
+```bash
+# Step 1: List available action types to find a valid type value
+twentythree action types --exclude-internal --json
+
+# Step 2: Add the action to a video using the chosen type
+twentythree action add --type <type> --object-id <video-id> --fields "title=Click Here" --json
+
+# Step 3: Update the timing on the newly created action
+twentythree action update <action-id> --name "Click Here" --start-time 15 --end-time 45 --json
+```
+
+### Suppress a global CTA on a specific video
+
+```bash
+# List actions to find the global action ID
+twentythree action list --json
+
+# Exclude that action from the video where it should not appear
+twentythree action exclude <action-id> --object-id <video-id> --json
+```
+
+### Upload a custom image to an overlay action
+
+```bash
+# First add the action
+twentythree action add --type overlay --object-id <video-id> --json
+
+# Then upload the image file to the action variable
+twentythree action upload <action-id> image ./custom-banner.png --json
+```