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

Command	Status
`add --text/--text-file` (text/md stopgap)	✅ available now (via scrivener-edit)
`outline`, `find`, `stats` (place/verify)	✅ available now
`import` (txt/md/rtf/html/opml + media pass-through)	🔜 planned
`import-split` (headings / md-atx / separator)	🔜 planned
`import-project` (merge another `.scriv`)	🔜 planned
`docx`/`odt`/`pdf`/`fdx` text extraction	🔜 planned, engine-gated (pandoc/textutil)

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.