Skip to main content

scriptorium

Single-responsibility AI skills that work on prose the author has written. Each skill reads a shared editorial state file and is grounded in a curated, peer-reviewed evidence base.

Scriptorium is a collection of focused AI skills — citation audit, reviewer simulation, argumentative-flow analysis, terminology normalization, page-limit compression, and ten more — that coordinate around a single editorial-state file (MANUSCRIPT_STATE.yaml). It is built for authors revising their own manuscripts and grants who want structured, anchored critique on prose they have already written.

Documentation site: https://seandavi.github.io/scriptorium/ (includes a worked case study showing real reviewer-simulation output and a before/after argumentative-flow run).

What scriptorium does

  • Reads prose the author has already declared and emits structured, anchored findings — one finding per claim, one per section, one per figure-text mismatch. No overall quality score. No letter grade.
  • Grounds every design decision in a curated knowledge layer (fifty-plus notes on citation accuracy, hallucination evidence, reviewer-archetype research, reporting guidelines, the AI-writing failure-mode literature). Each skill's manifest.yaml cites the knowledge notes its design comes from.
  • Preserves what the author owns. Critique skills modify nothing. Transformation skills operate under an explicit preservation contract (citations, statistics, declared terminology, declared core claims, hedging style — see voice preservation).
  • Doesn't invent. No skill names a citation from model memory. By default no skill drafts a section from a blank page; the declared-work-scope convention applies across every conversation-bearing skill.
  • Leaves the call to the author. By default, skills decline blank-slate generation and uses that funder or publisher AI policies restrict. Each such refusal is a declared policy or scope guard, and the author can override it for one run or in MANUSCRIPT_STATE.yaml; the skill's output then lists it under "Overrides applied". Accuracy guards, such as no citations from model memory, can't be overridden. See author-authority.

What scriptorium will not do

These are explicit non-goals, grounded in the roadmap and the knowledge layer. Naming them up front is the point — a pre-submission tool earns trust by being concrete about its limits.

  • No blank-slate prose generation by default. Scriptorium does not draft sections from nothing. The proposer role (Hayes 2012) is the author's; scriptorium occupies the translator and evaluator roles. See declared-work-scope. This is a scope guard, so an author can override it for a skill that declares it.
  • No autonomous reviewing. reviewer-simulation and desk-rejection-risk are built for authors. Editorial-side use would mean uploading a confidential manuscript and delegating the critique to AI, which current NIH and publisher reviewer policies restrict (peer-review-platforms). Run by a reviewer or editor on a submitted manuscript, the skills state that concern and ask before proceeding.
  • No overall writing-quality score. No letter grade, no Flesch-Kincaid, no aggregate number. Those systematically misrate scientific prose and would be theater rather than information.
  • No image-forensics or sleuth replacement. Bik-style figure integrity review, tortured-phrase detection, and statistical forensics (Carlisle, Statcheck, GRIM, SPRITE) require domain experts. Scriptorium is a pre-submission first pass.
  • No reference-manager replacement. Citation audit works with the bibliography Zotero, Mendeley, Paperpile, or BibTeX already produced; scriptorium does not manage references itself.
  • No discipline-specific defaults outside biomedical / clinical at v0.1–v0.3. The evidence base is biomedical-coded. Physics, CS/ML, mathematics, qualitative social science, and humanities defaults need per-discipline knowledge layers that don't exist yet — PRs welcome.
  • No native .docx round-trip. Scriptorium operates on markdown-converted prose; tracked changes and Word field codes are not preserved through the conversion.
  • No skill-degradation defence. Whether extended AI use atrophies the author's underlying skill is plausible but under-evidenced. The author retains responsibility for their writing.

Where scriptorium fits in the writing workflow

The seven lifecycle stages in MANUSCRIPT_STATE.yaml (outline → draft → review → revision → submission → post-submission → accepted) map onto four roles in Hayes' 2012 cognitive-process model: proposer, translator, evaluator, transcriber. Scriptorium occupies the translator and evaluator roles when the author has already proposed. It does not propose for the author.

Lifecycle stage Typical scriptorium skills
outline (proposer phase — author-owned) init, tour, explain, venue-fit. No critique skills — outline-phase prose isn't yet declared.
draft citation-audit, gap-finder, figure-text-alignment, reporting-guideline-fit, terminology-normalization, argumentative-flow (per section).
review · revision All of the above plus reviewer-simulation, author-contribution-audit, reporting-guideline-compliance.
submission All of the above plus desk-rejection-risk, compression.

The skill reference lists every shipped skill by category and lifecycle stage.

Voice preservation, the honest version

A common (correct) fear about AI editing tools is that they will flatten the author's voice. Scriptorium's posture on this is split into two claims — one that is enforced, one that is not.

Enforced (the preservation contract). Transformation skills (argumentative-flow, compression) operate under an explicit preservation contract:

  • Every citation key in the source is preserved; none are added.
  • Every numerical value, p-value, confidence interval, and unit is preserved verbatim.
  • Whatever the author declares in terminology.preferred / terminology.forbidden / terminology.synonyms is respected.
  • The author's hedging strength (over-cautious vs assertive) is honoured — any shift is reported as a per-edit note rather than absorbed silently.
  • Declared core_claims are preserved; no claim is added, no declared claim is dropped.

Critique skills (citation-audit, reviewer-simulation, gap-finder, desk-rejection-risk, figure-text-alignment, reporting-guideline-compliance, author-contribution-audit, venue-fit, reporting-guideline-fit) rewrite nothing at all.

Not promised (sentence-level voice preservation). Scriptorium does not claim that running a transformation skill leaves your prose "sounding like you" at the sentence level. The evidence is the Kobak et al. 2025 lexical-fingerprint work: LLM-edited prose is detectable at corpus scale, and correcting it at sentence scale is not reliable. The conservative-edit posture above minimizes the surface area of changes; it does not promise that nothing about the author's distinctive voice shifts. See ai-writing-failure-modes for the evidence we're calibrating against.

The defence is structural: the author reviews each per-edit diff and chooses what to accept.

Light, standard, full — author chooses

Critique can be paralyzing if it arrives all at once and presents as authoritative. meta.guidance_level in MANUSCRIPT_STATE.yaml lets the author dial in how much framing scriptorium adds around its work:

  • terse — questions and confirmations only. No prose between turns. For authors on their second-or-later project.
  • standard (default) — one-line "why" before non-obvious questions. For returning users who appreciate anchoring without a lecture.
  • full — upfront orientation, 2–3 sentence rationale before each elicited field, end-of-phase recap. For first-time users who want to learn the workflow as they go.

The structured output of each skill — the citation-audit table, the four reviewer-lens sections, the argumentative-flow diff — does not change with guidance level. What changes is the framing around the structured work. See guidance-level.

Install

Scriptorium hosts its own plugin marketplace at seandavi/scriptorium. Easiest install — no Python toolchain needed:

/plugin marketplace add seandavi/scriptorium
/plugin install scriptorium@scriptorium

(seandavi/scriptorium is the GitHub owner/repo shorthand for https://github.com/seandavi/scriptorium. Append @v0.3.0 or any ref to pin.)

Once installed, run:

/scriptorium:tour

A short conversational walk-through — three or four turns — that orients you to scriptorium and ends with one concrete next command. It writes nothing and invokes no other skill; it's the single entry point we recommend pointing new users at instead of linking them to documentation.

Updates: /plugin marketplace update then /plugin update scriptorium@scriptorium.

If you also want the Python CLI (scriptorium init, scriptorium validate, scriptorium trace), or you want a live-linked dev install, see INSTALL.md.

Other agents (Codex, Gemini, Hermes, ChatGPT, …)

For agents that load skills from a directory (Codex, Cursor, Gemini CLI, Claude Code, and others), install with the skills CLI:

npx skills add seandavi/scriptorium                      # all skills
npx skills add seandavi/scriptorium --skill citation-audit

See INSTALL.md for agent selection, global installs, updates, and what the plugin adds on top.

For agents without skill directories, each skill ships with a platform-neutral prompt.md you can paste into any LLM directly. To get all skills concatenated into a single prompt-pack file:

scriptorium prompt-pack -o scriptorium-prompts.md

See INSTALL.md for per-platform recipes.

Quick start

# 1. Scaffold editorial state for your manuscript
scriptorium init /path/to/your/manuscript

# 2. Populate it. Two ways:
#    a) Edit /path/to/your/manuscript/MANUSCRIPT_STATE.yaml directly.
#    b) In Claude Code inside the manuscript repo, run the conversational
#       bootstrap that walks you through core_claims, known_weaknesses,
#       terminology, audience, and tone:
#       /scriptorium:init

# 3. Validate the result
scriptorium validate /path/to/your/manuscript/MANUSCRIPT_STATE.yaml

# 4. Run the leaf skills in Claude Code, inside the manuscript repo:
/scriptorium:citation-audit
/scriptorium:reviewer-simulation
/scriptorium:argumentative-flow

MANUSCRIPT_STATE.yaml is a local file in your repository. It is not uploaded to scriptorium and is not shared unless you commit it to a shared branch. Whether to commit it is your call.

A fully-populated reference manuscript lives at templates/MANUSCRIPT_STATE.example.yaml (an imaginary biomedical paper that exercises every field in the schema). Use scriptorium init --example /tmp/example to drop a copy anywhere as a learning aid.

A worked case study showing the full citation-audit / reviewer-simulation / argumentative-flow run on a realistic discussion paragraph (constructed for the walk-through, not real) lives at docs/src/content/docs/concepts/case-study.md.

What ships today

Sixteen skills across critique, validation, normalization, transformation, meta, and utility categories. The full list, organised by category and lifecycle stage, is the skills reference page. A short summary:

  • Critique — citation-audit, reviewer-simulation, gap-finder, figure-text-alignment, desk-rejection-risk, venue-fit, author-contribution-audit, reporting-guideline-fit, outlier-sentence-detector.
  • Validation — reporting-guideline-compliance.
  • Normalization — terminology-normalization.
  • Transformation — argumentative-flow, compression.
  • Meta / utility — tour, explain, init.

The scriptorium CLI exposes six subcommands: install, init, validate, prompt-pack, list, and trace. See scriptorium --help.

Deliberately not shipped (see DESIGN.md and the roadmap for build order): the manuscript-pipeline orchestrator (held until the leaves have been exercised on more real manuscripts); blank-slate drafting skills (out of scope by design); Codex/Gemini installer scripts.

Companion tools

Scriptorium is the editorial layer; these tools are useful neighbors for the rest of the scholarly-writing workflow:

  • Semantic Scholar MCP and PubMed MCP — bibliographic lookup and full-text retrieval as MCP servers, consumable by Claude Code (and any MCP-aware agent). Pair well with scriptorium:citation-audit when claims need to be checked against primary literature.
  • quartobot — resolves persistent-identifier cite keys (@pmid:, @doi:) in Quarto documents before citeproc renders them. Used inside the scriptorium docs build for the knowledge/ evidence base; useful standalone for any Quarto-based scholarly writing.

These are external projects, not bundled with scriptorium. Install them separately following each project's own instructions.

Design principles

The system separates:

  • generation (write new prose — out of scope at v0.1–v0.3)
  • critique (assess existing prose; emit structured findings)
  • validation (check against an external standard)
  • normalization (enforce declared style and terminology)
  • transformation (modify prose under a preservation contract)

And prefers:

  • inspectable transformations over opaque rewrites
  • structured outputs over freeform rambles
  • semantic diffs over surface rewrites
  • explicit checkpointing over hidden state

See DESIGN.md for the full design philosophy and the roadmap for what ships when.

Status

v0.3 shipped (CHANGELOG: [0.3.0]), adding compression, figure-text-alignment, reporting-guideline-compliance and outlier-sentence-detector. Sixteen skills total, fifty-plus knowledge notes, the consolidated scriptorium CLI (six subcommands), the shared-state schema, the trace schema, the Venice example. Pre-1.0 shape: the skill catalog is growing; CLI surface and schema may still adjust.

License

Dual-licensed by category:

  • Code — source under src/, tests, schemas, scripts, and configuration files — is MIT.
  • Documentation and knowledge layer — the docs/ site, the knowledge/ evidence base, top-level prose files (README.md, DESIGN.md, INSTALL.md, CONTRIBUTING.md), and per-skill README.md files — is CC BY 4.0.

Metadata

Release files for agentic-scriptorium 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agentic-scriptorium 0.3.0
File Size Uploaded Provenance Actions
agentic_scriptorium-0.3.0.tar.gz 674.9 kB With provenance Details for agentic_scriptorium-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agentic-scriptorium 0.3.0
File Interpreter ABI Platform Actions
agentic_scriptorium-0.3.0-py3-none-any.whl Python 3 none any Details for agentic_scriptorium-0.3.0-py3-none-any.whl

Total release size: 1.5 MB

Release files / agentic_scriptorium-0.3.0.tar.gz

Download URL agentic_scriptorium-0.3.0.tar.gz
Size 674.9 kB
Tags Source
SHA-256 checksum
How to use checksums
dd76fcb73e1c4a46382a6d4c4f995e8e538c55ed33587fc0cbb0c6b670a8222a
BLAKE2b-256 checksum
How to use checksums
24e542d6aacb9e31f25343cedcd7a037b7e4dbcd0b5ec27360fdd17261fada6f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

Release files / agentic_scriptorium-0.3.0-py3-none-any.whl

Download URL agentic_scriptorium-0.3.0-py3-none-any.whl
Size 825.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b89a6e7ed3dbb8749e2944b43cb3e5a3930f40c5502a9ed9ae1c4863bd44ab78
BLAKE2b-256 checksum
How to use checksums
939d792166b534f62b99a7cfbf00799464d2ae00340f4a61978e9f2404c0e8dd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

Security for agentic-scriptorium 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for agentic_scriptorium-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page