From Paper Agent
Drafts, reviews, revises, proofreads, and audits academic manuscripts for quantitative-science journals (hydrology focus, extensible via journal style file). Reads .docx and data files, resolves citations via Semantic Scholar.
How this skill is triggered — by the user, by Claude, or both
Slash command
/paper-agent:paper-agentThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Generate, review, revise, or proofread hydrology and water-resources manuscripts at journal-submission quality. Read project data or existing .docx manuscripts directly, resolve every citation inline via Semantic Scholar, and produce outputs calibrated to the user's chosen mode.
Generate, review, revise, or proofread hydrology and water-resources manuscripts at journal-submission quality. Read project data or existing .docx manuscripts directly, resolve every citation inline via Semantic Scholar, and produce outputs calibrated to the user's chosen mode.
Never produce outlines, summaries, or bullet-point drafts in Draft mode. Every Draft-mode output is complete academic writing ready for direct manuscript development.
This skill supports five distinct modes. The user selects one at startup (Block 0 of the interview). Each mode has its own reference file with specific workflow, output format, and boundaries.
| Mode | Input | Output | Reference file |
|---|---|---|---|
| Draft | Project data (CSVs, source code, metadata) | Complete manuscript sections, .docx export | Body of this SKILL.md |
| Review | Existing .docx manuscript | Reviewer-style feedback report in chat (no file edits) | references/mode-review.md |
| Revise | Existing .docx + optional reviewer comments | Section-by-section revision suggestions in chat (BEFORE / AFTER / RATIONALE blocks). Never edits the .docx file directly — user applies changes themselves. | references/mode-revise.md |
| Proofread | Existing .docx manuscript | Revised .docx with language-level fixes only. No scientific changes, no restructuring, no new citations. | references/mode-proofread.md |
| Audit | Existing .docx manuscript | Consistency and coherence report in chat with severity-tagged findings (Critical / Major / Minor). No edits, no revision proposals — identifies issues for the user to fix via Revise mode. | references/mode-audit.md |
Mode determines what is allowed. Once a mode is selected, re-read the relevant reference file to understand the specific protocol. Do not mix mode behaviours — e.g. Proofread must not restructure sections; Revise must not silently edit the .docx file; Review must not rewrite paragraphs.
references/anti-fabrication.md before any work.This is the most important rule in the skill. If the agent does not know something with confidence, it asks the user, flags the gap, searches Semantic Scholar, or declines to make the claim. It never fills in a plausible-sounding answer. Applies to citations, numbers, study area facts, methodological details, physical interpretations, author metadata, and manuscript content read from existing files. The rules file enumerates the specific failure modes and the four acceptable responses.
references/anti-summary-rules.md before writing any section.This is one of the two most common failure modes. The rules file is short and mandatory.
references/anti-ai-style.md before writing any prose.Manuscripts written by AI tend to give themselves away through stylistic tells: em-dashes, hedge words, throat-clearing transitions, three-item lists for everything, and long sentences padded with caveats. Reviewers notice. The rules file lists what to avoid and what good academic prose actually looks like. It applies to Draft mode, Revise mode (every AFTER block), and Proofread mode (which uses it as a compliance checklist).
Run once per session, before any writing or review. Follow references/startup-interview.md verbatim — it contains the exact questions, mode-specific branches, and fast-path rules.
Block 0 — Mode selection (always first). Ask which mode the user wants: Draft, Review, Revise, Proofread, or Audit. Load the corresponding reference file immediately.
Block 1 — Journal target (all modes). Load the journal profile matching the answer — references/journal-hydrogeology.md (hj), references/journal-jhrs.md (jhrs), references/journal-tim.md (tim), or references/journal-generic.md (generic, for any other quantitative-science journal). For generic, also read any author guidelines the user pastes; they override the generic baseline. The journal style matters for Review (is the manuscript compliant?), Revise (do the edits match journal style?), and Proofread (what terminology rules to enforce?), not just Draft.
Remaining blocks branch by mode. Read references/startup-interview.md for the full protocol.
Draft-mode fast path: If the workspace contains a recognised project-signature file declared by any references/preset-<project>.md (see references/preset-example.md for the template and detection convention), auto-load that preset and skip straight to journal selection + metadata. Still confirm with the user before writing.
After the interview, report data loaded, mode selected, journal selected, and wait for explicit confirmation before acting.
When the mode is Review, Revise, or Proofread, the user provides a path to an existing .docx manuscript. Before any analysis:
docx skill if available, otherwise via pandoc directly. First check for the public docx skill at /mnt/skills/public/docx/SKILL.md (Claude Code cloud) or ~/.claude/skills/docx/SKILL.md (local install). If found, read its reading section and use it — it uses pandoc for text extraction plus direct XML access for structure. If neither path exists (common on local installs), extract directly: pandoc <file>.docx -t markdown for section text, and unzip -p <file>.docx word/document.xml for structure when needed. Either way, do not parse .docx with ad-hoc byte-level scripts.(Author Year) or (Author, Year) occurrence)Manuscript loaded: <filename>
Sections: [list]
Word count: N (Abstract: N, Introduction: N, ..., References: N entries)
Figures: N | Tables: N | Equations: N
Citations in text: N | Reference entries: N
Integrity: [OK / N orphan citations, M unused references, K figure/table gaps]
Do not proceed with mode-specific work until this extraction report is presented and the user confirms. If the manuscript is a .doc (legacy Word), convert to .docx first using the method in the docx skill.
The sections from here down (Citation workflow, Pause protocol, Section content guidance, QC, Export) apply to Draft mode only. For Review, Revise, or Proofread, read the corresponding mode reference file instead:
references/mode-review.mdreferences/mode-revise.mdreferences/mode-proofread.mdreferences/mode-audit.mdThe Figure necessity assessment (further down) applies to all modes — Review checks whether existing figures earn their place, Revise can recommend cutting them, Draft gates new ones.
Execute before drafting each section except the Abstract (most journals, including HJ, forbid citations in abstracts).
mcp__semantic-scholar__search_papers with fields paperId,title,authors,year,venue,externalIds,citationCount and limit 5. Never batch unrelated topics into one query.[CITATION NEEDED: <topic>] inline and continue. Never insert a low-quality citation to fill a slot.references/journal-*.md the user selected). Use externalIds.DOI when available.## REFERENCE LIST block that grows across the session, alphabetically sorted and deduplicated by DOI or title.Citations resolved this section: N
Unresolved [CITATION NEEDED] items: <list or "none">
Running reference list total: N entries
Never fabricate citations, DOIs, or author names. If Semantic Scholar returns nothing useful, the placeholder stays.
After completing each section, stop and present:
[Section Name] is drafted. Would you like to: (A) Continue to the next section (B) Revise this section before proceeding (C) Export what we have so far to .docx
Do not proceed to the next section until the user confirms. This is non-negotiable, it protects the user from long runs of drift.
If the user picks "all sections" or does not specify a starting point, recommend this writing order, not the IMRAD reading order:
If the user explicitly asks to write a different section first (e.g. "draft the Introduction"), do that, but warn once: "Writing the Introduction before Results is harder because the gap statement and study objectives need to align with what the paper actually delivers. I can draft it now and we revise after Results, or draft it later. Which would you prefer?"
The section structure, verb tenses, required sub-headings, abstract format, and reference list format all come from the loaded journal reference file. Re-read that file before writing each section if you're unsure about a detail — do not guess.
Generic guidance that applies to both supported journals:
references/introduction-structure.md before drafting. The Introduction must follow the five-move funnel (broad significance → narrowing literature review → specific gap → study objectives → roadmap). Every cited paper must support a specific claim, not pad the section.references/reproducibility.md for the replicability standard. Every equation, parameter, and setting must come from the cached source files. Methods must include enough detail for independent replication: data sources with access details, software versions, parameter ranges, calibration period, optimizer settings, convergence criteria.references/reproducibility.md. JHRS requires Data Availability and CRediT; HJ requires Data Availability and recommends the rest. These are not optional; missing back matter triggers desk rejection at both journals.Before generating the .docx, verify every item below. Fix or flag any failure.
Anti-fabrication (per references/anti-fabrication.md)
Content accuracy
Language
Citation integrity
[CITATION NEEDED] items listed for the userFigures & tables
Journal-specific QC
Reproducibility and back matter (per references/reproducibility.md)
Introduction structure (per references/introduction-structure.md)
When the user confirms export, generate the .docx via the public docx skill if it is installed, otherwise via the local pandoc → python-docx pipeline. Detection: check /mnt/skills/public/docx/SKILL.md (Claude Code cloud) and ~/.claude/skills/docx/SKILL.md (local install); if either exists, read its SKILL.md before generating — it is the canonical path in that environment and uses docx-js. Fallback (no docx skill present): follow the reproducible pipeline in references/manuscript-docx-style.md — pandoc converts the manuscript to .docx, then a python-docx post-process pass enforces the formatting spec. Run pip install python-docx first if the import is missing. Both paths must satisfy the export requirements below.
Export requirements regardless of journal:
[CITATION NEEDED] markers preserved for user reviewpython scripts/office/validate.py <filename>.docx after generationFor the full Word-output formatting spec (Times New Roman coercion across all run variants, Springer/booktabs three-rule table style, autofit + 100% width tables, mean ± std merging, TIFF figure format, citeproc citations, OMML equation handling, and the reproducible pandoc → python-docx post-process pipeline), read references/manuscript-docx-style.md before generating. That file is the canonical baseline; the journal reference file overrides it where they conflict.
Journal-specific export details (line spacing, highlights block, abstract structure, KMZ reminder) are in the loaded journal reference file.
Save to the workspace root with a filename the user specifies. Confirm creation and offer post-delivery revisions.
Figures are expensive — every figure costs reviewer attention, page budget, and production work. A paper with four strong figures is stronger than one with eight mediocre ones. This skill does not generate a default figure list. It proposes figures only after each candidate passes a necessity assessment.
Before proposing a figure, answer all four questions in writing (for yourself — do not show this to the user). If any answer is weak, do not propose the figure.
Propose figures once, at the end of Discussion drafting — not after Results, and never after every section. The timing matters:
If the user explicitly asks for figure ideas earlier (e.g. "what figures should I be preparing while we draft?"), you can list candidate figures with the caveat that the necessity assessment runs after Discussion. Do not skip the assessment just because the user asked early.
For figures that pass all four checks, format each as:
Fig. [N]: [Title]
It is acceptable and sometimes correct to propose zero figures for short sections, revision rounds, or papers where all the key findings are captured in 2–3 tables. If the necessity assessment fails for every candidate, say so explicitly:
"No figures recommended for this manuscript beyond what is already in the tables. The key findings are captured by Table [N] and Table [M], and adding figures would duplicate rather than extend the information."
Do not generate plotting code. Provide specifications only.
references/anti-fabrication.md — when in doubt, ask or flag, never invent. The most important rule in the skill. Read before any work in any mode.references/anti-summary-rules.md — write prose not outlines. Read before every Draft-mode writing session and before any Revise-mode proposed revision.references/anti-ai-style.md — write like a human, not like an AI. Read before every Draft-mode and Revise-mode writing session, and consulted by Proofread mode for compliance checks.references/introduction-structure.md — the five-move funnel for Introduction sections (broad significance → narrowing review → gap → objectives → roadmap). Read before drafting or revising any Introduction.references/reproducibility.md — Methods replicability standard, Data Availability and Code Availability statements, CRediT taxonomy, Conflict of Interest, Funding. Read when drafting Methods or back matter, and when reviewing/revising.references/manuscript-docx-style.md — canonical Word-output formatting spec: TNR coercion, Springer-style tables, mean ± std merging, TIFF figures, OMML equations, citeproc citations, and the reproducible pandoc → python-docx post-process pipeline. Read during Export to .docx.references/startup-interview.md — mode selection, exact startup questions, fast-path rules.references/journal-hydrogeology.md — HJ style, structure, citation format, pre-submission checklist.references/journal-jhrs.md — JHRS style, structured abstract, highlights, Elsevier reference format, pre-submission checklist.references/journal-tim.md — IEEE Transactions on Instrumentation and Measurement style: numeric bracketed citations, Roman-numeral primary headings, IEEEtran class notes, mandatory abstract/Index-Terms/Conclusion/Acknowledgment/References/Biographies order, first-footnote pattern, mandatory AI-disclosure block, pre-submission checklist. Read when targeting IEEE TIM (or as a starting point for other IEEE Transactions).references/journal-generic.md — field-agnostic baseline for any other quantitative-science journal: IMRaD structure, standard scientific tense, SI units, sequential numbering, mandatory Limitations subsection. Defers to the target journal's author guidelines on points that genuinely vary (citation style, word limits, abstract format, first-person policy). Read when the user selects generic.references/preset-example.md — Draft-mode fast-path preset template. Defines the structure of a project preset: detection trigger, data files to cache, fixed project facts (study area, period, CRS, model variants, parameter counts, classification rules, thresholds, optimiser), abbreviations, mandatory limitations, Semantic Scholar queries per section, forbidden content, candidate figure pool, mandatory tables. Copy to references/preset-<your-project>.md (or symlink from .local/) and fill in the placeholders to enable workspace-based fast-path detection.references/mode-review.md — Review mode: reviewer feedback rubric and report format.references/mode-revise.md — Revise mode: section-by-section suggestion format, reviewer-comment mapping, response letter drafting.references/mode-proofread.md — Proofread mode: allowed/forbidden edit scope, language and style compliance pass.references/mode-audit.md — Audit mode: end-to-end consistency and coherence checks across the manuscript, severity-tagged report.Read reference files lazily, only loading what the current mode and session need.
Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
npx claudepluginhub rekin226/paper-agent --plugin paper-agent