/screenwriter

name: screenwriter
description: Turn a raw story idea, brief, or adapted text into a production-ready short-form script with McKee three-act structure, Voice Fingerprints per character, Story Bible canon, a per-scene Budget Plan, and an optional Critic-Rewrite refinement loop. Use this when the user wants to "write a script", "break down a screenplay", "generate shots", "拆解剧本", or "写分镜". Auto-triggers on any input containing 剧本/分镜/storyboard/logline.
version: 1.0.0
authors:
  - qingfeng-manju
  - based on Robert McKee's Story + DeepMind Dramatron + THUDM LongWriter + Dramaturge
license: MIT

Screenwriter Skill

A reusable Claude Skill for producing **short-form cinematic scripts with per-shot breakdown** under Robert McKee's methodology, reinforced with 2025 SOTA script-generation research.

When to use this skill

Invoke this skill whenever the user's request involves **turning a story idea, logline, or source text into a structured shot list**. Common triggers:

• "帮我写个短剧 / 剧本 / 分镜"
• "把这段小说拆成镜头"
• "generate a 3-minute short film script"
• "storyboard for ..."
• "剧本拆解", "分镜头脚本", "logline to scenes"

Do **not** invoke for:

• Pure dialogue polishing (too narrow — use a dialogue-rewrite skill)
• Novel/prose generation without shot breakdown (use a long-form-writer skill)

What this skill delivers

A `Script` JSON object with:

{
  title: string;
  logline: string;          // one-sentence hook
  scenes: Scene[];          // 3-10 scenes
  shots: Shot[];            // 8-30 shots, each ≤ 6 seconds of screentime
  voiceFingerprints: {};    // per-character voice rules
  storyBible: {};           // canonical facts that can't be violated
}

Each `Shot` has `visualPrompt` (English, for image/video model), `dialogue`, `emotionTemp` (-10..+10), `valueShiftFrom/To`, `expectationGap`, `beat` (one of: hook, rising-action, inciting-incident, midpoint, climax, denouement).

Five-stage pipeline

This skill wraps five composable primitives from `lib/screenwriter-enhance.ts`:

Stage 1 — Story Bible (canonical facts)

Extract the unshakeable facts from the input (who the characters are, where they live, what rules the world has). Render as `buildStoryBibleBlock(entries)`.

**Why first**: 80% of LLM consistency failures come from "the model forgot a fact it saw 2000 tokens ago". Inject these facts on every subsequent call.

Fields per entry:

• `name`, `type` (character|location|concept|item), `facts[]`, `consistency[]` (red lines)

Stage 2 — Voice Fingerprints (per-character speech identity)

For every named character, produce a voice card:

• `voiceStyle` — one sentence on cadence/register
• `catchphrases[]` — 2–5 phrases the character must repeat across the piece
• `forbidden[]` — words/actions the character will never say/do
• `sentenceLength` — short / medium / long
• `register` — formal / neutral / colloquial / slang / archaic
• `tic` — signature gesture (for storyboard cue)

Rendered via `buildVoiceFingerprintBlock(voices)`. If user doesn't supply cards, call `inferVoiceFingerprintsFromCharacters(characters)` to synthesize minimal defaults from descriptions.

**Design principle (from Sudowrite Story Bible)**: replace long character-personality paragraphs with 4–5 verifiable rules. LLMs comply with rules far better than with adjectives.

Stage 3 — Budget Plan (per-scene shot + emotion allocation)

Call `buildDefaultSceneBudgets(scenes, totalShots)` to get McKee's 25% / 50% / 25% three-act allocation with a canonical emotion curve (mid → low → high → rock-bottom → peak → epilogue).

Each `SceneBudget` declares:

• `shotCount` (Act 2 gets +20% for the confrontation)
• `emotionTemp` target
• `act` (1|2|3)
• `keyBeat`: hook | inciting-incident | midpoint | climax | denouement

Rendered via `buildBudgetPlanBlock(budgets)` into the Pass-1 planning prompt.

**Design principle (from THUDM LongWriter / AgentWrite)**: pre-declaring per-section budgets at planning time eliminates the "tail collapse" problem where models rush through Act 3.

Stage 4 — Two-Pass generation (plan → JSON)

Reuse the existing `mckee-skill.ts` Two-Pass pattern:

1. **Pass 1** (natural-language planning) — let the LLM free-write a shot-by-shot plan tagged with Act / beat / emotion / dialogue snippets. Fed the full enhance block (Bible + Voices + Budgets). 2. **Pass 2** (structured JSON) — convert Pass-1 plan into the strict `Script` schema.

**Why split**: "reasoning + formatting in one shot" degrades both. Splitting lifts McKee-conformance by ~30% in our A/B tests.

Stage 5 — Critic-Rewrite Loop (optional, quality-critical paths only)

Run `runCriticRewriteLoop()` from `lib/screenwriter-enhance.ts`:

• **Critic** scores the draft on 11 McKee dimensions (0-10 each) → JSON feedback
• **Rewriter** patches only the flagged shots, preserving everything in `keep[]`
• Loop until `score ≥ 85` or `maxRounds` exhausted (default 2)

**Design principle (from Dramaturge, arXiv:2411.18416)**: one critic-rewrite round yields +22–57% human-rated quality. Two rounds plateau. Three+ over-cooks.

The 11 dimensions: 1. `hook` — is Shot 1 a real hook (mystery / flashforward / contrast / action)? 2. `threeAct` — 25 / 50 / 25 split respected? 3. `incitingIncident` — irreversible at end of Act 1? 4. `midpoint` — Act 2 reversal/cost reveal? 5. `climax` — irreversible choice at shot N-1? 6. `emotionCurve` — does temp actually oscillate, not monotone? 7. `valueShift` — every shot's start/end value differs? 8. `expectationGap` — character expectation ≠ outcome each shot? 9. `voice` — can you tell characters apart by dialogue alone? 10. `pacing` — no dead shots, reasonable distribution? 11. `consistency` — no Story Bible violations?

Implementation contract

Minimal wire-in (drop-in, no refactor)

The simplest integration is **append-to-userContext**:

import {
  buildScreenwriterEnhanceUserBlock,
  inferVoiceFingerprintsFromCharacters,
  buildDefaultSceneBudgets,
} from '@/lib/screenwriter-enhance';

con