# manuscript-peer-review

An Agent Skill for reviewing a scholarly manuscript (LaTeX or Markdown) with a fixed protocol: a deterministic audit first, then five independent role reviews, adversarial verification of every finding, an anchored scoring rubric and an author-facing report.

The protocol exists to prevent the usual failures of machine-assisted review: findings that quote text which is not in the manuscript, references described without being opened, "wrong" where "not shown" was meant, and a long undifferentiated list in place of the two or three comments a decision turns on.

# Contents

Path	Purpose
`SKILL.md`	The rules, the eight stages, the finding format, the limits
`references/roles.md`	What each of the five roles reads for, and how to delegate them
`references/procedure.md`	Each stage in detail, including verification and revision checks
`references/rubric.md`	Seven dimensions, anchored levels, weights, caps, how to report scores
`references/templates.md`	Intake note, referee report, decision letter, replication checklist, ledger, response table
`references/finding-codes.md`	The 67 codes of the audit script and what to check before reporting each
`scripts/manuscript.mjs`	Command-line audit tool, JSON or text output
`scripts/lib/`	The audit engine (shared with the `manuscript-audit-mcp` server)

No dependencies beyond Node.js 20+. No network access, no API key, no LaTeX installation.

# Install

bash

skills install @spboucher/manuscript-peer-review --client claude-code   # or codex, cursor, generic-agent-skills

# The script

bash

node scripts/manuscript.mjs audit paper.tex --text                 # every check
node scripts/manuscript.mjs audit paper.tex --root .. --min-severity warning
node scripts/manuscript.mjs citations paper.md --bib refs.bib
node scripts/manuscript.mjs scaffold paper.tex > report.md         # report skeleton
node scripts/manuscript.mjs compare v1/paper.tex v2/paper.tex      # revision check
node scripts/manuscript.mjs codes                                  # all finding codes

Exit code 0 when no finding reaches the --fail-on level (default error), 2 when one does, 1 on a usage or read error. Files are read only from --root (default: the directory of the manuscript), symbolic links included.

# Tested

node --test skill-tests/ in the source repository: the skill follows the Agent Skills specification, every referenced file exists, the engine is byte-identical to the MCP package (whose own suite checks each audit against manuscripts with planted defects), the engine imports nothing outside Node.js, and the command-line tool is exercised on the same fixtures (output, exit codes, root confinement).

The protocol itself (roles, rubric, templates) is a method, not a measured instrument: no claim is made that its scores are calibrated against editorial outcomes.

# Limits

The script reads LaTeX and Markdown source only: no PDF, no Word files, no images, no data.
It compiles nothing and looks nothing up. A complete, well-formed reference can still be wrong or non-existent; opening the source is the reviewer's job.
About half of its checks are heuristics on English wording and are labelled as such.
An empty audit never means a manuscript is correct.

# Licence

MIT.

spb llm-api-toolkits