Write-Screenplay Skill

English · 简体中文

An agent skill that turns novels, outlines and world-building into production-ready micro-drama screenplays — and the asset bible your AI video pipeline needs. Built for vertical short drama (ReelShort, DramaBox, ShortMax, TikTok, Douyin, Kuaishou), with a dedicated overseas mode: English character names, Chinese action and camera lines for the production team, and natural American English dialogue with Chinese subtext notes.

---

Why this exists

In AI short-drama production, the screenplay is the foundation of everything downstream. Every character, every outfit, every prop and every location in the script becomes a reference image that has to be generated and locked; every speaking role becomes a voice that has to be cast. A weak script costs you twice: once on screen, and again in wasted generations.

This skill covers the whole front end:

Novel / outline ──► Long-novel compression ──► Episode outline with cliffhangers ──► Scripts ──► Production bible ──► AI video pipeline
                    (≤60 episodes)              (hook rotation, paywall, midpoint)    (lint)     (characters, wardrobe,   (asset library +
                                                                                                   props, locations, voices) reference-image prompts)

Features

• 🎭 Two writing modes
  • Domestic Chinese — Chinese names, action and dialogue, tuned to Douyin / Kuaishou pacing (3-second hook, 30-second escalation, 60-second payoff, hard cliffhanger).
  • Overseas micro-drama — English character names (enforced), Chinese sluglines and action for the production crew, authentic American English dialogue, and a Chinese subtext line under every line of dialogue.
• 📚 Long-novel mode — compresses a 100+ chapter novel into a fixed episode count (default ≤60): chapter beat cards → compression decisions → weighted episode budget → episode outline → batch writing → continuity ledger. Every stage has a gate and a checker script.
• 🪝 Cliffhanger system — eight hook types, three hook levels with a "hook ladder", a mandatory payoff of the previous hook in the first 10 seconds, genre hook libraries (including non-violent hooks for romance), and automatic rotation checks.
• 🧬 Production bible — four-layer character profiles (drama / voice / visual / casting), wardrobe by phase (a costume change is a new asset ID), prop lifecycles, locations and voices in one bible.json. It cross-checks every script, produces a per-episode asset breakdown with generation priority, and exports an asset library plus reference-image prompts for an AI video pipeline.
• ✍️ Character & dialogue craft — want / need / misbelief, choices under pressure, voice sheets ("what this character never says"), subtext, and the four information tools (mystery, surprise, dramatic irony, suspense) — condensed for two-minute episodes.
• 🎬 AI-video-ready action decoupling — one momentum per micro-shot, open → execute → close for every action, explicit screen-left / screen-right, so diffusion video models don't melt limbs or drift.

Directory structure

write-screenplay-skill/
├── SKILL.md                              # Skill definition (agent-facing, Chinese)
├── README.md / README.zh-CN.md           # This page, in English and Chinese
├── templates/
│   ├── chinese_script_template.md        # Domestic Chinese script template
│   ├── overseas_script_template.md       # Overseas script template
│   └── adaptation/                       # Long-novel mode: parameters, compression decisions, continuity ledger,
│                                         #   episode outline example, episode template, production bible example
├── references/
│   ├── novel-to-script-engine.md         # Novel → script: causal skeleton, externalising interiority
│   ├── overseas-script-protocol.md       # Overseas genres and dialogue rules
│   ├── ai-friendly-beat-decoupling.md    # Action decoupling for AI video
│   ├── long-novel-adaptation.md          # Compression toolbox, episode budget, outline cards
│   ├── episode-hook-system.md            # Eight hook types, hook ladder, open-payoff
│   ├── character-and-dialogue.md         # Character design, voice sheets, subtext, information tools
│   └── production-bible.md               # Characters, wardrobe, props, locations, voices; ID rules; export
└── scripts/                              # Zero-dependency Python 3 tools
    ├── install.py                        # Link the skill into every supported agent
    ├── chapter_index.py                  # Scan chapters → beat-card skeleton (word count, dialogue/text-message share, chapter endings)
    ├── merge_cards.py                    # Merge beat cards written volume by volume
    ├── episode_budget.py                 # Weighted episode allocation per arc; paywall / midpoint / climax checks
    ├── outline_check.py                  # Outline gate: chapter coverage, hook rotation, hook ladder, paywall
    ├── script_lint.py                    # Episode gate: format, dialogue budget, runtime estimate, interiority, ending hook
    ├── bible_check.py                    # Production bible gate, script cross-check, asset breakdown, pipeline export
    └── adapt_common.py

Installation

Option 1 — link into every agent at once

git clone https://github.com/egguy886/write-screenplay-skill.git
cd write-screenplay-skill
python scripts/install.py

This is the beginning of the README. Read the rest at the original. Read the full README ↗