Scrivener Extract

Scrivener Extract

You help the writer get content out of a .scriv project as plain text or Markdown — a single document, a subtree, the Draft, or the whole binder. Extraction is read-only: it never modifies the project.

Pick the right tool for the job:

• Raw text of specific items (one doc, the Draft, everything) → extract.
• An assembled manuscript with titles turned into headings, in binder order, honoring Include-in-Compile → use scrivener-compile instead. That is the source of structured Markdown; extract gives you the per-document text.

When to use this skill

• "Get the text of the prologue."
• "Convert chapter 3 to Markdown."
• "Export this chapter as a plain .txt file."
• "Dump the whole manuscript to Markdown."
• "Pull all the synopses into one file." (planned — see Toolkit support)
• "Export the outline to OPML." / "Export metadata to CSV." (planned)

Extracting text (available now)

extract converts a document's content.rtf to Markdown (--to md, default) or plain text (--to txt). The target is a UUID, a title, draft, or all:

# One document, as Markdown (default)
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py extract <uuid> \
  --project "<path.scriv>"

# One document, as plain text
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py extract <uuid> \
  --to txt --project "<path.scriv>"

# Every document under the Draft/Manuscript folder
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py extract draft \
  --project "<path.scriv>"

# Every document in the whole binder
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py extract all \
  --to md --project "<path.scriv>"

Output is JSON by default — an array of {uuid, title, content}, one entry per document that has body text. Add --format text for a human-readable dump. Items with no content.rtf (folders, empty documents, Image items) are skipped; this is normal, not an error.

Titles are not unique. When the user names a document, run find (see scrivener-inspect) first and extract by UUID if more than one item matches.

RTF → Markdown is best-effort

The --to md conversion in v0.1.0 is deliberately simple: it produces clean paragraphs separated by blank lines. It does not recover headings, bold, italic, or list markup from the raw RTF. If the user wants a properly structured Markdown document — titles as #/## headings by binder depth — that comes from scrivener-compile, which builds headings from the binder + section types, not from inline RTF formatting.

Tell the user plainly: use extract to get the words; use compile to get the structure.

What plain extraction drops

Extraction reads only the visible body text. The following do not appear in extracted output (their anchors live inside the RTF byte stream and are intentionally skipped):

If the user needs comments or footnotes, route to scrivener-annotations (planned) or read them via read in scrivener-inspect, which reports the constructs present in a document. See references/conversion-notes.md for the full behavior of the converter and its limits.

Safety

Extraction is read-only — no backup or snapshot is taken because nothing is written. Even so, remind the writer to close the project in Scrivener and let cloud sync (Dropbox/iCloud) finish before pointing the toolkit at a live project, so you read a consistent on-disk state. docs.checksum mismatches are advisory and never block a read.

Toolkit support

When asked for a planned capability, say it isn't in the CLI yet and offer the closest available path:

• "Pull all synopses" → no --include yet; read each item's synopsis via read (scrivener-inspect), or extract body text with extract all.
• "Export each doc to its own file" → extract all returns every document's text as JSON; write the files yourself from that output until export-files ships.
• "Export the outline to OPML / metadata to CSV" → use outline (scrivener- inspect) for the tree and assemble the OPML/CSV from its JSON for now.

See references/conversion-notes.md for the converter internals and the planned export-files / OPML / CSV shapes.

Related skills

• scrivener-compile — assembled, structured output (titles → headings, binder order, Include-in-Compile); the place to get a real manuscript file.
• scrivener-inspect — outline, read (text + synopsis + notes + constructs), find; use it to resolve ambiguous titles to UUIDs.
• scrivener-annotations — comments & footnotes, which plain extraction drops.
• scrivener-format — the .scriv package and RTF reference these notes cite.