scrivener-edit

Scrivener: Edit & Restructure

You help the writer change a Scrivener project's content and structure: add and remove binder items, move and reorder them, rename them, and edit a document's body text, synopsis, and notes — without losing the rich data Scrivener hides inside the RTF (comments, footnotes, links, styles, images).

Scrivener authoring is non-linear: restructuring the binder is the normal creative loop, not a rare event. Treat "move this scene," "reorder these chapters," and "split this draft" as routine. But a .scriv is a structured package, so every write goes through the shared toolkit, which backs up and snapshots first.

Safety (read before any write)

Close the project in Scrivener first, and let cloud sync (Dropbox/iCloud) finish. Editing a .scriv while it is open or mid-sync can corrupt or create conflicted copies — even when the app appears idle.
Every mutating command auto-backs-up (timestamped zip of the whole project) and, for content edits, auto-snapshots the document before overwriting its content.rtf. These are on by default; --no-backup / --no-snapshot only when you are certain.
Titles are not unique. The reference project has two items titled "Dont Stop To Early." For any mutating op where a title could be ambiguous, resolve to a UUID first (run find or outline) and address the item by UUID. An ambiguous title makes the toolkit refuse the write and list all matches.
Never regenerate a rich document from plain text. Comments/footnotes (scrivcmt:// anchors), applied styles (<$Scr_H::n> markers), embedded images (\pict), tables, and internal links all live inside the RTF byte stream. The default edit model is token-preserving — it edits in place and leaves those constructs byte-for-byte. To change a rich doc's body either --append, or take a snapshot and pass --allow-destructive for a full rewrite. set-text refuses to regenerate a rich doc otherwise.
docs.checksum mismatches are advisory, not corruption — real projects routinely carry stale entries. Never block an edit on a checksum mismatch.
Deletions go to Trash, never hard-delete. The Draft (a.k.a. Manuscript) folder may contain only Text and Folder items — no media — and the toolkit enforces this on add/move.

Use --dry-run to preview any mutating command before committing.

CLI commands this skill uses

Entry point (JSON by default; --format text for humans):

python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py <command> --project "<path.scriv>" [args]

Command	What it does
`outline`	Binder tree — read this first to get UUIDs, parents, and order
`find <query>`	Resolve a title/type to its UUID before a mutating op
`add <parent-id> --type text\|folder [--title ...] [--text ...\|--text-file ...]`	Create a new binder item
`rename <id> <title>`	Rename a document or folder
`move <id> --to <parent-id> [--index N]`	Re-parent and/or reorder (`--index` is the 0-based slot among siblings)
`delete <id>`	Move an item (and its subtree) to Trash
`set-synopsis <id> --text ...\|--text-file ...`	Set the corkboard synopsis
`set-notes <id> --text ...\|--text-file ...`	Set document notes
`set-text <id> (--text ...\|--text-file ...) [--append] [--allow-destructive]`	Edit body; token-preserving; refuses to regenerate a rich doc
`snapshot <id> [--title ...]`	Capture a version of `content.rtf` before a risky change

All mutating commands accept --no-backup, --no-snapshot, and --dry-run.

How to approach a request

Inspect first. Run outline (and find for a named item) to get UUIDs, current parent, and sibling order. Never act on a guessed UUID.
Disambiguate. If a title resolves to more than one item, show the matches and ask, or pick by type — then use the UUID.
Pick the right verb. Add vs. move vs. rename vs. delete vs. edit-text. Keep structural and content edits separate steps so each is independently revertible.
Protect rich content. For an existing body, prefer --append. Only do a destructive rewrite after a snapshot and with --allow-destructive, and tell the user why.
Confirm and verify. Re-run outline (or read) to confirm the new shape. After significant restructuring, suggest scrivener-integrity's verify.

Worked example: move a section, then rename it

Goal: move the scene "The Reveal" so it becomes the second child of the chapter folder "Act Two," then rename it to "The Turn."

SCRIV="/path/My Novel.scriv"

# 1. Find the items and their UUIDs (titles are not unique — confirm one match each).
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py find "The Reveal" --project "$SCRIV" --format text
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py find "Act Two"    --project "$SCRIV" --format text
# → scene  = 8F1C...  (Text)
# → chapter = 2A9D... (Folder)

# 2. Preview the move into slot index 1 (the second position) under Act Two.
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py move 8F1C... --to 2A9D... --index 1 \
  --project "$SCRIV" --dry-run

# 3. Commit the move (auto-backup runs).
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py move 8F1C... --to 2A9D... --index 1 \
  --project "$SCRIV"

# 4. Rename it by UUID.
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py rename 8F1C... "The Turn" --project "$SCRIV"

# 5. Confirm the new structure.
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py outline --project "$SCRIV" --format text

To set a synopsis or notes on the moved scene, follow with set-synopsis 8F1C... --text "..." or set-notes 8F1C... --text "...".

This same move + rename, then assigning a section type and compiling, is a multi-skill flow: scrivener-edit (move + rename) → scrivener-metadata (set section type) → scrivener-compile (compile to Markdown).

Editing text without losing rich data

Append (safe for any doc): set-text <id> --append --text "new paragraph" adds to the end and preserves everything already there.
Replace a plain doc: for a document with no comments/styles/images/tables/links, set-text <id> --text "..." rewrites it cleanly.
Replace a rich doc: set-text refuses unless you --allow-destructive. First snapshot <id> --title "before rewrite", then rewrite. Warn the user that comments, footnotes, styles, embedded images, and internal links anchored in that doc will be lost.
For inserting comments or footnotes rather than overwriting, see scrivener-annotations. For applying named styles, see scrivener-styles.

Toolkit support

✅ Available now: add, rename, move (re-parent + reorder via --to/--index), delete (to Trash), set-synopsis, set-notes, set-text (--append, --allow-destructive; token-preserving with the rich-doc guard), snapshot.

🔜 Planned (v0.1.0 roadmap — not yet in the CLI): split a document at an offset or by separator, merge several documents, promote/demote (shift outline level), duplicate (optionally with subtree), convert folder↔text (lossless), auto-fill titles/synopses, and set-title --from-selection. When asked for one of these, describe the workflow and suggest the closest available command — e.g. for a manual "split," add a new sibling and move text via set-text/--append; for a manual "merge," append each source's text into one doc, then delete the emptied originals. See references/restructuring.md.

Related skills

scrivener-metadata — labels, status, keywords, custom metadata, and section types (assign "Part"/"Chapter"/"Scene" after restructuring).
scrivener-snapshots — take/list/read/diff/restore versions; always snapshot before a destructive rewrite.
scrivener-annotations — add/edit comments and footnotes (linked and inline) instead of overwriting body text.
scrivener-formatting — direct formatting (fonts, color, alignment, lists, tables) on the text you edit here.
scrivener-inspect — outline/read/find to gather UUIDs and current structure before editing.
scrivener-integrity — verify/backup/repair after risky restructuring.

For the move/reorder mechanics, Draft containment rules, the token-preserving edit model, the rich-doc guard, and planned split/merge/promote/demote, see references/restructuring.md.