shuohao-skills: Agent Skills That Turn a Novel Into AI Short-Drama Production Assets

The paperwork problem shuohao-skills addresses

Generating a short drama with AI models is not the hard part. The hard part is everything before the first frame: deciding which characters survive the adaptation, what each of them looks like and sounds like, which props carry narrative weight, how long each episode runs at a given speaking rate, and how a script breaks into segments short enough for a single generation call. Those decisions are usually scattered across notes, chat threads and a dozen inconsistent prompt files.

shuohao-skills packages that work as five agent skills, each in its own directory under skills/. The README describes the pipeline as adaptation outline converging the structure, then script, scenes and characters iterating together, with the storyboard doing output only and making no new decisions. That ordering is the design claim: downstream artifacts consume upstream JSON rather than re-deciding.

The audience is narrow and specific. You need an agent session in Claude Code or codex, a novel or source text, and patience for a Chinese-language workflow. The reports default to Chinese, with render --lang en producing English report interfaces while the data content stays in its original language.

Five skills, one JSON handoff

Each skill is self-contained and can be copied out on its own. The repository layout requires a SKILL.md that the agent reads as its workflow, a README.md for humans, a scripts/ directory holding a zero-dependency .mjs tool plus a selftest.mjs, and optional references/, examples/ and assets/ folders.

The handoff between stages is a JSON file. novel-outline produces an outline covering adaptation notes, a character list, a payoff table, episode synopses and an asset list that includes narrative props. novel-characters reads outline.json to prefill its character table and emits portraits, image prompts, voice prompts and character reference sheets. novel-art does the same for scenes and props, with consistency anchors, lighting and state variants, scale references, and prompts specifying no people and no hands on a white background. novel-script writes scenes as beat flows alternating action and dialogue, converts episode duration deterministically from speaking rate, and aggregates lines by character with voice prompts attached for TTS. novel-storyboard splits into segments of at most 15 seconds, then shots of 2 to 5 seconds under a hard gate, then storyboard images pinned to specific cut times.

The gate counts are stated per skill: 14 quality gates for novel-outline, 11 for novel-art, 10 for novel-script, 17 for novel-storyboard. The README says these are checked by scripts, which matters more than the number. A gate enforced in code is a constraint; a gate described in prose is a suggestion.

Installing shuohao-skills and running the first skill

The install path is a clone plus a shell script. The script detects whether Claude Code or codex is present and symlinks every skill into place, so a later git pull takes effect without reinstalling. Node 18 or higher is required. The skill scripts use only the standard library, so there is no npm install step and no API key to configure; they consume the quota of your current session.

git clone https://github.com/eternityspring/shuohao-skills.git
cd shuohao-skills
./scripts/install.sh

If you want a single skill, or only codex, the same script takes arguments. The README gives these forms:

./scripts/install.sh novel-characters   # 只装某一个
./scripts/install.sh --codex            # 只装到 codex
./scripts/install.sh --uninstall        # 取消软链

Manual linking is documented as an alternative, pointing at ~/.claude/skills/ and ~/.codex/skills/.

Before running anything through a model, run the deterministic tests. The README states each selftest covers all deterministic logic without calling a model, so it costs no quota:

for f in skills/*/scripts/selftest.mjs; do node "$f"; done

The README says the suite finishes in about a second and that there is no CI, on the reasoning that a local run is cheaper than waiting for a pipeline. That is a defensible choice for a repository this size, but it also means nothing prevents a broken commit from landing. If you fork this, run the loop yourself.

The report assembler is separate from the skills. It does not import skill code; it invokes each skill's render --html and stitches the outputs into one page with left-side navigation, showing only the panels you actually produced:

node scripts/report.mjs --from <demo目录> --out report.html

You can also name each input individually with --outline, --cast, --art, --script and --storyboard. The README notes the assembler handles three collision problems: 57 shared class names of which 13 are same-name-different-definition, global document.querySelector calls in each report's scripts that would otherwise only hit the first match, and image paths that are relative to each report's own JSON directory. Number keys 1 through 5 switch panels, and deep links like #pane-script point at a specific panel.

Where the pipeline breaks

The most concrete failure mode in the README is a silent one. Storyboard segment folders such as E01-01/ must sit at the same level as the report HTML, because the report references images by relative path <segment>/f<cut>.png. If you nest them one level deeper, for example inside a segments/ directory, the report does not error. The images simply become not-generated placeholders. The README records that moving 10 segment folders into segments/ took the embedded image count from 2 to 0 with no warning.

That is the shape of the whole tool: deterministic scripts enforce their gates loudly, but the file-layout contract is enforced only by convention. Nothing validates your directory tree.

Two other limits are stated plainly. Image generation requires the codex CLI and its built-in $imagegen; without it you skip image output and everything else still runs, which means a Claude Code user gets text artifacts and no reference sheets. And the README says the code has been verified only on macOS with Node 24. It notes there are no platform-specific calls and that Linux and older Node versions should work, but that this has not been tested. Treat that as unverified rather than supported.

Finally, this is not a service. There is no hosted API, no queue, no database. It is a directory of instructions and scripts that an agent executes inside your session, and it inherits every limitation of that session, including context length. The README notes the five combined reports approach 600,000 characters, which is why the assembler shows one panel at a time by default.

Against writing your own prompt chain

The obvious alternative is a folder of prompt files and a spreadsheet. That approach is more flexible and has no install step, and for a one-off short drama it is probably faster. The difference is what happens on the second and fifth project. A prompt chain carries no validation: nothing tells you that your episode durations do not match your target speaking rate, or that a character appears in the script but not in the character bible. shuohao-skills puts those checks in selftest scripts and quality gates, which is the actual product here.

The second alternative is a general-purpose writing assistant with a long system prompt. That gives you better prose and no structure. The skills are the inverse: structured JSON with deterministic duration math and prompt scaffolding, and prose quality that depends entirely on the model in your session.

Comparing the two honestly, the skills win on repeatability and lose on flexibility. If your production format diverges from the five-stage model, you will be fighting the gates rather than using them. The repository does document how to add a skill, but it also requires that every skill ship a SKILL.md and a model-free selftest, so extending it means writing tests, not just prompts.

Maintenance, licence and what to verify

The last push to the repository was on 2026-09-14, two days before this writing, and the repository is not archived. Recent releases were not retrieved, so there is no version history to inspect; the CHANGELOG.md at the repository root is the place to look for what changed. Because the install is a symlink into your agent's skills directory, a git pull updates every skill immediately with no reinstall step, which is convenient and also means an upstream change reaches your workflow without a version boundary.

The licence is Apache-2.0, with a NOTICE file at the root alongside LICENSE. Apache-2.0 permits commercial use and modification and includes an explicit patent grant, but it also requires that you preserve copyright and licence notices and state significant changes. The README mentions a paid AI video community group on WeChat and states that the group and the ReelBench workbench are two independent services. That is a community arrangement, not a licence term, and it has no bearing on your rights to the code. For anything beyond that, read LICENSE and NOTICE rather than a summary.

Upgrade cost is low in the ordinary case and higher if you fork. Since there are no npm dependencies, there is no dependency tree to audit. The cost sits in the file-layout contract and the selftest suite: any local change to a skill's deterministic scripts should keep its selftest passing, and the README's own loop is the check.

Editorial conclusion

Adopt shuohao-skills if you already run Claude Code or codex and want the pre-production paperwork of a short drama produced as structured JSON with scripted quality gates. Skip it if you need a hosted service, a GUI, or anything that works without an agent session. Before committing, run the per-skill selftest suite, confirm your Node version is at least 18, and check that your storyboard segment folders stay siblings of the report HTML, because nesting them silently breaks the embedded images.

Frequently asked questions

Official sources

1. eternityspring/shuohao-skills on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README