Short vertical cut-paper explainer reels, made by your coding agent. Nine Agent Skills plus a Remotion library. Works with Claude Code, OpenCode, Codex, Gemini CLI, Cursor, Copilot and more.
TypeScript agent-skillsagents-mdclaude-codeclaude-code-skillscodexexplainer-videosgemini-cliopencodepapercutremotiontext-to-speechvideo-generation
skills: agent-agnostic wording (Claude Code + opencode)
José Naves7b223aae40de
diff --git a/skills/papercut-build/SKILL.md b/skills/papercut-build/SKILL.mdindex e5ac758..4a88aff 100644--- a/skills/papercut-build/SKILL.md+++ b/skills/papercut-build/SKILL.md@@ -11,7 +11,7 @@ Build every episode on the library instead of writing a Remotion project from sc- Install: **Standard** or Full. Needs the library, node 20+, npm, ffmpeg, Python tools (numpy, Pillow, soundfile) and Chrome or Chromium for the audio render. Probe with the commands in `papercut-explainer`; if something is missing, run `./install.sh --doctor` and hand over to `papercut-setup`.- Library: `$PAPERCUT_LIB`, else the `PAPERCUT_LIB=` line in `~/.config/papercut-explainer/config.env`, else ask once. With no library at all, build from the sketches in `../papercut-explainer/references/remotion-recipes.md`.-- Load the Remotion best-practices skill first (`remotion-best-practices`, from the Remotion Claude Code plugin or `npx skills add remotion-dev/skills`) and follow its routing for markup, captions and the Studio.+- Load the Remotion best-practices skill first (`remotion-best-practices`, from the Remotion plugin or `npx skills add remotion-dev/skills -g -y -a claude-code` plus `-a opencode` for opencode) and follow its routing for markup, captions and the Studio.- Needs `papercut/STORYBOARD.md` and `narration/script.json` from the earlier stages.- Smoke test of the whole toolchain: `library/tools/selftest.sh` builds `examples/hello-reel/` in a throwaway folder and renders one still.@@ -48,7 +48,7 @@ Follow `../papercut-explainer/references/asset-prompts.md`: an image tool (anyth## 4. Scenes1. Build `S01Hook` yourself first, from the HOOK block. It is the reference scene the agents match (cue constants, the camera, clamped `interpolate`).-2. Hand the rest to scene agents in parallel, grouped by scene (2-3 scenes each; more agents cost more startup context). Use the `papercut-scene` agent that `install.sh` links into `.claude/agents` (a general agent also works). The brief is `library/papercut/AGENT_BRIEF.md`. The spawn message gives the project path, each agent's scenes with absolute frame ranges, a QA folder name and the value of `$PAPERCUT_LIB`.+2. Hand the rest to scene agents in parallel, grouped by scene (2-3 scenes each; more agents cost more startup context). Use the `papercut-scene` agent that `install.sh` links into the agents folder (`~/.claude/agents` for Claude Code, `~/.config/opencode/agents` for opencode; a general agent also works). Spawn via the Task tool in Claude Code or the subagent tool in opencode. The brief is `library/papercut/AGENT_BRIEF.md`. The spawn message gives the project path, each agent's scenes with absolute frame ranges, a QA folder name and the value of `$PAPERCUT_LIB`.3. File ownership: an agent writes only `src/scenes/<Scene>.tsx`, an optional `<Scene>.parts.tsx` and `tools/cue_sheet.d/<Scene>.json`. Never `src/lib/**`, other scenes, `index.ts`, `plan.json`, `episode.json` or the storyboard.4. Agents read `library/papercut/CATALOG.md` and `library/audio/CATALOG.md`, not the kit source, and reuse components, prop sets and scene templates (`kit/scenes/`, for example `CtaPhoneDM` for the CTA) before drawing anything new.diff --git a/skills/papercut-explainer/SKILL.md b/skills/papercut-explainer/SKILL.mdindex 831ed39..939fa07 100644--- a/skills/papercut-explainer/SKILL.md+++ b/skills/papercut-explainer/SKILL.md@@ -90,7 +90,7 @@ node -v; ffmpeg -version | head -1"$QWEN_TTS_PY" -c 'import qwen_tts'```-The first three lines passing means Standard. The `qwen_tts` import passing as well means Full. If a stage needs more than the install provides, say so in one line, run `./install.sh --doctor` from the repo root, and hand over to `papercut-setup` instead of improvising. Find the root with `readlink` on the installed skill folder, or `PAPERCUT_HOME` in the config file.+The first three lines passing means Standard. The `qwen_tts` import passing as well means Full. If a stage needs more than the install provides, say so in one line, run `./install.sh --doctor` from the repo root, and hand over to `papercut-setup` instead of improvising. Find the root with `readlink` on the installed skill folder (under `.claude/skills` or `.config/opencode/skills`), or `PAPERCUT_HOME` in the config file.## Rules across stagesdiff --git a/skills/papercut-setup/SKILL.md b/skills/papercut-setup/SKILL.mdindex 39fe1e4..ab188e9 100644--- a/skills/papercut-setup/SKILL.md+++ b/skills/papercut-setup/SKILL.md@@ -9,9 +9,9 @@ A guided wrapper around `install.sh`. It checks what is installed, asks how much## Preflight-- Find the repo root (where `install.sh` lives): `readlink ~/.claude/skills/papercut-setup` (or the same under `<project>/.claude/skills`) ends in `<root>/skills/papercut-setup`; failing that, `PAPERCUT_HOME=` in `${XDG_CONFIG_HOME:-~/.config}/papercut-explainer/config.env`. If neither exists, the skills probably came from `npx skills add` (skills only, no library). Ask where to clone the repo (default `~/papercut-explainer`), run `git clone https://github.com/0xS4N4TG/papercut-explainer <dir>`, and use that as the root. The installer then replaces the copied skill folders with links into the checkout (it backs up real folders first). Never guess a path.+- Find the repo root (where `install.sh` lives): `readlink` on the installed skill folder ends in `<root>/skills/papercut-setup`. Check each agent's location in turn: `~/.claude/skills/papercut-setup` (or `<project>/.claude/skills`), then `~/.config/opencode/skills/papercut-setup` (or `<project>/.opencode/skills`; opencode also discovers the `.claude` paths). Failing that, `PAPERCUT_HOME=` in `${XDG_CONFIG_HOME:-~/.config}/papercut-explainer/config.env`. If neither exists, the skills probably came from `npx skills add` (skills only, no library). Ask where to clone the repo (default `~/papercut-explainer`), run `git clone https://github.com/0xS4N4TG/papercut-explainer <dir>`, and use that as the root. The installer then replaces the copied skill folders with links into the checkout (it backs up real folders first). Never guess a path.- Run every `install.sh` command from that root. It needs bash, and macOS or Linux (Windows: use WSL).-- The installer's own prompts need a terminal, which the Bash tool lacks. Always pass `--yes` and the answers as flags. Tell the user they can run `./install.sh` themselves for the interactive menu.+- The installer's own prompts need a terminal, which the agent's shell tool lacks. Always pass `--yes` and the answers as flags. Tell the user they can run `./install.sh` themselves for the interactive menu.## 1. Doctor@@ -19,7 +19,7 @@ A guided wrapper around `install.sh`. It checks what is installed, asks how much./install.sh --doctor```-Add `--project DIR` or `--skills-dir DIR` if the skills went somewhere other than `~/.claude/skills`; the doctor only looks where you point it. It prints `[ok]`, `[--]` (missing) or `[!!]` (wrong). Summarise it in plain words:+Add `--project DIR`, `--skills-dir DIR` or `--target claude|opencode|all` if the skills went somewhere other than the defaults (`~/.claude/skills` + `~/.config/opencode/skills`); the doctor only looks where you point it. It prints `[ok]`, `[--]` (missing) or `[!!]` (wrong). Summarise it in plain words:- skills installed, config file and `PAPERCUT_LIB`- node 20+, npm, ffmpeg, python3- Remotion agent skills, Python tools (numpy + Pillow)@@ -28,14 +28,15 @@ Add `--project DIR` or `--skills-dir DIR` if the skills went somewhere other thaThen say which install mode that adds up to (see `papercut-explainer`, Install modes).-## 2. Ask (AskUserQuestion)+## 2. Ask-Ask only what is still open, in one call:+Ask only what is still open, in one call (AskUserQuestion in Claude Code, the question tool in opencode):| Question | Options ||---|---|| How much? | **Minimal**: skills only, seconds. **Standard**: render with a placeholder voice, ~0.7 GB and a few minutes. **Full**: Standard + local voiceover, +4-6 GB (a 1.5 GB venv plus a 2.3 or 4.2 GB model) and a 2-minute smoke test. **Custom**: pick components. |-| Where do the skills go? | User-wide (`~/.claude/skills`, the default) or one project (`--project DIR`). |+| Which agent? | Both (default, `--target all`), Claude Code only (`--target claude`) or opencode only (`--target opencode`). |+| Where do the skills go? | User-wide (the default) or one project (`--project DIR`). || Copy or link? | Symlink (default, updates with `git pull`) or `--copy` (a snapshot). || TTS model size (Full) | 1.7B, better prosody, ~4.2 GB (default). 0.6B, lighter and faster, ~2.3 GB. || Voice-clone model (Full) | No (default), or `--with-clone`: the Base model of the same size again. |@@ -45,18 +46,18 @@ Confirm before any multi-GB download. On a machine with no GPU (not Apple Silico## 3. Install```-./install.sh --mode <minimal|standard|full> --yes [--skills-dir DIR | --project DIR] [--copy] [--tts-model 1.7B|0.6B] [--with-clone]+./install.sh --mode <minimal|standard|full> --yes [--target claude|opencode|all] [--skills-dir DIR | --project DIR] [--copy] [--tts-model 1.7B|0.6B] [--with-clone]./install.sh --mode custom --components skills,deps,remotion-skills,pytools,tts,verify --yes```- Add `--dry-run` first if the user wants to see the plan; it changes nothing.- Standard and Full take minutes (npm install, Remotion's Chrome, venvs, model download). Run them in the background and check the output; do not hold a foreground call.-- What each mode does: Minimal links the skills and the scene-builder agent. Standard adds a dependency check, the Remotion agent skills (`npx skills add remotion-dev/skills -g -a claude-code`, installed user-wide, so say so when you confirm the plan), a Python venv with numpy, Pillow and soundfile, and a self-test render. Full adds `library/voice/setup_tts.sh`: a voice venv with Qwen3-TTS, an ASR backend (mlx-whisper on Apple Silicon, faster-whisper elsewhere), the model download and a one-line smoke test.+- What each mode does: Minimal links the skills and the scene-builder agent (into the Claude and opencode skill/agent folders, unless `--target` says otherwise). Standard adds a dependency check, the Remotion agent skills (`npx skills add remotion-dev/skills -g -y -a claude-code` plus `-a opencode`, installed user-wide, so say so when you confirm the plan), a Python venv with numpy, Pillow and soundfile, and a self-test render. Full adds `library/voice/setup_tts.sh`: a voice venv with Qwen3-TTS, an ASR backend (mlx-whisper on Apple Silicon, faster-whisper elsewhere), the model download and a one-line smoke test.- The installer writes `PAPERCUT_HOME`, `PAPERCUT_LIB`, `PAPERCUT_PY`, `QWEN_TTS_PY` and `ASR_PY` into `~/.config/papercut-explainer/config.env`. An existing skill folder that differs from this checkout is backed up to `~/.config/papercut-explainer/backups/` (not into the skills folder, so it is not loaded twice); an identical copy, such as one from `npx skills add`, is just replaced.## 4. Verify and report-Run `./install.sh --doctor` again with the same `--project` or `--skills-dir`. Report what is installed, what failed (the installer prints `needs attention:` with component names), and the fix. A new Claude Code session picks up newly linked skills. Then suggest: "make a papercut explainer about <link>", or one stage at a time ("write a hook for...", "storyboard this script", "set up the voice").+Run `./install.sh --doctor` again with the same `--project`, `--skills-dir` or `--target`. Report what is installed, what failed (the installer prints `needs attention:` with component names), and the fix. A new Claude Code session picks up newly linked skills (restart it); opencode reloads configuration automatically. Then suggest: "make a papercut explainer about <link>", or one stage at a time ("write a hook for...", "storyboard this script", "set up the voice").## Troubleshooting@@ -68,7 +69,8 @@ Run `./install.sh --doctor` again with the same `--project` or `--skills-dir`. R| Hugging Face download stalls or fails | Rerun; finished files are kept and the script retries 3 times. It sets `HF_HUB_DISABLE_XET=1`; set it yourself for manual downloads. || First render is slow | Remotion downloads its headless Chrome once. The audio render and `capture.mjs` use your own Chrome; set `CHROME_PATH` if it isn't in a usual place. || Self-test fails | Run `library/tools/selftest.sh` directly to see the failing step. |-| Skills don't show in Claude Code | Start a new session. Check `ls ~/.claude/skills` (or `<project>/.claude/skills`). |+| Skills don't show (Claude Code) | Start a new session. Check `ls ~/.claude/skills` (or `<project>/.claude/skills`). |+| Skills don't show (opencode) | Config reloads automatically. Check `ls ~/.config/opencode/skills` (or `<project>/.opencode/skills`); opencode also reads the `.claude` paths. || Move from Minimal to Standard | `./install.sh --mode custom --components deps,remotion-skills,pytools,verify --yes` || Add the voice later | `./install.sh --mode custom --components tts --yes [--tts-model 0.6B] [--with-clone]` || Remove it | `./install.sh --uninstall` removes the links it recorded. It leaves `config.env`, the venvs under `~/.local/share/papercut-explainer` and the Hugging Face cache; delete those by hand for the space. |