# Scrivener Stats

> When the user wants word counts, length estimates, or writing-progress metrics for a Scrivener project. Use when the user says "word count", "how long is my manuscript", "reading time", "how many pages", "what words do I overuse", "writing history", or "am I hitting my target". For reading a document's text and outline, see scrivener-inspect. For assembling the Draft into a finished file, see scrivener-compile.

- Skill: `donnfelker/scrivener-stats` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add donnfelker/scrivener-stats`
- Raw SKILL.md: https://api.skillmd.com/api/skills/donnfelker/scrivener-stats/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-stats

---


# Scrivener Stats

You help the writer measure a Scrivener 3 project: total and per-item word/character
counts, reading-time and page estimates, day-by-day writing history, and which words
they overuse. Every command here is **read-only** — none of them mutate the project.

## When to use

- "What's my word count?" / "How long is my manuscript?"
- "How long would this take to read?" / "How many (paperback) pages is this?"
- "What words do I overuse?" / "Show me my most common words."
- "Show my writing history." / "How many words did I write each day?"
- "Am I on track / hitting my target?" (report from history; deadline math is planned)

## Commands

All commands take `--project "<path.scriv>"` and emit JSON by default
(`--format text` for a human-readable view). These are read-only — no backup,
snapshot, or `--dry-run` flags apply.

### `stats [<id>]` — counts and estimates

With no id, reports the whole Draft. Pass a document or folder UUID/title to scope
to that subtree.

```bash
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py stats --project "<path.scriv>"
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py stats <uuid> --project "<path.scriv>"
```

Returns `words`, `characters`, `reading_time_minutes`, `paperback_pages_est`,
`documents_with_text`, and `scope` (draft or item).

### `stats-history` — per-day draft/other words

Reads `Files/writing.history` (Scrivener's own session log) and reports per-day
draft vs. other word counts plus totals.

```bash
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py stats-history --project "<path.scriv>"
```

Each day reports `draft_words` (manuscript), `other_words` (everything else), and
the `session_target`. Totals roll up `draft_words`, `other_words`, and
`days_written`.

> **`writing.history` is read-only.** Scrivener owns this file and rewrites it as
> the writer works. This skill only reads it — never regenerate or edit it. If the
> file is absent (e.g. a brand-new project), the result is simply empty.

### `stats-frequency [--top N]` — word frequency

Lists the most-used words across the Draft (default top 50).

```bash
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py stats-frequency --project "<path.scriv>"
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py stats-frequency --top 25 --project "<path.scriv>"
```

Returns `unique_words` and a `top` list of `[word, count]` pairs. Use this to spot
crutch words, repeated names, or overused adverbs.

## Understanding the estimates

The estimates are deliberately simple, transparent rules of thumb — not Scrivener's
exact figures. Tell the writer how each number is derived so they can judge it:

| Metric | How it's computed |
|---|---|
| `reading_time_minutes` | `words ÷ 250` — about **250 words per minute** silent reading |
| `paperback_pages_est` | `words ÷ 350` — about **350 words per typeset page** |
| `words` / `characters` | counted from each document's `content.rtf` after RTF→text conversion |
| `documents_with_text` | how many items actually contributed body text |

Reading speed and page density vary by reader, trim size, and font, so present these
as ballpark figures. Full detail (which items count, how subtrees roll up,
`writing.history` attributes) lives in `references/metrics.md`.

## Toolkit support

✅ **Available now:**
- `stats [<id>]` — words, characters, reading_time_minutes, paperback_pages_est
- `stats-history` — per-day draft/other word counts (read-only)
- `stats-frequency [--top N]` — word frequency across the Draft

🔜 **Planned (not yet in the CLI):**
- Per-document/folder **targets** and **deadline math** (words remaining, words/day
  to hit a date). For now, read progress from `stats-history` and compute the gap by
  hand against the writer's stated goal.
- **CSV export** of stats and writing-history. For now, hand the JSON output to the
  writer or another tool.

When asked for a planned feature, describe the workflow, say it isn't in the CLI
yet, and offer the closest available command.

## Safety

- These commands are read-only and never modify the project, so they are safe to run
  even while drafting. Still, results are most accurate once **cloud sync
  (Dropbox/iCloud) has finished** — a mid-sync project may have partial content.
- **Binder titles are not unique** — when scoping `stats <id>` by title and the title
  is ambiguous, prefer the item's UUID (get it from `scrivener-inspect`'s `outline`
  or `find`).
- Counts come only from items that have body text; folders and empty documents
  legitimately contribute zero. Absent `content.rtf` is normal, not corruption.

## Related skills

- **scrivener-inspect** — open and explore the project: `outline`, `read`, `find`
  (use it to get the UUID to pass to `stats`).
- **scrivener-compile** — assemble the Draft into Markdown/text; useful once length
  and frequency look right.
- **scrivener-search** — find and (planned) replace specific words flagged by
  `stats-frequency`.