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';

const enhanceBlock = buildScreenwriterEnhanceUserBlock({
  voices: inferVoiceFingerprintsFromCharacters(plan.characters),
  budgets: buildDefaultSceneBudgets(plan.scenes, plan.storyStructure.totalShots),
  // bible: [...],  // optional, wire up when user adds Story Bible UI
});

// Append to existing userContext — no prompt refactor needed
userContext = `${userContext}\n${enhanceBlock}`;

This works with every existing LLM path (OpenAI, Claude, local Ollama) because it's pure text injection.

Full critic-rewrite path (premium tier)

When latency budget allows (20–60s extra):

import { runCriticRewriteLoop, buildCriticSystemPrompt, buildCriticUserPrompt,
         buildRewritePrompt, parseCriticFeedback } from '@/lib/screenwriter-enhance';

const { finalDraft, rounds, finalScore } = await runCriticRewriteLoop({
  initialDraft: script,
  critic: async (draft) => {
    const raw = await callLLM(
      buildCriticSystemPrompt(),
      buildCriticUserPrompt(draft, storyBibleBlock),
      true,  // JSON mode
    );
    return parseCriticFeedback(raw);
  },
  rewriter: async (draft, feedback) => {
    const raw = await callLLM(
      systemPrompt,
      buildRewritePrompt(feedback, draft),
      true,
    );
    return JSON.parse(raw);
  },
  opts: { targetScore: 85, maxRounds: 2 },
  onRound: (r, s, fb) => console.log(`round ${r}: ${s}/100 — ${fb.fixes.length} fixes`),
});

Cross-references (kebab-case Claude Skills convention)

This skill composes with:

• mckee-skill (lib/mckee-skill.ts) — the base McKee prompt library
• seedance-enhance (lib/seedance-enhance.ts) — downstream visual-consistency primitives
• content-generation (skills/base/content-generation.md) — generic generation primitives

Quality guardrails (non-negotiables)

Even in fastest path (no critic), the Pass-1 prompt must enforce:

• Shot 1 is a hook — never open on "protagonist wakes up / walks / looks at view"
• Act 1 ends with an irreversible inciting incident — the choice can't be un-made
• Act 2 midpoint has a reversal/cost reveal — not smooth-sailing
• Shot N-1 forces an irreversible choice exposing true character
• Emotion curve oscillates — monotone up/down = fail
• Every shot's start-value ≠ end-value — "calm → calm" = waste

These are encoded in getMcKeeWriterPrompt() and re-stated in buildCriticSystemPrompt().

Anti-patterns

Do NOT:

• Feed the raw source text + enhance block + critic prompt all at once (context will blow). Split into stages.
• Run critic-rewrite more than 2 rounds — diminishing returns, over-cooking.
• Skip Story Bible when adapting existing IP — that's where consistency failures originate.
• Mix voice fingerprint register within a single character across scenes.
• Hand-edit the JSON output to "fix" the structure — re-prompt with buildRewritePrompt() so the critic can re-score.

Research lineage

Primitive	Source
Voice Fingerprint	Sudowrite Story Bible + NovelCrafter Codex (2024-2026)
Story Bible Block	Sudowrite, NovelCrafter (commercial), adapted to plaintext
Budget Plan	THUDM LongWriter / AgentWrite (arXiv:2408.07055)
Critic-Rewrite Loop	Dramaturge (arXiv:2411.18416), +22-57% quality
Two-Pass planning → JSON	DeepMind Dramatron (arXiv:2209.14958, Apache-2.0)
11-dim critic	Our extension of McKee's Story to machine-checkable dims
SKILL.md format	anthropics/skills (2025-10)

Versioning

• v1.0.0 (2026-04) — initial release. Five primitives + critic-rewrite loop + SKILL.md.

Breaking changes will bump MAJOR. New primitives or prompt improvements bump MINOR.