Guide · Agent skill
How to use the StoryFilm agent skill: narrated animated story films
Updated · written with AI from the project's own documentation and checked against our catalogue data
StoryFilm is an agent skill that turns a short story written in markdown into a narrated, animated film. The listener is read to while the story's paintings, camera moves and captions play in sync with the narration. This guide explains what the skill makes the agent do, how to install it, how to trigger it with plain requests, and what it needs before your first run.
StoryFilm: Narrated Animated Story Filmsdanielmiessler/LifeOS · MIT Download the skill Quick start
- 1Download and unzip. Download the StoryFilm ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder.
- 2Complete setup. Follow Setup.md to add FISH_API_KEY and GOOGLE_API_KEY and install Bun, ffmpeg and the HyperFrames tooling.
- 3Optionally configure. Create Config.json if you want a different runs folder or licensed serif fonts.
- 4Prepare a story file. Use a markdown story with frontmatter including title, author and audio_voice if you want a specific narrator.
- 5Ask for a film. Say something like "Turn this story into an animated reading" and name the file.
- 6Review the output. Look at the review sheets and watch Out/film.mp4 before delivering, since consistency needs a human check.
What an agent skill is and what StoryFilm makes it do
An agent skill is a folder of instructions and scripts that an AI agent loads when a request matches the skill's trigger phrases. StoryFilm is one such skill, and its job is narrow: take a story file and produce a film of it.
Once installed, the agent splits the story into beats (one per paragraph), writes a bible of recurring characters and places so they look the same in every shot, paints one illustration per beat in one style, generates narration in a chosen voice with word timings, and assembles a HyperFrames video with camera moves, dissolves, scene breaks, a caption line and title cards. It then checks the rendered film before delivering it.
- Input: a story markdown file
- Output: a film at Out/film.mp4 inside a run folder, plus review sheets and a verify.json report
- Narration and images come from paid external services (Fish Audio and Google)
Install the StoryFilm skill
Download the StoryFilm ZIP from this page and unzip it. You can install it in one of two ways.
For a personal install, unzip it into ~/.claude/skills/ so the StoryFilm folder sits there. For a single project, unzip it into that project's .claude/skills/ folder instead. In the Claude apps, you can also upload the ZIP under Settings → Capabilities → Skills.
After installing, complete the setup in Setup.md before your first run. The skill needs API keys and some programs installed.
- Personal: ~/.claude/skills/
- Project only: .claude/skills/ inside the project
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Set up keys and programs
StoryFilm needs two keys in your environment file: FISH_API_KEY for Fish Audio narration and GOOGLE_API_KEY for image generation. It also needs Bun to run its scripts, ffmpeg and the other programs listed in Setup.md, and the HyperFrames render tooling from the LifeOS shared tools.
An optional Config.json lets you set the output folder (runsRoot, default ~/StoryFilms) and paths to licensed fonts. If you set no font, the skill uses Source Serif 4, installed as a pinned dependency by Setup.ts.
- FISH_API_KEY: Fish Audio narration
- GOOGLE_API_KEY: image generation
- LIFEOS_STORYFILM_DIR: overrides runsRoot
- Optional Config.json: runsRoot, fonts.serif, fonts.serifItalic
Trigger the skill with a natural request
You do not need a special command. Name the story file and say what you want. The skill's trigger phrases include "film this story", "animate this story", "illustrated audiobook", "narrated story video", "turn this story into a movie", "storyboard this story" and "paint the shots".
The skill has three intents. Full runs the whole pipeline from a story file. Storyboard plans the bible and shots only. Produce paints, renders and verifies an existing storyboard. Say "straight through" to skip the storyboard review checkpoint.
- Full: "Turn the story at stories/the-lighthouse.md into an animated reading"
- Storyboard: "Storyboard this story" or "plan the shots"
- Produce: "Paint the shots", "render it", "verify the film"
Work through an example run
A typical full run intakes the story into Beats.json, writes the storyboard and passes its lint check, then paints the bible and shots, synthesizes narration, renders the film and verifies it. Review sheets are written to the run's review folder for you to look at.
To fix one painting, describe the problem. For example, if a kitchen in beat 12 looks like a restaurant, the agent edits that shot's prompt and repaints only that beat, because other paintings are hash-cached. If a character drifts in age, the agent tightens that character's bible description and repaints the affected sheet and shots.
- Shots are cached by hash, so an edited prompt repaints one beat
- Re-run intake if you edit the story file after the first run, or the old text will still be used
Understand the safety and network notes
StoryFilm runs scripts on your machine and uses the network. Your story text goes to Fish Audio for narration, and your prompts and images go to Google for painting. Both services charge for use, so check their terms and pricing before running long stories.
The skill has no upload or publish path. The finished film and sheets reach your downloads folder only through the deliver step, after critique passes. A human still needs to watch the film, because character consistency is checked by eye, not guaranteed.
- Network: yes, to Fish Audio and Google
- Scripts: yes, run with Bun
- Run folders are refused under the config tree or the user-data repo
- No publishing: nothing leaves your machine except the paid API calls
What people use it for
- Teachers turning a short class reading into an illustrated narrated video
- Writers producing an animated reading of their own short fiction
- Developers studying a working multi-stage media pipeline with storyboard, render and verification stages
Frequently asked questions
How do I install the StoryFilm agent skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for a personal install, or into a project's .claude/skills/ folder. In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.
Is StoryFilm free to use?
The skill is released under the MIT licence. Narration uses Fish Audio and images use Google, both paid external APIs, so running it costs money through those accounts.
What does StoryFilm need to run?
It needs Bun to run its scripts, ffmpeg and other programs listed in Setup.md, the HyperFrames render tooling from the LifeOS shared tools, a FISH_API_KEY and a GOOGLE_API_KEY. An optional Config.json sets the output folder and fonts.
Does StoryFilm send my text anywhere?
Yes. Narration sends your story text to Fish Audio and image generation sends prompts and reference images to Google. The skill itself has no upload or publish path.
Can StoryFilm make live-action videos or video essays?
No. The skill's own description says it is for narrated animated story films. Live-action video, argument-first video essays, one-off motion graphics and single illustrations are routed to other tools.
Why does my film still have a character that looks different?
Consistency is checked manually, and the skill runs a render rather than guaranteeing quality. Tighten that character's bible description and repaint their sheet and affected shots, as described in the skill's examples.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
StoryFilm suits writers, teachers and creators who want an illustrated, narrated video of a short story built from their own text, and developers who want a worked multi-stage media pipeline. It is a poor fit if you need a paid-service-free workflow, a live-action or essay video, or a finished file ready to publish without human review.
Download the skill