Agent skill

Watch CLI

Watch any social video → get an architecture diagram, working component, runnable notebook, or step-by-step cheat sheet — automatically.

MITAuto-check passedDevelopment

Install Watch CLI

skills CLI

$ npx skills add sonpiaz/watch-cli --skill watch-cli -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install sonpiaz/watch-cli watch-cli --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "watch-cli" agent skill from https://github.com/sonpiaz/watch-cli/tree/main into .claude/skills/watch-cli/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "watch-cli", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add sonpiaz/watch-cli --skill watch-cli -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install sonpiaz/watch-cli watch-cli --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "watch-cli" agent skill from https://github.com/sonpiaz/watch-cli/tree/main into .agents/skills/watch-cli/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "watch-cli", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add sonpiaz/watch-cli --skill watch-cli -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install sonpiaz/watch-cli watch-cli --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "watch-cli" agent skill from https://github.com/sonpiaz/watch-cli/tree/main into .cursor/skills/watch-cli/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "watch-cli", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add sonpiaz/watch-cli --skill watch-cli -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install sonpiaz/watch-cli watch-cli --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "watch-cli" agent skill from https://github.com/sonpiaz/watch-cli/tree/main into .gemini/skills/watch-cli/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "watch-cli", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install sonpiaz/watch-cli watch-cli

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add sonpiaz/watch-cli --skill watch-cli -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "watch-cli" agent skill from https://github.com/sonpiaz/watch-cli/tree/main into .github/skills/watch-cli/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "watch-cli", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add sonpiaz/watch-cli --skill watch-cli -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install sonpiaz/watch-cli watch-cli --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "watch-cli" agent skill from https://github.com/sonpiaz/watch-cli/tree/main into .opencode/skills/watch-cli/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "watch-cli", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: watch-cli
GitHub stars: 253
Token cost: ~2.1k tokens
SKILL.md length: 1,069 words
Files: 57
Skills in repo: 1
Repo updated: Sep 13, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Watch any social video → get an architecture diagram, working component, runnable notebook, or step-by-step cheat sheet — automatically.

Tasks that involve Diagrams
SKILL.md covers When to invoke, What you get back, Parse rules and Invocation, plus 3 more sections
Needs KYMA_API_KEY

What it does

Watch CLI is an agent skill from sonpiaz/watch-cli. Watch any social video → get an architecture diagram, working component, runnable notebook, or step-by-step cheat sheet — automatically.

Its SKILL.md is about 2.1k tokens, which your agent loads only when the skill is triggered. The skill folder holds 60 other files (for example `.claude-plugin/marketplace.json`, `.github/workflows/ci.yml` and `.github/workflows/release.yml`).

It sits in Development, covering Diagrams. It works with Model Context Protocol. The repository describes itself as: Gives a coding agent eyes and ears for any social video: timestamped frames plus a transcript, about 50x cheaper than sending the whole file to a multimodal API. The licence is MIT.

When your agent uses it

Tasks that involve Diagrams

Example prompts

“/watch-cli”

Requirements

A credential in KYMA_API_KEY

What it can do on your machine

Read from SKILL.md and the folder at commit 06beafb. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
No scripts in the folder and no shell commands in SKILL.md (its code samples are bash).
From the folder's file list and the shell code blocks in SKILL.md.
Network
Links to these hosts (documentation or services it may open):
- kymaapi.com
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names these keys or tokens, usually read from environment variables:
- KYMA_API_KEY
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Watch CLI loads about 2.1k tokens when it runs. Until then it costs about 37 tokens; SKILL.md has 1,069 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~37
When it runs · the whole SKILL.md, loaded when a task matches: ~2.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from sonpiaz/watch-cli at commit 06beafb, republished under its MIT licence (© sonpiaz). 1,069 words, ~2,080 tokens.

Download SKILL.mdSave it as .claude/skills/watch-cli/SKILL.md (or your agent's skills folder). This skill also uses 56 other files; get the full folder from GitHub.

name: watch-cli
description: Watch any social video → get an architecture diagram, working component, runnable notebook, or step-by-step cheat sheet — automatically.
homepage: https://github.com/sonpiaz/watch-cli

Watch any social video → get an architecture diagram, working component, runnable notebook, or step-by-step cheat sheet — automatically.

watch-cli is a thin orchestrator that downloads any social video, extracts evenly-spaced frames, and transcribes the audio. The output is a single labeled block (or one-line JSON) designed for an LLM to read frames as images and transcript as text. The agent supplies the prompt; watch-cli supplies the raw materials.

When to invoke

Reach for watch whenever the user gives you a video URL and wants you to do something with what's in it.

The user pastes a video URL with no verb. Ask one clarifying question ("summarize, implement, clone the UI, extract the architecture, or something else?"), then run watch.
The user asks to "summarize", "explain", or "walk me through" content at a video URL.
The user asks to "implement", "clone", "build", or "replicate" what is on screen in a video.
The user asks to "extract architecture from", "diagram", or "turn this paper talk into code" at a video URL.

Supported platforms: YouTube, X / Twitter, LinkedIn, TikTok, Vimeo, Reddit, Facebook. Every URL is fetched anonymously. A login-walled URL fails with tag=download-auth; watch-cli does not touch browser sessions on its own. If the user wants to use one, they opt in per run with WATCH_BROWSER=auto (or a browser name), which lets yt-dlp read cookies from the local browser profile and send them only to that platform; --cookies <file> uses an exported cookie file instead. Ask the user before setting either; never set them silently.

What you get back

The watch output gives you the raw materials to map to five concrete artifacts. Match the user's intent to one of them.

A coding walkthrough becomes working project files: read the frames for file names, exact code, and dependencies; read the transcript for intent and rationale; emit the final state, not the intermediate edits.

A system architecture talk becomes an interactive architecture diagram: a single self-contained HTML page with actors, surfaces, APIs, and clickable named flows that highlight the path through the system.

A UI or motion demo becomes a working React component: one paste-ready .tsx file that captures the feel and the single interaction that makes the UI special, not a pixel-perfect screenshot.

A paper or research talk becomes a runnable notebook: one .ipynb implementing the core method on a toy dataset that runs end-to-end on a free Colab T4.

A long tutorial becomes a step-by-step cheat sheet: numbered steps with copy-pasteable commands, video timestamps, verification per step, and only the troubleshooting the speaker actually discussed.

Five copy-paste prompt templates live in prompts/. Pick the one that matches the user's intent.

Parse rules

watch emits a versioned, agent-shaped payload. Both formats are documented in docs/output-schema.md and conform to the v1 contract — append-only, no renames, no type changes within v1.

Preferred: JSON mode. watch <url> --format json emits one UTF-8 JSON object on stdout terminated by a newline. Parse it with a real JSON parser, switch on obj.version, read obj.video_path, obj.duration_sec, obj.frame_paths (array of absolute JPG paths, earliest-in-video first), obj.transcript (string or null), and obj.exit_code. Field reference is the single source of truth in docs/output-schema.md.
Fallback: text mode. Some agent hosts (Claude Code does this today) capture stdout as a free-text block. The leading line WATCH_OUTPUT_VERSION: 1 is the version signal; everything below is labeled blocks (VIDEO:, DURATION:, FRAMES:, TRANSCRIPT:, EXIT:) per the same doc.
Read frames as images, transcript as text. Each path under FRAMES: (or each string in frame_paths) is an absolute path to a JPG on disk. Pass the path to the host's image-reading primitive. The transcript is plain UTF-8 text — no decoding needed.
Exit-code behavior is documented in docs/exit-codes.md. The partial-success case is the one to remember: on exit 4 the frames are populated and the transcript is null — branch on the exit code and fall through to a frames-only consumption path instead of failing the run.

Show full SKILL.md (423 more words)Show less

Invocation

bash

watch <url> [frame-count]

Default frame count is 8. For a fast-cut or dense UI demo, double it. For a multi-hour conference talk, bump to 24–32. The CLI does not cap; agent hosts typically prefer ≤ 32.

Check the archive before watching

Every successful run is stored under ~/.watch-cli/archive. Re-watching a URL is a cache hit — no download, no transcription, and the output block is byte-identical to the cold run — so re-running a URL is cheap, but re-deriving an answer already on disk is wasted work.

bash

watch-archive find "context graph"   # → id, [04:32], the matching line
watch-archive ls                     # what has already been watched
watch-archive get <id|url>           # reprint one record, transcript timestamped

Reach for watch-archive find first when the question is "have I already seen something about X?" or "where in that video did they say Y?". It searches every stored transcript and answers with a timestamp, which is a seek position rather than a video to sit through again.

Records are plain JSON, SRT and JPG on disk — grep and jq read them without this CLI, and <id>/transcript.srt loads in any video player. Layout in docs/archive.md.

Pass --no-cache only when the source itself has changed. A failed transcription is never stored, so a retry after an error always makes a real attempt.

Anti-patterns

Do not parse stderr. Progress lines on stderr ([watch] downloading …) are not part of the contract and change between releases. Programmatic consumers ignore stderr.
Do not parse the filename of a frame to infer its position. Filenames are implementation detail; the ordering of frame_paths is the contract.
Do not hard-fail on every non-zero exit. exit 4 is recoverable partial success — frames populated, transcript null. Branch on exit_code before parsing.
Do not surface API keys or environment variable names in chat. KYMA_API_KEY setup lives in the README.
Do not embed the locked pitch into a longer marketing paragraph. The description line above is the source of truth; reuse it verbatim where the host shows skill metadata.

What leaves the machine

The video download goes to the platform hosting it, through yt-dlp.
The extracted audio track is uploaded to Kyma API for transcription; frames and the video file stay on disk under ~/.watch-cli/archive. With --with-local installed, transcription runs offline through whisper.cpp instead and nothing is uploaded.
Browser cookies are never read unless the user sets WATCH_BROWSER or passes --cookies; when they are, they go only to the platform that set them.
Installation is pinned: the release installer downloads a tagged tarball and verifies its SHA256 against the checksum published on the same GitHub Release. Homebrew does the same through the formula's sha256.

Transcription runs through Kyma API. Get a key at https://kymaapi.com/?src=skill:watch and set KYMA_API_KEY; a one-hour video costs about $0.05.

Files

SKILL.md and 56 other files in the repository root of sonpiaz/watch-cli.

SKILL.md
.claude-plugin/marketplace.json
.env.example
.github/workflows/ci.yml
.github/workflows/release.yml
.gitignore
BRANDING.md
LICENSE
README.md
bin/audio-q
bin/dl-video
bin/extract-frames
bin/models
bin/transcribe
bin/watch
bin/watch-archive
docs
… and 40 more

Open the folder on GitHubat commit 06beafb

Compare with similar skills

Watch CLI next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Watch CLI compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Watch CLI this skillsonpiaz/watch-cli	253	—	~2.1k	Automated safety check: Pass	MIT	27 days ago
Excalidraw Canvas Toolkitlingzhi227/agent-research-skills	386	—	~3.8k	Automated safety check: Pass	None	7 mo ago
Excalidraw Skillyctimlin/mcp_excalidraw	2.5k	—	~4.6k	Automated safety check: Pass	MIT	4 days ago
GitDiagram Repository Overviewahmedkhaleel2004/gitdiagram	18k	—	~427	Automated safety check: Pass	MIT	yesterday
Drawio Diagram BuilderWill-hxw/drawio-diagram-builder	413	—	~5.9k	Automated safety check: Pass	MIT	3 mo ago
Bm Mdmiantiao-me/bm.md	617	—	~2.1k	Automated safety check: Pass	LGPL-3.0	10 days ago

Similar skills

Excalidraw Canvas Toolkit
lingzhi227/agent-research-skills
Draws and refines Excalidraw diagrams on a live canvas through MCP tools or a REST API, with screenshots, file import and export, snapshots and Mermaid conversion.
386 GitHub stars~3.8k tokensUpdated 7 mo ago
DevelopmentAuto-check passed
Excalidraw Skill
yctimlin/mcp_excalidraw
Excalidraw canvas toolkit for creating, editing, and refining diagrams on a live canvas.
2.5k GitHub stars~4.6k tokensUpdated 4 days ago
DevelopmentAuto-check passed
GitDiagram Repository Overview
ahmedkhaleel2004/gitdiagram
Explains the architecture of a public GitHub repository through GitDiagram: how the code is organized, the main components with paths, and a Mermaid diagram.
18k GitHub stars~427 tokensUpdated yesterday
DevelopmentAuto-check passed
Drawio Diagram Builder
Will-hxw/drawio-diagram-builder
Create, edit, replicate, and iteratively refine editable research and technical diagrams in diagrams.net/draw.io (.drawio XML) from prompts, papers, repositories, screenshots, or existing diagrams.
413 GitHub stars~5.9k tokensUpdated 3 mo ago
DevelopmentAuto-check passed
Bm Md
miantiao-me/bm.md
使用 bm.md 写作、改写、排版或渲染 Markdown；生成 Mermaid 与 AntV Infographic，设置图片尺寸、高亮重点，以及执行 HTML/纯文本转换和 Markdown lint
617 GitHub stars~2.1k tokensUpdated 10 days ago
Media & CreativeAuto-check passed
Drawio
bahayonghang/drawio-skills
Create, edit, replicate, import, and export draw.io diagrams with an offline YAML-first workflow: architecture, network topologies, flowcharts, UML/ER, org charts, Mermaid/CSV conversion, existing…
287 GitHub stars~4.1k tokensUpdated 1 mo ago
DevelopmentAuto-check: notes

Works with

Model Context Protocol

Questions about Watch CLI

What does Watch CLI do?

Watch any social video → get an architecture diagram, working component, runnable notebook, or step-by-step cheat sheet — automatically. Watch CLI is an agent skill from sonpiaz/watch-cli. Watch any social video → get an architecture diagram, working component, runnable notebook, or step-by-step cheat sheet — automatically.

When should I use Watch CLI?

Watch CLI fits situations like: tasks that involve Diagrams.

How do I install Watch CLI in Claude Code?

Run `npx skills add sonpiaz/watch-cli --skill watch-cli -a claude-code`. Or copy the skill folder (the sonpiaz/watch-cli repository) into .claude/skills/watch-cli in your project. Claude Code loads it when a task matches its description.

How do I install Watch CLI in Codex?

Run `npx skills add sonpiaz/watch-cli --skill watch-cli -a codex`. Or copy the skill folder (the sonpiaz/watch-cli repository) into .agents/skills/watch-cli in your project. Codex loads it when a task matches its description.

Can I use Watch CLI in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add sonpiaz/watch-cli --skill watch-cli -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/watch-cli, .gemini/skills/watch-cli, .github/skills/watch-cli and .opencode/skills/watch-cli in your project.

What does Watch CLI need to run?

Going by SKILL.md and its folder, Watch CLI needs credentials named KYMA_API_KEY. Our summary lists: A credential in KYMA_API_KEY.

Does Watch CLI access the network?

SKILL.md names 1 domain. As links in the text: kymaapi.com. This is read from the text; nothing was executed.

Is Watch CLI safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Watch CLI use?

Watch CLI is published under the MIT licence (from the LICENSE file in the skill folder). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Watch CLI use?

About 2.1k tokens (SKILL.md is roughly 8.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Watch CLI?

Skills that share tags, products or a category with Watch CLI: Excalidraw Canvas Toolkit (lingzhi227/agent-research-skills, 386 stars), Excalidraw Skill (yctimlin/mcp_excalidraw, 2.5k stars), GitDiagram Repository Overview (ahmedkhaleel2004/gitdiagram, 18k stars) and Drawio Diagram Builder (Will-hxw/drawio-diagram-builder, 413 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Watch CLI?

sonpiaz (a GitHub user) maintains it in sonpiaz/watch-cli, which has 253 GitHub stars. The repository was last updated on September 13, 2026.

Source: sonpiaz/watch-cli on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Watch CLI

Facts

At a glance

What it does

When your agent uses it

Example prompts

Requirements

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

When to invoke

What you get back

Parse rules

Invocation

Check the archive before watching

Anti-patterns

What leaves the machine

Files

Compare with similar skills

Similar skills

Excalidraw Canvas Toolkit

Excalidraw Skill

GitDiagram Repository Overview

Drawio Diagram Builder

Bm Md

Drawio

Related

Questions about Watch CLI