# Scrivener Extract > When the user wants to get the raw text out of a Scrivener project — convert a document to Markdown or plain text, export a chapter or the whole draft, or pull synopses and metadata into files. Use when the user says "get the text of this document," "convert this to Markdown," "export this chapter as text," "pull all the synopses," "dump the manuscript to markdown," or "export the outline to OPML/CSV." For an assembled, structured manuscript with proper headings, see scrivener-compile. For reading a single document in place, see scrivener-inspect. For comments and footnotes, see scrivener-annotations. - Skill: `donnfelker/scrivener-extract` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add donnfelker/scrivener-extract` - Raw SKILL.md: https://api.skillmd.com/api/skills/donnfelker/scrivener-extract/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Data & Analytics - Author: donnfelker (https://skillmd.com/u/donnfelker) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/donnfelker/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`**: ```bash # One document, as Markdown (default) python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py extract \ --project "" # One document, as plain text python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py extract \ --to txt --project "" # Every document under the Draft/Manuscript folder python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py extract draft \ --project "" # Every document in the whole binder python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py extract all \ --to md --project "" ``` 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): | Construct | In extracted text? | |---|---| | Body paragraphs, tabs, line/para breaks | ✅ kept | | Visible hyperlink text | ✅ kept (the URL/target is dropped) | | Comments & linked footnotes | ❌ dropped | | Inline annotations & inline footnotes | ❌ dropped | | Scrivener placeholders (`<$...>`, `<$img:...>`) | ❌ stripped | | Embedded images (`\pict`/`pngblip`) | ❌ skipped | | Tables | ⚠️ best-effort; cell text only, no structure | | Applied style markers (`<$Scr_H::n>`) | ❌ stripped (text kept) | 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 | Capability | Status | |---|---| | `extract [--to md\|txt]` | ✅ available now | | `export-files --to rtf\|txt\|md\|html\|fountain --out ` (per-document to disk, mirroring binder folders) | 🔜 planned | | `--include synopsis,notes,comments,footnotes` on extract | 🔜 planned | | Sidecar files (metadata / notes / synopsis next to each export) | 🔜 planned | | `export-outline --to opml` | 🔜 planned | | `export-metadata --to csv` (or `tsv`) | 🔜 planned | | `export-files --to docx\|odt\|pdf` (needs pandoc / `textutil` / LaTeX engine) | 🔜 planned | 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.