storyshot
Ask your coding agent for a video of your web app: promo clips, narrated tutorials and docs GIFs from a YAML storyboard
Install / Use
claude mcp add boheling -- npx -y github:boheling/storyshotIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of storyshot
storyshot scores 71/100 on our quality scale, 3862nd of 4,720 Development & Engineering skills we index.
Its MCP Server is 43 KB long, well organised into 23 sections with 4 code examples: long enough that it reads more like full documentation than a focused instruction file, which agents can find harder to follow.
It has 3 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated 2 days ago, so storyshot is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 92/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
storyshot compared with similar skills
All 4 of these similar skills score higher than storyshot; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| storyshot (this skill)by boheling | 71 | 3 | 2d ago | MCP Server |
| taste-skillby Leonxlnx | 100 | 117.8k | 9d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.8k | 10d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 82.0k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.9k | today | CLAUDE.md |
Frequently asked questions
- How do I install storyshot?
- Run
claude mcp add boheling -- npx -y github:boheling/storyshot. The install tabs above show the steps for each supported agent. - Which AI agents does storyshot work with?
- It is written for Claude Code, Claude Desktop, Cursor and OpenAI Codex, as a MCP Server file. Other agents that read the same format can often use it too.
- Is storyshot safe to use?
- It is MIT-licensed and scores 92/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is storyshot still maintained?
- The repository was last updated 2 days ago, so storyshot is actively maintained.
Skill content
View source on GitHubStoryshot
Ask your coding agent for a video, and get a polished 1080p MP4. Two kinds of film come out of one tool:
- An explainer of an idea — no web app, no footage, nothing recorded. Every scene is an animation the agent writes and times to the narration: a mechanism, a diagram that builds, a number that lands. Chinese or English. This is what most people come for.
- A video of your web app — a promo, a narrated tutorial, a lesson, or step-by-step GIFs for your docs. A real browser clicks through your site, and the recording gets a smooth cursor, automatic zoom, captions, an optional voiceover, music and an end card.
The agent plans, writes and fixes the storyboard. Storyshot does the rendering, and the same storyboard always renders the same video.
Install it into your coding agent
The skill is the front door. You do not learn a CLI — your agent does.
Open your project in your coding agent (Claude Code, Cursor, Codex, Gemini CLI,
Copilot in VS Code, Windsurf, Cline) and paste this one line into its chat, with
your agent's name in place of claude:
Set up Storyshot in this project: run
npx -y storyshot setup claudeand do everything it says.
Agent names: claude · cursor · codex · gemini · vscode · windsurf · cline.
That one command installs the Storyshot skill into your agent, writes the MCP
server config, adds .storyshot/ to .gitignore, and downloads the browser it
needs. The skill is what teaches your agent the whole workflow — how to plan a
film, write the scenes, read the render back and fix it — so from the next chat
on you can just ask for a video in plain words.
Restart or reload your agent when setup says to. Then:
「做一个视频,讲清楚热泵为什么能把一份电变成三份热」
"make an explainer about how a heat pump moves three units of heat per unit of electricity"
"make a 15 s promo video of https://myapp.com"
"make a narrated tutorial showing how to export a report"
or type /storyshot.
npx storyshot doctor re-checks everything at any time. Storyshot runs on
macOS, Linux and Windows. Needs Node 18+ and ffmpeg (setup prints the exact
install command for your OS if it is missing).
Explainers, in one paragraph
An explainer has no url and records nothing. You ask for a subject; the agent
writes a storyboard of scenes, and each scene is an HTML animation it draws
and times to the voice, phrase by phrase. It renders a still of every scene,
looks at it, and fixes what is wrong before it ever renders video. Free local
voices in English and Chinese, synth music, subtitles and chapters — no API key
and no per-video cost. Start here:
the explainers in the gallery,
and the "Scenes and explainers" playbook.
What setup writes, per agent
| agent | what setup writes |
|---|---|
| Cursor | .cursor/mcp.json and the skill in .cursor/skills/storyshot/ |
| Claude Code | .mcp.json and the skill in .claude/skills/storyshot/ |
| Codex | the skill in .agents/skills/storyshot/, a short section in AGENTS.md pointing to it, and the MCP server through codex mcp add (in ~/.codex/config.toml, for your user). Storyshot launches a browser, which Codex's sandbox blocks: approve it when Codex asks, or run Codex with --sandbox danger-full-access |
| Gemini CLI | .gemini/settings.json, a section in GEMINI.md, the skill in .agents/skills/storyshot/ (trust the folder when Gemini asks, or it ignores project settings) |
| Copilot in VS Code (vscode) | .vscode/mcp.json, a section in .github/copilot-instructions.md, the skill in .agents/skills/storyshot/ |
| Windsurf | .windsurf/rules/storyshot.md, the skill in .agents/skills/storyshot/, and the MCP server in ~/.codeium/windsurf/mcp_config.json (for your user) |
| Cline | .clinerules/storyshot.md, the skill in .agents/skills/storyshot/, and the MCP server in Cline's own settings in each editor it is installed in (for your user) |
Existing files are merged, not replaced: other MCP servers stay, and instruction files get one marked
Storyshot section that a second setup updates instead of duplicating.
Tested end to end (setup, then an agent making a real video from a plain request): Claude Code, Cursor and Codex. Gemini CLI, Copilot in VS Code, Windsurf and Cline get the configuration their docs describe, but haven't been tested with a real session yet; reports are welcome.
The agent does the rest:
setupwrites the MCP server config and the Storyshot skill, adds.storyshot/to.gitignore, and downloads the browser it needs.- If ffmpeg is missing, setup prints the exact install command for your OS
(
brew install ffmpeg,winget install --id Gyan.FFmpeg -e,sudo apt-get install -y ffmpeg). The agent runs it after you approve. - The agent reads the skill and starts on your video in the same chat, using the CLI.
From the next chat on, the agent uses the Storyshot MCP tools automatically.
https://github.com/user-attachments/assets/05dd9a73-2edc-46af-9b2b-a8e33c7005b4
A 68-second pitch for Storyshot, made with HyperFrames and a free local voice (Kokoro). The request, storyboard, recording, contact sheet and render log in it, and the 16 videos on the wall, are real Storyshot output.
Gallery
boheling.github.io/storyshot-gallery: promos, tutorials, lessons and help-center docs of real web apps (Squoosh, Excalidraw, NCBI BLAST, Desmos, regex101, RCSB PDB, Datasette and more, two of them in Chinese). Each one was made by an agent from a one-paragraph request, and comes with its storyboard and notes on how it went.
Next to similar tools
Storyshot, promo-video-recorder and demo-dev each made a promo of this repo's page, with the same storyline and free local voices only. The grid below is muted; open the full videos to hear them.
https://github.com/user-attachments/assets/3d8175ab-ba15-4b61-961d-481e57566e7a
<details> <summary>The three full videos, with sound</summary>Storyshot
https://github.com/user-attachments/assets/22987356-2a74-4e28-9a14-a1b01d04f932
promo-video-recorder
https://github.com/user-attachments/assets/e5eb86e5-e69c-403b-ad6c-c4499592307a
demo-dev
https://github.com/user-attachments/assets/8d3370ca-7a90-48af-b1c9-88189763e95d
</details>How each one was made, what we saw, and the caveats: docs/comparison.
What happens when you ask
-
The agent looks at your site (about 5 s). It reads the page, and checks whether the flow is behind a login and whether you have a voice API key.
-
It confirms the plan with you, once, before spending anything:
Here's the plan. Reply "ok", or change any line: 1. Type: pitch: a promo for the landing page 2. Length: about 20 s, 6 shots 3. Flow: hero → Examples → Try It → AI result → pricing → end card 4. Voice: none (other options: free local English voice; ElevenLabs, key found in .env) 5. Music: upbeat · Captions: English · Subtitle file (.srt): no 6. Format: 16:9, 1080p 7. Login: not needed -
If you need to log in, a browser window opens and you log in there. The agent never sees or types your password. See Logged-in apps.
-
It writes
videos/<site>-<kind>.yaml(kind is promo, tutorial, lesson or docs, plus a topic for tutorials, e.g.videos/acme-tutorial-export-pdf.yaml→.mp4), using only click targets verified on your live pages. -
It renders, looks at the result, and fixes it. Every render returns a contact sheet with one frame per step, plus warnings: a step that is rushed or slow, narration that doesn't fit, a caption covering what's being clicked, a page still loading. The agent fixes these and re-renders. When only text or timing changed, it re-renders in seconds without re-recording.
-
It hands you the MP4, a shot list, and what was sped up. Depending on the type, you also get
.srtsubtitles, YouTube chapters, or per-step GIFs.
The storyboard is a plain file in your repo. Commit it, edit it, and ask the agent for changes later ("make step 3 slower", "add a Chinese voiceover"). After your next release, re-render it and you have an up-to-date video.
What you can make
| ask for | type (purpose) | you get |
|---|---|---|
| a promo / launch / landing-page clip | pitch | short and tightly cut: intro card, the app in a browser frame, music, captions |
| a how-to or onboarding video | tutorial | paced to follow along: one narrated action per step, the camera following each click, part cards, a second example, a recap; .srt + chapters. check holds the narration to a teaching pace too — one job per step, a budget per line, no bolded payoffs — so a slow film doesn't still read as a pitch |
| a lesson | course | explains the why: concept cards, the idea shown in the app, question cards, a recap, no music; .srt + chapters. check holds it to the tutorial's teaching pace, and to a lesson's own shape: a card names one idea, a question waits for an answer and its step marks it |
| help-center snippets | docs | silent per-step GIFs and PNGs cropped to the action, plus a ready-to-paste Markdown article |
| an animated explainer of how something works | explainer | no web app: every step is a scene, an animation the agent writes and times to the narration (a mechanism, a diagram that grows, a number); calm music, subtitles, chapters |
Tutorials and lessons can use scenes too: a scene: step between recorded
steps explains an idea the app can't show, then the video goes back to the app.
Length follows the purpose and the content, not a target: a promo is as short as its message, a tutorial as long as the workflow takes to explain.
Any type can also be vertical (9:16) or in another language.
Voice and cost
Rendering is free and runs locally. Only the voiceover can cost money:
| voice | cost | notes |
|---|---|---|
| none | free | captions only |
| kokoro | free | local, English and Mandarin Chinese (zf_001); downloads a ~90 MB model on first use (Chinese: ~130 MB, and needs Python 3.10–3.12) |
| qwen | free | local, Apple Silicon Macs only; the most natural free Chinese voice (dylan, serena); every take is checked by a speech recognizer and made again if it comes out wrong; downloads ~3.3 GB of models and needs Python 3.10–3.12 |
| ElevenLabs | your credits | the most natural voice; many languages including Chinese. Put ELEVENLABS_API_KEY in .env. |
| OpenAI | your credits | OPENAI_API_KEY |
With a paid voice, the agent iterates with the free voice (draft mode) and only renders the paid voice once the video looks right. Each line is cached, so a change only pays for the lines that changed.
Logged-in apps
When the flow is behind a login, the agent says so in its plan. Then:
- A normal Chrome window opens (the
logintool, orstoryshot login <url>). No script is attached to it while you log in, so "Sign in with Google" and 2FA work as usual. - You log in there. When you see the app logged in, tell the agent "done" (or press Enter in the terminal). You can also just close the window.
- The session is saved to
videos/<site>-login.json. It includes cookies, localStorage, IndexedDB and sessionStorage, and the file is added to.gitignorebecause it holds your session. The temporary browser profile is deleted. - Every recording starts logged in, so the video never shows a login screen.
If the session expires, Storyshot says so ("the saved login has expired, run login again") instead of failing in a confusing way. Use a demo account: the video shows whatever is on screen.
For agents: tools and playbook
The playbook is [`skills
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
117.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.8kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
82.0k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
79.9kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
