Vertical Short-Drama Script
Transform a novel's story bible or an original short-drama idea into a shootable, machine-checkable vertical short-drama episode script with chapter-to-episode mapping, and seamlessly hand it off to downstream storyboarding.
When to Use / Not to Use
- Use this skill: Adapting a novel into a vertical short drama, writing an original short drama from a concept, creating episode outlines and chapter-to-episode mappings, designing first-3-second hooks / cliffhangers / paywall breakpoints, drafting batches, continuing or reworking episode scripts with approval, or read-only checking of existing scripts for format and duration.
- Do NOT use this skill (boundaries and fallback when uninstalled):
fiction-init: Scaffolds the project structure (AGENTS.md, config,sources.md, bible files). Without a project, first ask the author to run it; if uninstalled, this skill only createsbible/characters.mdand an empty-tablebible/foreshadows.mdper SB §6.2, SB §6.4 (missing either file causesdrama-check.mjsto exit with code 2), informs the author which files are missing and which fallback contract defaults are used, and adds scaffolding completion to the to-do list.fiction-planner: Novel concept planning, marketing variant exploration, genre positioning, and volume outline creation. When working on an original short drama only, this skill handles the short drama project setup itself (logline, emotional promise, protagonist's goal, antagonist's leverage, unit division); hands off tofiction-planneronly if the author also wants to write the concept as a novel or broadly explore genre selling points. If uninstalled, this skill completes only the short-drama side of the project setup. Genre commonalities are checked against installedfiction-craftgenre packs.fiction-chapter: Writes the main body of the novel. If the adaptation progress exceeds the novel's written chapters, the mapping plan rows may point to unwritten chapters (drama-check.mjswill reportmap-sourcesuggestions), but this skill will never write novel text; if uninstalled, it only keeps the plan rows for the author to fill in later.fiction-continuity: Maintains the shared bible (canon rulings, existing shared characters, foreshadowing table, timeline). This skill only appends short-drama-exclusive character blocks withScope: short-drama:{series}tobible/characters.md(SB §6.4, SB §9.1); it does not modify any other bible files. If uninstalled, changes to shared world-building elements are handed over to the author for final commitment.fiction-review: Polishes dialogue and action prose. If the author only requests a review, deliver writing notes first; rewrite the script text only if the author explicitly authorizes it. Structural, duration, paywall, mapping, and hard rule checks are always handled by this skill viadrama-check.mjsandlint.mjs --series. If uninstalled, this skill delivers only structural and machine-check findings, explicitly noting that prose polish was not performed.fiction-storyboard: Next stage (episode scripts → storyboards).fiction-workflow: Cross-stage routing. If any downstream skill is missing, this skill delivers the existing files, a next-action list, and a reminder of un-run checks, but does not perform the downstream skill's tasks.
Before Starting (Step 0)
Open the project root AGENTS.md (especially its "About This Book" section), .fiction/config.json (focus on drama.* settings, see SB §8), and bible/sources.md (the primary source table, SB §5). Priority for writing style: Project's "About This Book" > bible/style-guide.md > this skill's defaults (SB §3). All creative numbers below are adjustable defaults; machine-readable formats strictly follow the contract.
Before writing or modifying any machine-readable file, first open the corresponding format excerpt from the reference table at the end of this document and follow that format. Do not rely on memory.
First, determine the task entry point (three options), then check the source material:
- New project: Not yet started; follow the full workflow based on the source (starting from Step 1).
- Continue / Approved rework: First read the existing
drama/{series}/series.md,adaptation-map.md, and the end of the previous episode or the target episode. Maintain the approved overall setting and mapping; do not redo the project setup. Before overwriting existing episodes or mapping text, obtain explicit author approval[Author]. Go directly to Step 4 → 5 → 6 → re-run checks. - Read-only check: Do not create or modify any files. Jump directly to Step 5, run both scripts, and produce a machine-check and manual-review report.
For new projects or planning, confirm the source and copyright status:
- Mode A (Adaptation from a novel): Has an existing story bible. Follow Steps 1 → 2 → 3 → 4.
- Mode B (Original from a concept): No novel; write
Source: Originalinseries.md, writeOriginalin theSource Chaptercolumn of the mapping table, skip Step 2, proceed from Step 1 to Step 3. - Mode C (Has manuscript, no bible): First hand off to
fiction-initimport mode to extract the bible. If uninstalled, see the Mode C fallback procedure in the Adaptation and Episode Planning Guide (inform about missing files and default configurations, gather material based on chapter numbers and draft rounds confirmed by the author, and log import and setup as to-dos). - Copyright confirmation
[Author]: Only adapt works for which the author holds the copyright or has obtained adaptation rights. Never attempt to reconstruct or patch together external novels from memory based on title.
Workflow
1. Project Setup drama/{series}/series.md
Confirm the English directory slug (^[a-z0-9][a-z0-9-]*$, SB §2). Use the Short Drama Series Template per SB §9.1 to create series.md. Ask the author all questions at once along with reference defaults, write confirmed answers, and never guess platform rules (see Series Setup and Configuration Guide for details):
- Episode Duration and Total Episodes: 60–90 seconds (motion comic / AI short episodes), 90–120 seconds (standard, often 60/80/100 episodes), 150–195 seconds (long episodes, often 30/40/50 episodes, with one long episode roughly equivalent in content to two standard episodes). Write
Episode Duration: N-M, corresponding to the configdrama.tiers(micro≤60,short≤120,standard≤180,longunlimited, SB §8). - Free Episodes and Paywall Breaks: Configure
drama.paywall.first_at(default[8, 15]) andfree_ratio(default[0.05, 0.25]). Reference for first paywall: 60 episodes at 8–11, 80 at 10–15, 100 at 13–19 (or 8–12). If the chosen first paywall falls outside the currentfirst_atorfree_ratiosettings (e.g., 100 episodes choosing 16–19, or a fast-paywall short drama of 30–60 episodes choosing 3–5), remind the author to confirm and adjust the config[Author]. For free/ad-supported dramas, setdrama.paywall.first_attonull(skipspaywall-missingandpaywall-ratiochecks; if the script still contains markers,paywall-positionwill give suggestions, whilepaywall-placementandpaywall-hookchecks still run normally), leaveFree Episodesblank, and do not place<!-- paywall -->tags. - Target Platform, Genre, Main Characters, and Production Format: Each
Main Charactermust have an entry inbible/characters.md(verify by model[Model]); write the production format (Live-action / AI-generated video / Motion comic) in## Production Format. For narration-heavy dramas, remind the author to setdrama.voiceover.os_max/vo_maxtonull. - Free Sections: Add sections as needed:
## Character Arc,## Unit and Pacing Plan,## Adaptation Scope,## Compliance Notes. For Mode B, also add## Original Project Core(emotional promise, protagonist's visible goal, antagonist's leverage) and## Suspense Log.
2. Bible Direct Adaptation (Mode A Only)
Read the bible first, not the novel text. Follow the order extended from SB §4.1: series.md → adaptation-map.md → bible/plot-outline.md → bible/volumes/{vol}.md chapter plan table (SB §7.5) → chapters/{vol}/summary.md (if exists) → bible/subplots.md → bible/foreshadows.md → bible/characters.md → bible/character-dynamics.md → bible/storylines.md → if time is involved, bible/timeline.md.
- Extract a Node Table: Organize by chapter number. 1 Node = 1 visible relationship change, power shift, or information asymmetry flip. Extract from each row in
character-dynamics.md, steps ②③⑤⑥ insubplots.md, buried/triggered/collected chapters inforeshadows.md, andheavychapters in the volume plan table (see Adaptation and Episode Planning Guide for details). - Only open the source novel text for these four specific reasons (determination of a final draft per SB §7.1): (a) When writing a batch, open the
Source Chapterfor that batch to extract props, imagery, settings, and direct quotes; (b) When bible information for a chapter segment is too thin; (c) To verify facts in a frozen chapter (frozen chapter text takes precedence over bible, per SB §3 rule 1); (d) Whensummary.mdconflicts with the bible (report the conflict verbatim to the author; do not adjudicate yourself). Never skim the entire novel out of fear of missing something (SB §1).
3. Episode Planning → drama/{series}/adaptation-map.md
Use the Chapter-to-Episode Mapping Template per SB §9.2 to create the mapping table (can start with plan rows and fill in after writing episodes). Arrange units, key episodes, and paywall placements in series.md's ## Unit and Pacing Plan section; do not add new columns to the mapping table. See Adaptation and Episode Planning Guide and Paywall Breaks and Hook Design for details:
- Node Ratio: For ≤120 second episodes, 1 node per episode (one push & one block, or one setup & one payoff). For 150–195 second episodes, 2 nodes + a midpoint hook around the 50% mark. If nodes are insufficient, add conflicts, create rounds, or reduce the total episode count. If nodes are excessive, cut subplots or split into seasons. For long novels exceeding 200 chapters, the first season typically covers the first third and collects the strongest 20 most iconic scenes.
- Cutting / Merging / Reordering: 1 main plot + at most 1 subplot. Classify minor plots per SB §6.3 (A: retain and compress; B: compress into props or single lines integrated into the main plot, or retain if carrying a paywall; C: delete unless carrying a retained foreshadow). Merge characters with overlapping functions (default: 1–5 main characters, ≤10 named supporting characters, ≤10 functional extras using tags). Delete training sequences, travel montages, and transitional scenes. Reordering is driven by paywall layout, but must not violate the set-up-before-payoff rule (
map-order) or hard anchors intimeline.md. Log all changes in theChangescolumn. - Units, Key Episodes, and Paywalls: Each unit is 20–30 episodes (long episodes: 10–15 episodes), roughly equivalent to 1 novel volume. Four-act structure: roughly 20/35/25/20%. Key episodes: approximately 25%–35%. High-suspense episodes: approximately 10%–15%. The first 10 episodes should contain ≥3 key episodes and ≥2 high-suspense episodes (this is a reference method, not a machine-check rule). The 2–3 episodes before a paywall should build pressure step by step; cut before a counterattack or truth reveal (about 0.5 seconds before the reveal). Within the first 15 seconds of the first paid episode, deliver on the promised payoff. The free segment must establish the core conflict, leave ≥3 hanging questions, and provide a reward. For revenge/up-from-the-bottom stories, default to ≤3 episodes before the antagonist pays a visible price. Place
<!-- paywall -->at the end of the last free episode, after<!-- hook: X -->(e.g., marking the end of episode 10 means episode 11 begins the paywall). The episode number of the first<!-- paywall -->marker is written intoFree Episodes. Subsequent markers are added only if the platform adopts a tiered paywall unlock system. - Foreshadowing Scope: Write the
Foreshadowingcolumn per SB §7.3 asPlant/Trigger/Payoff/Abort + F-ID. The script only shows what theReader Knows; keep theAuthor Truthuntil the planned payoff episode. Never write back to thebible/foreshadows.mdstatus column (SB §9.2). For Mode B, keep the foreshadowing table empty, leave theForeshadowingcolumn blank, and track suspense inseries.md's## Suspense Log. - Author's Three Decisions Before Starting
[Author]: Which plots to cut, which characters to merge, and the placement of major nodes and paywalls. Plan episode summaries in batches of ≤10 episodes.
4. Batch Episode Writing drama/{series}/episodes/ep{NNN}.md
Write batches of ≤5 episodes at a time. Start from adaptation-map.md, the previous episode's ending, and relevant bible files. Do not carry over the full text of previous batches. Write per SB §9.3 and the Episode Script Template. The Status field takes only Draft / Revision / Final (new submissions use Draft). Write Target Duration only if it differs from the series default. See Episode Writing Techniques for details:
- Opening and Continuation: The first content line of scene 1 must be a visible action with movement. The first 3 beats must present a captivating image. Prohibit: waking up and drawing curtains, driving scenes longer than 2 seconds, background narration, casual chatter, slow landscape shots, crowded openings with multiple characters, and starting with OS/VO (
voiceover-open). Acknowledge the previous episode's cliffhanger but do not immediately resolve it. Within the first ~5 lines of episode 1, establish "Who wants what + a number or deadline." For exciting/revenge dramas, deliver the first counterattack within 35–45 seconds. - Pacing and Scene Count: 90–120 second episodes follow a four-beat structure (0–15s: grab attention & establish stakes → 15–45s: confrontation → 45–85s: reveal cards & visible consequence → 85–110s: aftermath & hook). Ensure visible change every 15–30 seconds; do not repeat the same argument without changing location. For 150–195 second episodes, split into two rounds at roughly the 50% mark with a midpoint hook, with a B-round escalation. Default scene count: ≤2 for 90–120 seconds, ≤3 for 150–195 seconds, 1–2 for ≤60 seconds. Config
drama.max_scenes(default 5) is an upper limit only. - Cliffhangers and Hooks: The last beat must be an open action, an unanswered question, or an unresolved sound. Do not write a summary sentence. Place exactly one
<!-- hook: X -->after the last scene (S > A > B > C, per SB §7.2). Use S for paywall and unit endings, A for standard endings, B for buffer endings, and avoid C. - Dialogue, Action, Shots, and OS/VO: Insert one action or reaction line for every 2–4 lines of dialogue (2–3 for tight dramatic scenes). The
dialogue_run_maxdefault of 6 is an upper limit only. Keep one sentence per breath; typically ≤25 characters, split if exceeding 35. For general dialogue techniques, consultfiction-craft. Action lines are in present tense, describing only visible and audible facts. Prohibit: pseudo-actions using negation, micro-expressions, smells/tastes, or internal thoughts. Props must have a clear origin. For AI video, write only common everyday actions. Use【Shot】sparingly; do not include shot numbers or prompt words (the script handles the drama, the storyboard handles the filming). OS/VO is limited to five valid purposes; prohibit: exposition dumping, repeating actions, substituting for confrontation, two consecutive lines, and placement immediately before a hook. Default configos_maxis2,vo_maxis1. For standard episodes, OS ≤1 is recommended. - Character Voice and Revisions: Write dialogue according to the latest state in
characters.md,character-dynamics.md, andstyle-guide.md(it should be identifiable who is speaking even with names removed). After finishing a beat, re-read the surrounding beats to verify character positions, props in hand, and who is present.
5. Machine Checks (Run After Each Batch and for Read-Only Checks)
Run these scripts from the project root (see --help for full parameters):
node <this skill's directory>/scripts/drama-check.mjs <series> --ep N-M
node <this skill's directory>/scripts/lint.mjs --series <series>
For full-series read-only checks, omit --ep. --ep N-M only limits per-episode rules; series-level rules always run on the entire series. Clear all block results. For each suggest result, review against the Machine Check Guide:
unshootable(UA01–UA04,UA11,UA12): Rewrite as visible action; retain only if it's a clearly shootable reaction close-up.dialogue-run: Insert an action or reaction to break the run; retain only for intentionally rapid-fire dialogue.voiceover-quota: Reduce or convert to action; retain only for narration-heavy dramas (or set the corresponding config items tonull).voiceover-open: Always rewrite to start with an action.
drama-check.mjs does not support inline waiver comments. For any retained suggest, note "Reviewed and retained: reason" in the report. The length estimate is calculated only as character count ÷ chars_per_minute and does not equal actual filming duration.
6. Backfill and Recheck
- Complete the rows for this batch in
drama/{series}/adaptation-map.md:Characters: based on actual appearances.Foreshadowing: based on actual actions.Changes: write the reason for merges, cuts, or reordering (SB §9.2).
- For Mode B original dramas, simultaneously update the
## Suspense Loginseries.mdbased on actual planting, revealing, and payoff (includingActual Payoff EpisodeandStatus), and verify thatBehind-the-Scenes Truthhas not been leaked. - For new short-drama-exclusive characters: append a block to
bible/characters.mdmarked with- Scope: short-drama:{series}(SB §6.4). Log any adjustments that apply only to the short drama inseries.md's## Adaptation Scope. According tofiction-continuity's conflict priority (SB §3), only write shared world-building rulings that were explicitly confirmed by the author during this workflow and are conflict-free intobible/canon.md. Unconfirmed or conflicting rulings are handed tofiction-continuity. - Never modify novel chapters,
bible/foreshadows.md, or existing shared character entries. If a source chapter from the original novel is later revised, list the affected episode numbers for the author to recheck. - After backfilling and reworking, ALWAYS re-run the two scripts from Step 5 to prevent backfill from introducing
map-foreshadow,map-order, orparseblocking errors. Acceptance is based only on the latest script results.
7. Compliance and Likeness / Copyright Checks
At the end of each batch and before finalizing the entire series, the model first flags potential issues [Model]. Then, following the Compliance and Copyright Checklist, the author confirms each item [Author] (real-name desensitization is done in conjunction with lint.mjs --series [Script]). Always state "Subject to the currently effective official texts of the platform and regulatory authorities." Do not cite specific regulation numbers or dates. Log the check date in series.md's ## Compliance Notes.
8. Handoff to fiction-storyboard
Handoff must meet all four conditions simultaneously (based on the final files after backfill and rework):
- The latest run of
drama-check.mjsandlint.mjs --seriesboth executed successfully with exit code 0; provide both results for the series to storyboarding. - The target episode numbers for this batch all appear in
drama-check.mjs'sepisodes[]array. - The corresponding rows in
adaptation-map.mdhave been completed (storyboards rely on plant/payoff pairs to avoid spoilers). - The author has changed the script
StatustoFinal[Author].
If an episode that already has a storyboard is later revised, first provide the affected episode numbers and the list of changes to fiction-storyboard for rechecking and syncing, then pass to fiction-visual-prompts for prompt updates. This order is irreversible. This skill does not touch storyboards/ or prompts/. If any downstream skill is missing, deliver the final files, a to-do list, and a reminder of un-run checks.
Checklist
- Format, scene headings, dialogue lines, hooks, and paywall markers
[Script] - Duration estimate and tier
[Script] - Paywall episode position, ratio, and hook minimum
[Script] - Mapping table F-ID / character existence, plant-before-payoff
[Script] - Unshootable action patterns, dialogue runs, OS/VO count and opening
[Script] - Prohibited words, desensitization, exact years, internal references
[Script] - Main characters in
series.mdare filed, short-drama characters have correctScope, mapping matches actual script appearances, episodeStatususes only the three valid values[Model] - Each episode hits a qualitative change node (standard episodes: 1 node; long episodes: 2 nodes including a midpoint hook; covering relationship, power, or information changes)
[Model] - First 3 beats are engaging with movement, connects to previous episode
[Model] - Cliffhanger is an open moment, not a summary
[Model] - Build pressure before paywall, deliver payoff in first 15 seconds of paid episode
[Model] - Action lines are visible and audible
[Model] - Character voice is distinguishable
[Model] - Do not prematurely reveal the author's truth
[Model] - Plots cut, characters merged, paywall positions
[Author] - Duration tier, total episodes, platform, paywall scheme
[Author] - Canon changes from adaptation
[Author] - Final draft
[Author] - Compliance, likeness, copyright
[Author]
Deliverables and Report
Deliverables: drama/{series}/series.md, drama/{series}/adaptation-map.md, this batch's drama/{series}/episodes/ep{NNN}.md, and (if new) the short-drama character block in bible/characters.md. After each batch, provide a summary to the author covering four items:
- This Batch's Progress: Episode number range, core nodes, estimated duration range, and hook/paywall placements.
- Final Machine Check Results: Exit codes from the latest
drama-check.mjsandlint.mjs --seriesafter backfill,episodes[]coverage, and statistics onblock/suggestitems. For each retainedsuggest, note "Reviewed and retained: reason." - Backfill and Changes: Mapping table updates, suspense log updates (Mode B), new short-drama characters added, and entries in
## Adaptation Scope. List any conflicts with the original novel or pending canon rulings separately. - Pending Author Confirmation: Items requiring a decision, compliance check date, and whether to change
Status: Finalfor handoff tofiction-storyboard(if the downstream skill is missing, include the to-do list and un-run checks).
Reference Documents
| If you need... | Read this |
|---|---|
| Directory paths, conflict rulings, primary writing sources, or downstream order after script changes | SB §1–§5: Project Structure and Reading/Writing Rules |
Foreshadowing table, subplot classification, character Scope field, relationship log, or timeline format | SB §6: Bible Machine-Readable Format |
| Final draft determination, hook grades (S/A/B/C), foreshadowing actions, or volume plan table | SB §6.1, §7: Chapter Files |
Before writing series.md, adaptation-map.md, or ep{NNN}.md, check the format | SB §6.1, §9.0–§9.3: Short Drama Scripts |
drama.* tiers, paywalls, dialogue/OS/VO, or desensitization config keys | SB §8: Project Configuration |
| Direct adaptation from novel bible, Mode C fallback, node extraction, cutting/merging/reordering, or source chapter revision recheck | Adaptation and Episode Planning Guide |
| Project setup questions, duration/episode presets, free or narration drama config, or original short drama startup | Series Setup and Configuration Guide |
| Arranging three-tier paywalls, selecting suspense patterns, controlling key episode ratio, or long-episode midpoint hooks | Paywall Breaks and Hook Design |
| Writing first-3-beat openings, four-beat pacing, shootable action lines, OS/VO tradeoffs, and character voice verification | Episode Writing Techniques |
Handling specific drama-check and lint --series errors or interpreting JSON output | Machine Check Guide |
| Author self-check list for genre red lines, likeness, copyright, and AI labeling | Compliance and Copyright Checklist |