# Scrivener Import

> When the user wants to bring external material into an existing Scrivener project. Use when the user says "import this file/manuscript into Scrivener", "bring this markdown in", "split this long doc into chapters on import", "import research", or "merge another Scrivener project". For adding or splitting items already in the project, see scrivener-edit. For scaffolding a brand-new project, see scrivener-create-project. For matching imported text to the project's look, see scrivener-format.

- Skill: `donnfelker/scrivener-import` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add donnfelker/scrivener-import`
- Raw SKILL.md: https://api.skillmd.com/api/skills/donnfelker/scrivener-import/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: donnfelker (https://skillmd.com/u/donnfelker)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/donnfelker/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.

```bash
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:

```bash
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):

```bash
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:

```bash
# 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:

```bash
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.