mirror of
https://github.com/Luchexx/claude-video.git
synced 2026-11-02 09:19:48 +00:00
457627318c
Claude's skill upload rejects frontmatter keys outside the spec. SKILL.md now uses only spec keys, with the version under metadata.version. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
52 lines
3.9 KiB
Markdown
52 lines
3.9 KiB
Markdown
# claude-video / watch skill
|
|
|
|
Agent Skills package that gives an agent a video input. Installable across Claude Code (most common host), Codex, Cursor, GitHub Copilot, and 50+ other [Agent Skills](https://agentskills.io) hosts. Pure-stdlib Python that orchestrates `yt-dlp` + `ffmpeg` and an optional Whisper API or separately managed local WhisperX process.
|
|
|
|
## Structure
|
|
|
|
- `skills/watch/SKILL.md` — canonical skill contract the model reads when `/watch` fires. Source of truth for behavior across every host.
|
|
- `skills/watch/scripts/watch.py` — entry point; orchestrates download → frames → transcript.
|
|
- `skills/watch/scripts/{download,frames,transcribe,whisper,local_whisperx,setup,config,runtime}.py` — yt-dlp wrapper, ffmpeg frame extraction + auto-fps, caption/Whisper transcription, preflight/installer, shared config.
|
|
- `skills/watch/scripts/build-skill.sh` — builds `dist/watch.skill` for claude.ai upload (dev-only).
|
|
- `hooks/` — Claude Code SessionStart setup-status hook (Claude Code only).
|
|
- `.claude-plugin/` — `plugin.json` + `marketplace.json` (Claude Code plugin + local marketplace).
|
|
- `.codex-plugin/plugin.json` — Codex/agents manifest; `"skills": "./skills/"` points the Agent Skills CLI at the self-contained skill folder.
|
|
- `.agents/plugins/marketplace.json` — agents marketplace listing pointing at the repo-root plugin.
|
|
- `CLAUDE.md` → `@AGENTS.md` — generic-agent entry point.
|
|
- `tests/` — pytest suite (ffmpeg-synthesized clips; no network).
|
|
|
|
## Orientation
|
|
|
|
- The product is the slash-command-invoked skill (`/watch <url-or-path> [question]`), not a CLI. `scripts/watch.py` is implementation. Features must work across every harness the skill installs into, not just Claude Code.
|
|
- **The skill is one self-contained folder: `skills/watch/`.** SKILL.md and `scripts/` are siblings inside it. This is what lets `npx skills add` copy a working skill as a unit — do NOT move SKILL.md or `scripts/` back to the repo root, or non-Claude installers will copy SKILL.md without the scripts.
|
|
- **Path resolution is harness-agnostic.** SKILL.md resolves `SKILL_DIR` as the directory of the SKILL.md the model just Read, then runs `${SKILL_DIR}/scripts/...`. Do NOT reintroduce `${CLAUDE_SKILL_DIR}` (Claude-Code-only) — it is unset on Codex/Cursor/agents and breaks every script call there.
|
|
- **No `commands/` wrapper.** `/watch` comes from `name: watch` (skills are user-invocable by default). A separate command file creates a duplicate slash command.
|
|
- **SKILL.md frontmatter uses only Agent Skills keys:** `name`, `description`, `license`, `allowed-tools`, `metadata`, `compatibility`. Claude's skill upload rejects anything else; the version lives in `metadata.version`.
|
|
|
|
## Install surfaces
|
|
|
|
| Surface | Install |
|
|
|---------|---------|
|
|
| Claude Code | `/plugin marketplace add bradautomates/claude-video` then `/plugin install watch@claude-video` |
|
|
| Codex / Cursor / Copilot / +50 | `npx skills add bradautomates/claude-video -g` |
|
|
| claude.ai (web) | upload `dist/watch.skill` (built by `skills/watch/scripts/build-skill.sh`) |
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# Tests (stdlib + pytest; ffmpeg required for frame tests)
|
|
.venv/bin/pytest -q # or: python3 -m pytest -q
|
|
|
|
# Build the claude.ai upload bundle (archives skills/watch/ as the bundle root)
|
|
bash skills/watch/scripts/build-skill.sh # → dist/watch.skill
|
|
|
|
# Dev: mirror the working tree into the installed Claude Code plugin cache
|
|
./dev-sync.sh # --dry-run to preview
|
|
```
|
|
|
|
## Rules
|
|
|
|
- Keep the version in sync across `skills/watch/SKILL.md` (`metadata.version`), `.claude-plugin/plugin.json`, and `.codex-plugin/plugin.json` when cutting a release.
|
|
- Releasing: tag `vX.Y.Z` and push the tag; `.github/workflows/release.yml` builds `dist/watch.skill` and attaches it to the GitHub release.
|
|
- Never commit real API keys or `.env` contents; keys live in `~/.config/watch/.env` (mode `0600`) at runtime.
|