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.yamlcites 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-scopeconvention 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. Seeauthor-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-simulationanddesk-rejection-riskare 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
.docxround-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.synonymsis 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_claimsare 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
Claude Code (recommended)
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-auditwhen 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 theknowledge/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:
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.