# Scrivener Format > When the user wants to understand how a Scrivener 3 project is stored on disk — the .scriv package, the .scrivx binder, where text/synopses/notes/snapshots/comments live, or how section types, labels, and metadata serialize. Use when the user says "how does Scrivener store…", ".scrivx format", "what's in a .scriv", "scrivener file format", "where are synopses stored", or "what files make up a Scrivener project". This is the foundational reference hub the other scrivener skills cite. For reading/exploring an actual project, see scrivener-inspect. For validating or repairing a package, see scrivener-integrity. - Skill: `donnfelker/scrivener-format` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add donnfelker/scrivener-format` - Raw SKILL.md: https://api.skillmd.com/api/skills/donnfelker/scrivener-format/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: donnfelker (https://skillmd.com/u/donnfelker) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/donnfelker/scrivener-format --- # Scrivener 3 package format You help the writer understand how a Scrivener 3 project is laid out on disk so the right tool and the right skill can be chosen. This is a **knowledge / reference** skill: it explains the package anatomy at a high level and points to deep references. It has **no mutating commands** — for actual reads use `scrivener-inspect`, for writes use the editing skills, and for validation use `scrivener-integrity`. Use this skill to answer "what is this file?", "where does X live?", and "is this normal or corruption?" questions, and as the shared vocabulary the other 16 skills cite. ## What a `.scriv` is A Scrivener 3 project is **not a single file** — it is a **package** (a directory that macOS shows as one bundle; Windows and the synced cloud copy show it as a plain folder). The toolkit always operates on the **folder** regardless of platform. The format target is **Scrivener 3 only** (cross-platform: Mac / Windows / iOS, Mac as reference). Scrivener 1/2 projects use a different internal layout and are detected and reported, not edited — see `scrivener-integrity`. Two facts identify a v3 project: - `Files/version.txt` holds the format version (e.g. `23` in the reference project). - the `.scrivx` root carries `Version="2.0"`. ## High-level anatomy ``` Project.scriv/ ├── .scrivx # binder XML tree + project-wide settings (the spine) ├── Files/ │ ├── version.txt # format version │ ├── styles.xml # named stylesheet (project styles) │ ├── search.indexes # regenerable plaintext index (Title/Text/Synopsis/Notes/Comments) │ ├── writing.history # per-day word-count history — Scrivener owns it, read-only │ ├── binder.autosave / binder.backup # zipped copies of .scrivx (Scrivener regenerates) │ └── Data/ │ ├── docs.checksum # SHA-1 of content.rtf / notes.rtf / synopsis.txt ONLY │ └── / # per-document payload (not every item has one) │ ├── content.rtf # body text (cocoa RTF); embeds notes/styles/links/images │ ├── synopsis.txt # plain-text synopsis (or a synopsis image) │ ├── notes.rtf # document notes │ ├── content.styles # named styles applied in this doc │ ├── content.comments # linked comments + linked footnotes │ ├── snapshots/ # captured versions of this doc │ └── content. # media payload for an Image/media item (e.g. content.jpeg) ├── Settings/ # compile.xml, projectpreferences.xml, ui state, sync markers └── QuickLook/ # Preview.html, Thumbnail.jpg (macOS preview only) ``` Full directory tree, every file's purpose, and the regenerable-vs-authoritative split: **[references/package-layout.md](references/package-layout.md)**. ## The two big pieces **The `.scrivx` is the spine.** It is the binder XML tree plus project-wide settings. Every binder entry is a `` (UUID, Type, Title, MetaData, Children). Project siblings of `` carry Collections, SectionTypes, Label/Status settings, and ProjectTargets. The full schema — BinderItem fields, the Type enum, section types and their three assignment states, collections, label/status settings — is in **[references/binder-and-metadata.md](references/binder-and-metadata.md)**. **`Data//` is the content.** Each document's text, synopsis, notes, applied styles, linked comments, and snapshots live under a UUID-named directory. The binder points to these by UUID, not by title. ## Absent data is normal, not corruption This is the single most important thing to know when judging a project: - **Not every binder item has a `Data/` directory.** In the reference project the three special root folders (Draft, Research, Trash) have no `Data` dir at all. - **Not every `Data/` directory has a `content.rtf`.** Folders, empty/never-written documents, and Image items have a directory with no body file (an Image item stores `content.` instead). - A "file group" is a `Text` item that has children — container-vs-document is decided by children, not by `Type` alone. So a missing `content.rtf` or a missing `Data` directory is **never** corruption. Only an *explicitly referenced* payload that is gone counts (e.g. a `docs.checksum` entry, an Image item's declared `content.`, or a referenced snapshot/comments file). ## Titles are not unique Binder titles repeat (the reference project has two items both titled "Dont Stop To Early" — a Text and an Image). Always address a document by **UUID** when a title is ambiguous. Every mutating skill restates this. ## `docs.checksum` is advisory `docs.checksum` holds SHA-1 hashes of **only** `content.rtf`, `notes.rtf`, and `synopsis.txt` (never `content.styles`, `content.comments`, or media). Scrivener uses it to *detect external/sync edits*, not to assert integrity — real, valid projects routinely carry stale entries (≈32% mismatch in the reference project). Treat mismatches and absent entries as **informational**, never as corruption. `scrivener-integrity` can recompute them with `repair --checksums`. ## What lives *inside* `content.rtf` Several things are encoded in the RTF byte stream, not in side files — which is why edits must be token-preserving (see `scrivener-edit` / the RTF strategy in the spec): - **Linked comments/footnotes** are anchored in the RTF as `HYPERLINK` fields targeting `scrivcmt://`; their bodies live in `content.comments`. - **Applied named styles** are marked with `<$Scr_H::n>…` markers. - **Embedded images** appear as `\pict` / `pngblip` data. - **Inline annotations/footnotes** and **internal Scrivener Links** (HYPERLINK to a binder UUID) live inline too. Naïvely regenerating "minimal RTF from text" would silently orphan comments, drop style ranges, break links, and delete images. That is why writes default to token-preserving edits. ## How this hub is cited Other skills point here for format facts so they can stay lean: | You're asking about… | Read this reference | |---|---| | Which files exist and what each is for | [references/package-layout.md](references/package-layout.md) | | BinderItem schema, Type enum, MetaData | [references/binder-and-metadata.md](references/binder-and-metadata.md) | | Section types (3 states), collections, labels/statuses | [references/binder-and-metadata.md](references/binder-and-metadata.md) | | What's embedded in content.rtf | this page + binder-and-metadata.md | ## Toolkit support This skill is **knowledge only** — it teaches the format and has no commands of its own. The closest *read* commands (in other skills) are: - ✅ `outline` — see the binder tree (scrivener-inspect) - ✅ `read ` — see one document's text/synopsis/notes + construct flags (scrivener-inspect) - ✅ `verify` — validate the package; checksum mismatches are advisory (scrivener-integrity) There are no 🔜 planned commands here — format facts live in the references. ## Related skills - **scrivener-inspect** — open and explore a real project: `outline`, `read`, `find`. - **scrivener-integrity** — `verify`, `repair`, `backup`/`restore`; confirms a package is valid. - **scrivener-metadata** — set labels, status, section types, custom metadata defined here. - **scrivener-snapshots** — work with the `snapshots/` versions described here. - **scrivener-annotations** — the linked/inline comments & footnotes embedded in `content.rtf`.