Scrivener Scriptwriting

Scrivener Scriptwriting

You help the writer use Scrivener 3's script mode to draft screenplays, stage plays, and other formatted scripts, and to move that work in and out as Fountain (the plain-text screenplay format). The core idea to teach: in script mode, the element of each line — Scene Heading, Action, Character, Dialogue, and so on — is encoded by the paragraph's formatting, so any tool that rewrites formatting blindly can quietly destroy a script.

Most of the dedicated script tooling is planned, not yet in the CLI. Be honest about that and steer the writer to the closest available command.

When to use this skill

• "I want to write a screenplay in Scrivener." / "Turn this document into script mode."
• "Set the whole Draft to script mode." / "What script-format settings is this using?"
• "Compile / export my screenplay to Fountain."
• "Import this .fountain file as a screenplay."
• Before any project-wide formatting change, to check whether script docs are in scope.

How script mode works (teach this)

• Script mode is a per-document flag, stored in the binder item's <MetaData> / <TextSettings> inside the .scrivx. One document can be in script mode while its neighbors are normal prose — it is not a project-wide switch.

• In a script-mode document, every paragraph is one script element. Scrivener recognizes the element by the paragraph's formatting (indents, alignment, spacing, caps), not by markup or a hidden tag. Standard elements:

  Element	What it is
  Scene Heading	INT./EXT. LOCATION — TIME slugline
  Action	description / stage direction
  Character	the speaking character's name (cued above dialogue)
  Parenthetical	(beat) / delivery note under a Character
  Dialogue	the spoken lines
  Transition	CUT TO: etc.
  Shot	camera direction

• The mapping of element → exact formatting (and Tab/Return cycling between elements) is the document's script-format settings, which persist in the .scriv (script-settings / .scrformat data) so the format travels with the project.

The formatting hazard (most important warning)

Because elements are defined by paragraph formatting, a blind project-wide font/format rewrite breaks scripts. If scrivener-formatting runs something like format set-font --scope project or re-aligns/re-indents every paragraph across the whole project, it will overwrite the very indents and alignment that are the script elements — Scene Headings, Character cues, and Dialogue stop being recognized as those elements.

So, whenever a bulk formatting change is requested:

• Identify script-mode documents first and warn the writer that they are in scope.
• Exclude script docs from the bulk change (scope to specific non-script subtrees or documents instead of --scope project), or change them only through their script-format settings, never with direct formatting.
• This is the same caution scrivener-formatting raises from the other side — keep the two skills in sync.

Fountain in and out

Fountain is a plain-text screenplay markup. It is the supported script interchange format (Final Draft .fdx is a deferred non-goal). The element ↔ Fountain mapping is in references/scriptwriting.md. At a glance:

Toolkit support

🔜 Planned (not yet in the CLI) — describe the workflow, say it isn't built, offer the fallback:

• script set-mode <id> --on|--off — toggle a document's script-mode flag.
• script settings — read/set the per-document script-format settings (element → formatting map) that persist in the .scriv.
• Fountain import — handled via scrivener-import (import … --to fountain workflow), not yet wired in the CLI.
• Compile to Fountain — handled via scrivener-compile (compile --to fountain), also on the roadmap.

There is no available-today command that toggles script mode or reads/writes Fountain. Until those ship:

• To inspect a document, use scrivener-inspect's read <id> and report whether the text reads like a script; you cannot yet flip the flag from the CLI.
• For Fountain interchange, the manual path is to set script mode and choose Fountain in Scrivener's own Import/Compile dialogs.

# Available today: inspect the document you intend to put in script mode.
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py read <uuid> --project "<path.scriv>"

# Planned (NOT yet in the CLI) — shown so the writer knows the intended shape:
# python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py script set-mode <uuid> --on --project "<path.scriv>"
# python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py compile --to fountain --project "<path.scriv>" --out screenplay.fountain

Safety

• Close the project in Scrivener and let cloud sync (Dropbox/iCloud) finish before any write — editing a .scriv mid-sync can corrupt or conflict it.
• Writes auto-backup (zip) the project and auto-snapshot a document before overwriting its text. Never regenerate a rich/script document from plain text — append or snapshot and pass --allow-destructive.
• Binder titles are not unique — use a UUID for any mutating command when a title is ambiguous.
• Most of this skill is roadmap. Do not claim a script/Fountain command ran when it is planned — name it as planned and offer the closest available step.

Related skills

• scrivener-compile — assemble/export the Draft; the planned home of compile --to fountain (Fountain out).
• scrivener-import — bring outside material in; the planned home of Fountain import (Fountain in).
• scrivener-formatting — direct formatting; coordinate with it so a project-wide font/format change excludes script-mode documents and does not break their element formatting.