[δΈζ](README.md) Β· **English**
> π **Open to work / collaboration** β I'm between jobs right now, and this repo is what I build in that spare time.
> Happy to hear from anyone this resonates with. Besides **remote work**, I'm also open to a **half-collaboration**: a few thousand RMB a month for living costs plus a profit share. On-site trips are possible where the work genuinely needs them. What I'm really after is finding people on the same wavelength to build something in this AI wave.
> Email: **[eternityspring@gmail.com](mailto:eternityspring@gmail.com)** Β· RΓ©sumΓ©: **[resume.79px.com](https://resume.79px.com)** Β· WeChat **`hao_dev`** (please mention `github` when you add me)
>
> These skills are free and open source, built and battle-tested on real AI short-drama production.
> If they save you an afternoon, consider [**buying me a coffee on Ko-fi**](https://ko-fi.com/eternityspring) β β it keeps the updates coming.
# shuohao-skills
**Agent skills for AI short-drama production** β from a novel to shoot-ready material: character bibles, adaptation outlines, scene & prop bibles, screenplays, storyboards. Built for AI coding agents, **runs in both Claude Code and codex**.
Here is the whole pipeline β **the outline converges the structure; script, scenes and characters iterate together; the storyboard only outputs, it makes no new decisions**:
| Skill | What it does |
| --- | --- |
| [**novel-outline**](skills/novel-outline/README.en.md) | Adapts a novel into a five-piece short-drama outline: adaptation notes, cast, beats, per-episode synopses, asset list (including a narrative-prop table). All 14 quality gates are script-checked; includes a checkup mode for existing outlines |
| [**novel-characters**](skills/novel-characters/README.en.md) | Turns the cast the outline settled on into a character bible: profiles, design prompts, voice prompts, model sheets. Seeds the roster from outline.json; report language and image style are both configurable |
| [**novel-art**](skills/novel-art/README.en.md) | Art bibles for AI production (scenes + narrative props): consistency anchors, lighting & state variants, scale references, no-people/no-hands white plates. Seeds from outline.json; all 11 quality gates script-checked |
| [**novel-script**](skills/novel-script/README.en.md) | Screenwriting for AI short drama: scenes + beat flow (action beats alternating with dialogue lines), per-episode duration deterministically estimated from reading speed, a gated cold-open hook in the first 3 beats, a per-character line book with voice prompts that feeds straight into TTS. All 10 quality gates script-checked |
| [**novel-storyboard**](skills/novel-storyboard/README.en.md) | Storyboarding for AI short drama: segments (one generation, β€15s) β cuts (2β5s hard gate) β keyframes (master pinned at 0.00s, sub-frames at their cut marks), with MiniMax H3 prompt alignment and cut times audited verbatim; frames actually generated with the design sheets as references, plus one-command H3 production packs. All 17 quality gates script-checked (the 17th audits shot-recipes cards when the library is mounted) |
Off to the side of the pipeline there is a **shot vocabulary library** that none of the five skills is required to mount:
| Skill | What it does |
| --- | --- |
| [**shot-recipes**](skills/shot-recipes/README.en.md) | A shot vocabulary library for generative AI video β 67 cards in two families: **recipe cards** (17) answer "how should this cut in this scene be taken", **technique cards** (50) answer "what this device is, when to use it, and **when not to**" across camera move, angle, shot size, composition, lens & depth, lighting and special technique. **All 20 official H3 camera terms are covered, and completeness itself is a gate** β `lint` names any domain item nobody wrote. **Useful well beyond short drama** (product promos, explainers, vlogs). Every card declares must-have phrases that can be machine-audited; `novel-storyboard` can optionally mount the library with `--shots` |
**Every skill renders its report in English too** β reports default to a Chinese UI; pass `--lang en` to `render` for a fully English report (data content stays as authored).
## One page for the whole pipeline
The five stage reports can be merged into a single page with a left-hand nav β **you get a pane for every stage you actually have**:
```bash
node scripts/report.mjs --from --out report.html
```
`--from` discovers the five json files using the [working-directory convention](#repository-conventions); you can also point at each one directly (`--outline` `--cast` `--art` `--script` `--storyboard`). Ran only the character pass? You get one pane, no error.
It is an **assembler, not a sixth skill**: it imports no skill code, it shells out to each skill's own `render --html` and stitches the results. So the six skills stay untouched, still run standalone, and are still copyable on their own β and when a skill changes its rendering, this picks it up for free.
Merging solves three problems, **all of them inside the assembler, none inside the skills**:
- **Style bleed.** The five reports share 57 class names, 13 of which mean different things in different reports (`.copy`, `.kpis`, `.badge`, `.chip`β¦), so every selector gets a scope prefix
- **Script bleed.** Each report's script does document-wide lookups like `document.querySelector('.expo')`. Merged, that only ever finds the first one β all five export buttons would break. Each script gets wrapped in a scoping proxy
- **Asset paths.** Each report's images are relative to its own json directory (`images/β¦`, `E01-01/f1.png`) and get rebased against the output file
One pane shows at a time by default (the five together run to roughly 600k characters). "Show all" in the bottom-left expands every pane so Cmd+F reaches the whole document. Number keys `1`β`5` switch panes, and `#pane-script` deep-links straight to one.
```bash
node scripts/report-selftest.mjs # 92 assertions, no browser needed
```
Point it at a novel and you get all five:
**novel-outline Β· short-drama adaptation outline**
**novel-characters Β· character bible**
**novel-art Β· art bible (scenes + props, sheets actually generated by the skill)**
**novel-script Β· screenplay (duration gauge + episode scripts + line book)**
**novel-storyboard Β· storyboard (cut rhythm strip + master/sub keyframes actually generated by the skill + H3 prompts)**
And off the pipeline, the shot recipe gallery β **an empty cell in the category Γ energy matrix is a vocabulary gap**:
**shot-recipes Β· shot recipe library (category Γ energy matrix + card wall, example frames actually generated by the skill)**
## Install
```bash
git clone https://github.com/eternityspring/shuohao-skills.git
cd shuohao-skills
./scripts/install.sh
```
It detects whether you have Claude Code or codex installed and **symlinks** every skill into place β so `git pull` takes effect immediately, with no reinstall.
```bash
./scripts/install.sh novel-characters # just one skill
./scripts/install.sh --codex # only into codex
./scripts/install.sh --uninstall # remove the symlinks
```
Prefer to do it by hand:
```bash
ln -s "$PWD/skills/novel-characters" ~/.claude/skills/novel-characters
ln -s "$PWD/skills/novel-characters" ~/.codex/skills/novel-characters
```
## Requirements
| | Required? | Notes |
| --- | --- | --- |
| **Node** | Yes | β₯ 18. The skill scripts use only the standard library β **no npm dependencies, nothing to install** |
| **Model quota** | Yes | Uses your current session's quota. **No API key needed** |
| **codex CLI** | Optional | Only for image generation (via its built-in `$imagegen`). Without it, image steps are skipped and everything else still runs |
> **Note on output language.** These skills are Chinese-first. `novel-characters` produces Chinese character profiles even for an English source novel, and its validator actively rejects English in those fields. See that skill's README for what it would take to change.
## Repository conventions
One directory per skill, **self-contained and copyable on its own**:
```
skills//
βββ SKILL.md the workflow the agent reads (required)
βββ README.md the docs a human reads
βββ scripts/
β βββ .mjs deterministic helpers, zero dependencies
β βββ selftest.mjs self-test, never calls a model (required)
βββ references/ detailed instructions, loaded on demand
βββ examples/ bundled samples that double as test fixtures
βββ assets/ screenshots
```
Two hard requirements:
- Every skill must have a `SKILL.md`
- Every skill must have a `scripts/selftest.mjs` that **calls no model and costs no quota**, covering all deterministic logic
Run every self-test before adding a skill:
```bash
for f in skills/*/scripts/selftest.mjs; do node "$f"; done
```
There is no CI β the self-tests run in about a second, so running them locally beats waiting on a pipeline. **Only tested on macOS with Node 24**; there is no platform-specific code, so Linux and older Node releases should be fine, but that is unverified.
## License
[Apache 2.0](LICENSE)