Scrivener Inspect

Scrivener Inspect

You help the writer open and explore a Scrivener 3 (.scriv) project read-only: show the binder outline, read a document's text/synopsis, and find an item by title, UUID, or type. Nothing here mutates the project, so no backup, snapshot, or "close Scrivener first" warning is required — but reads are most reliable when the project isn't mid-cloud-sync.

Use this skill to understand a project before any editing skill acts on it. Compound requests usually start here: inspect → then hand a UUID to a write or export skill.

When to use

• "Show me the outline / list the binder" → outline
• "Read this chapter / what does this scene say / what's the synopsis of X" → read <id>
• "What's in this project / where's the document about Y / find the scene where…" → find <query>

Commands

All three are read-only. Output is JSON by default; add --format text for a human-readable view. Always pass --project pointing at the .scriv package (or its .scrivx).

outline — the binder tree

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

Returns the nested binder: each node has uuid, title (adaptive — see below), type, label, status, include_in_compile, and children. This is the map you read first to get the UUIDs other commands need.

read <id> — one document's content

python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py read <uuid-or-title> --project "<path.scriv>"

Returns uuid, title, type, include_in_compile, label, status, synopsis, has_synopsis_image, the document text (RTF converted to plain text), and a constructs map flagging rich content. Pass a UUID when a title is ambiguous (titles are not unique). Folders and empty documents have no body text, so text and constructs will be null — that is normal, not corruption.

find <query> — locate items

python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py find "<query>" --project "<path.scriv>"

Matches a title substring (case-insensitive), an exact UUID, or an exact Type (e.g. Folder, Text, DraftFolder). Returns uuid, title, and type for every match. Use it to turn a fuzzy "the chapter about the storm" into a concrete UUID, then read it. find is title/UUID/type only — for full-text or field search (text/synopsis/notes), use scrivener-search.

Adaptive titles

A binder item without a <Title> still gets a usable display title. The toolkit derives one in order: the document's synopsis first line → the body text's first line → "Untitled" (each truncated to ~60 chars). So an untitled scene shows up in outline/read/find with a meaningful, derived title rather than a blank. Treat these as display titles, not stable identifiers — address such items by UUID.

What read returns

A single read gives you the whole picture of one item:

• text — the body, RTF→plain text (folders/empty docs return null).
• synopsis + has_synopsis_image — the corkboard card text, or a flag that the synopsis is an image instead.
• label / status / include_in_compile — the item's metadata (label/status are IDs; resolve names via scrivener-metadata's labels/statuses).
• constructs — boolean flags for rich content embedded in the RTF: comments_or_footnotes, style_markers, images, tables, hyperlinks, lists. These tell you before any edit whether a document is "rich." Any true flag means a regenerative rewrite would lose data, so a downstream edit must be token-preserving or explicitly destructive (see scrivener-edit).

Finding the Draft

The Draft (manuscript) is identified by Type DraftFolder, never by title — a user can rename it ("Manuscript", "Novel", etc.). To locate it without guessing the name:

python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py find "DraftFolder" --project "<path.scriv>"

Similarly, research lives under ResearchFolder and deleted items under TrashFolder. Reading the whole manuscript in order means walking the DraftFolder's children from outline.

Reference

• references/reading-items.md — how outline/read/find output is shaped; UUID vs title addressing; reading notes and synopsis; and the meaning of every constructs flag.

Toolkit support

Related skills

• scrivener-extract — convert/export content out (RTF→Markdown/text, bulk export of one item, a subtree, or the whole Draft).
• scrivener-search — full-text and field search (text/synopsis/notes), beyond find's title/UUID/type matching.
• scrivener-stats — word counts, characters, reading-time and page estimates, writing history, and word frequency.
• scrivener-format — the .scriv package format reference (binder schema, data files, the RTF constructs read flags).