shuohao-skills: Six Claude Code Agent Skills for AI Short-Drama Production

What shuohao-skills Does and Who It Is For

Turning a written novel into an AI short drama requires several distinct production stages: adapting the plot into a series structure, defining characters, establishing art direction, writing scripts, and breaking scripts into individual shots. Each stage produces artifacts that feed the next. shuohao-skills packages this entire pipeline as six Claude Code agent skills, each responsible for one stage and each producing structured JSON and Markdown output that the next skill consumes.

The audience is creators and developers who are already running Claude Code or OpenAI Codex and want a repeatable, quality-checked workflow rather than sending ad-hoc prompts. The README describes the target: from a novel to production-ready pipeline materials. The skills also support non-novel starting points: `character-refs` can generate reference images for any character from a description, not just ones derived from a novel.

The README notes that the pipeline has been used to produce end-to-end demo output, with the working directory convention derived from that experience.

The Six Skills and What Each Produces

The six skills are organized in pipeline order. `novel-outline` takes a novel and produces a five-part adaptation package: an adaptation note, a character list, a hook-point table, episode synopses, and an asset inventory including a narrative-props table. It runs 14 quality gates as scripted checks.

`novel-characters` takes the outline's character list and produces a character bible: character profiles, image generation prompts, voice style prompts, and character design images. It reads the `outline.json` file from the previous stage to pre-populate the character table.

`character-refs` generates actual reference images for any character. It takes a written character description, expands it into structured fields, produces a frontal full-body anchor image first, and then generates a close-up, a 90-degree side view, a rear view, and a detail shot, all referencing the anchor. The README lists four image generation backends: ComfyUI with Qwen Image, Codex's built-in image generation, GPT Image 2 via API, or a custom command. The backend is chosen once on first use.

`novel-art` produces an art bible for scenes and narrative props, including consistency anchors, lighting and state variants, scale references, and clean-background prompts for AI image generation. It runs 10 quality gates and reads `outline.json` to pre-populate the asset list.

`novel-script` writes the actual screenplay: scenes with beat flows (action and dialogue alternating), episode durations calculated deterministically from speaking speed, cold-open hooks, and a dialogue script organized by character with voice style prompts ready for TTS. It runs 10 quality gates.

`novel-storyboard` breaks the script into storyboard segments (each segment is at most 15 seconds), then individual shots (each shot is 2 to 5 seconds, enforced as a hard gate). It generates main and sub-shot images referencing the art bible as source images, and exports a production package for MiniMax H3 and Seedance with per-shot prompts. It runs 18 quality gates.

Installation and Running the Skills

The install script detects whether Claude Code or Codex is present and creates symlinks for all six skills:

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

Because the install uses symlinks rather than copying files, running `git pull` updates all skills immediately without reinstalling. Selective installation is also supported:

./scripts/install.sh novel-characters

To install only to Codex instead of Claude Code:

./scripts/install.sh --codex

To remove all symlinks:

./scripts/install.sh --uninstall

If you prefer to create symlinks manually, the pattern for a single skill in Claude Code is:

ln -s "$PWD/skills/novel-characters" ~/.claude/skills/novel-characters

The only hard requirement is Node 18 or later. The README states that the skill scripts use only the Node standard library, so there are no npm dependencies and no `npm install` step. Model quota comes from your existing Claude Code session; no separate API key is needed for the five pipeline skills. `character-refs` is the exception: it requires one of the four image generation backends configured separately.

Quality Gates and Self-Tests

Each skill ships a `scripts/selftest.mjs` that runs all deterministic quality checks without calling any AI model. The README makes this a hard requirement: every skill must have a selftest that runs in under a second. The convention before adding a new skill is to run all existing selftests:

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

The quality gates in each skill check structural constraints that the AI cannot be trusted to enforce on its own: minimum and maximum shot lengths in `novel-storyboard`, episode duration calculations in `novel-script`, asset list completeness in `novel-art`. The README notes that the storyboard skill's 18 quality gates include frame-count verification and prompt-to-timestamp alignment.

All five pipeline skills produce reports with bilingual interfaces: the default language is Chinese and `render --lang en` produces a full English report. The data content stays in its original language. `character-refs` supports Chinese, English, and Japanese interfaces, with other languages translated on the fly.

The README also documents a `scripts/report.mjs` assembler that combines any subset of the five skill outputs into a single-page HTML report with a left-side navigation panel:

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

The assembler handles style and script scope conflicts between the five separate reports automatically.

Repository Layout and Working Directory Conventions

The repository follows a strict layout. Each skill lives in `skills/<skill-name>/` and is self-contained: it can be copied out of the repository and used independently. The required files are a `SKILL.md` for the agent to read and `scripts/selftest.mjs` for the deterministic checks. Reference files go in `references/`, examples and test fixtures in `examples/`, and screenshots in `assets/`.

For a full end-to-end project, the README specifies a working directory structure with one subdirectory per stage:

<demo>/
├── outline/
├── characters/
├── art/
├── script/
├── storyboard/
├── docs/
└── scripts/

The storyboard skill generates per-segment export folders (`E01-01/`, `E01-02/`) inside `storyboard/` alongside the `manifest.json`. The README warns explicitly against nesting these segment folders inside an extra subdirectory: the storyboard report references images by relative path, and adding a nesting level causes all images to silently appear as placeholders without any error message. The README documents this from a specific experience where moving 10 segment folders into a `segments/` subdirectory dropped embedded images from 2 to 0 without the report reporting any error.

Version control convention: commit only the JSON and Markdown files; exclude report HTML and storyboard PNG files with `.gitignore`.

Limitations and License

The README states clearly that the skills have been verified on macOS with Node 24 only. There are no platform-specific calls in the code, and Linux and lower Node versions are expected to work, but this is not tested.

The pipeline produces prompt packages for MiniMax H3 and Seedance video generation. These are specific model families for AI video; teams using other video generation models would need to adapt the export format.

There is no CI configuration. The selftests are fast enough that the README treats local execution as sufficient. The README notes that no CI is configured because the selftests run in about one second.

A practical alternative to shuohao-skills is writing an ad-hoc Claude Code prompt sequence for each stage. The difference is that shuohao-skills provides scripted quality gates that check constraints the AI model cannot be relied upon to enforce on its own, a structured working directory convention that keeps the pipeline's artifacts organized, and a report assembler for the final output. The Apache-2.0 license permits commercial use and modification.

The last push was on 2026-09-26.

Editorial conclusion

shuohao-skills is a good fit for solo creators or small teams who already use Claude Code and want a structured, quality-gated pipeline from novel to storyboard. The skills are self-contained, install via symlink, and do not require API keys beyond your existing Claude Code session quota. The hard constraint is the platform: the README states the tools have been verified on macOS with Node 24. Linux and lower Node versions are expected to work but are untested. Start with `novel-outline` to see whether the 14-gate quality check matches your content's structure before investing time in the downstream skills.

Frequently asked questions

Official sources

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