Scrivener Import

Scrivener Import

You help the writer bring outside material into an existing .scriv project — a drafted chapter, a folder of research, a long Markdown file that should become one document per chapter, or another Scrivener project to merge in. Importing is additive: it creates new binder items; it never overwrites existing ones.

This skill describes the planned import family and the available-today stopgap using scrivener-edit's add. Be honest with the writer about which path runs now.

When to use this skill

• "Import chapter-3.md into the Drafts folder."
• "Bring this Markdown manuscript in and split it into chapters."
• "Import my interview notes and PDFs as research."
• "Merge my old Notes.scriv into this project."

Safety first (restate briefly to the writer)

• 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 first; content edits auto-snapshot.
• Import is additive — new items only. It does not touch existing documents, so the rich-doc / --allow-destructive concern does not apply to fresh imports.
• Titles are not unique; pass the UUID of the parent (and verify the parent's Type) when a title is ambiguous. Use outline/find to get the UUID.
• The Draft/Manuscript folder accepts only text and folders, not media. Import PDFs/images/audio/video into a Research folder instead.

Choosing where things land (do this first)

Resolve the destination parent before importing.

python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py outline --project "<path.scriv>" --format text
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py find "Research" --project "<path.scriv>"

Planned import commands (🔜 — describe the workflow, then offer the stopgap)

None of these are in the CLI yet. Explain what each will do and route the writer to the available path below.

• import <parent-id> <file>... — bring external files in. Stdlib-native (runs with the pre-installed Python, no extra engine): txt, md, rtf, html, opml, and PDF / images / audio / video copied in as research/media items (pass-through, no conversion). Engine-gated: converting docx/odt, or extracting text from a PDF or fdx, needs pandoc/textutil and degrades gracefully when absent.
• import-split <parent-id> <file> --by headings|md-atx|separator [--sep "#"] — import one long file and split it into multiple binder items in one pass (e.g. one document per chapter).
• import-project <other.scriv> [--into <parent-id>] [--merge] — import or merge another Scrivener project's binder subtree into this one.

See references/import-formats.md for the full pass-through-vs-engine table and the split modes.

Available today: the add stopgap (✅)

For local text or Markdown, you can create the document now with scrivener-edit's add, which accepts inline text or a file. This is the supported stopgap until import ships. It is not a converter — it takes plain text / Markdown only.

Single file → one new document under a parent:

python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py add <parent-id> \
  --type text --title "Chapter 3" \
  --text-file ./chapter-3.md \
  --project "<path.scriv>"

Inline text (short snippets):

python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py add <parent-id> \
  --type text --title "Epigraph" --text "It was a bright cold day..." \
  --project "<path.scriv>"

Stopgap for import-split (one long Markdown file → one doc per chapter): split the file outside Scrivener first (e.g. on top-level # ATX headings), make a parent folder, then add each piece. Walk the writer through it:

# 1. create the container
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py add <draft-id> \
  --type folder --title "Part One" --project "<path.scriv>"
# 2. add each pre-split chapter file under the new folder's UUID
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py add <folder-uuid> \
  --type text --title "Chapter 1" --text-file ./ch01.md --project "<path.scriv>"
# ...repeat per chapter

Stopgap limits — say so plainly:

• Only txt/md content. rtf/html/opml parsing, docx/odt/pdf conversion, and media pass-through are not available via add — those wait for import.
• No automatic splitting; you split the file first, then add each part.
• No project-merge stopgap; import-project has no equivalent today.

Media and PDFs (pass-through, not extraction)

Bringing a PDF or image in as a research/media item is a pass-through copy — no engine needed; that is what planned import will do. Only extracting the text out of a PDF/fdx/docx needs an engine. There is no stopgap for media import today (add writes text documents only); tell the writer to add the file in the Scrivener UI for now, or wait for import.

After importing

Confirm the new items landed and check counts:

python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py outline --project "<path.scriv>" --format text
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py stats <new-id> --project "<path.scriv>"

If you want the imported text to match the project's editing defaults or headings, hand off to scrivener-format / scrivener-edit.

Toolkit support

Related skills

• scrivener-edit — the add (stopgap create) and future split of items already in the binder; move/rename/delete the imported items.
• scrivener-create-project — scaffold or fork a brand-new project; new-project can seed from a directory at creation time.
• scrivener-format — the .scriv package reference and matching imported text to the project's editing defaults and heading conventions.