Paper Writer Skill

Full-pipeline academic paper writing assistant. From literature search to submission-ready manuscript.

Overview

This skill manages the entire paper writing workflow:

[Discovery] → Literature Search → Outline → Tables/Figures → Draft → Humanize → References → Quality Review → [Adversarial Review] → Pre-Submission → [Revision] → [Post-Acceptance] → [Rejection → Resubmission]

Each paper is a project directory containing structured Markdown files for every section, a literature matrix, and quality checklists.

AI-for-Science Operating Model

This skill is not only a manuscript factory (write → format → submit). It is a research engine that wraps the writing pipeline in a discovery loop and names the two things only a human can supply. Before doing anything else, read ~/.claude/skills/paper-writer/references/ai-for-science-model.md — it defines:

• The two human-sovereign inputs. 💡 IDEA (what is worth asking, what it means, what is ethical) and 📊 DATA (real, IRB-approved, never machine-originated). AI proposes and executes everything else at full power; the human owns exactly these two gates. AI must never originate a data point, participant, or result.
• The loop. Phase −1 Discovery (hypothesis → novelty → design → pre-registration lock) feeds the existing pipeline; Phase 6.5 Adversarial Review red-teams the central claim before any journal sees it. A red-team KILL sends the project back to Discovery — that is the system working.
• The three integrity guardrails that make AI-accelerated research more rigorous, not less: pre-registration (anti-HARKing), novelty check (anti-reinvention/inflation), adversarial self-review (anti-slop). Each prevents a documented frontier failure mode.
• The autonomy dial (Manual / Co-pilot / Autopilot). Hard rule for clinical work: the 💡 IDEA gate, the 📊 DATA gate, and the pre-registration lock are never autopilot.

The rest of this document is the execution detail. When a phase touches a sovereign gate, stop and get the human; everywhere else, run at full power.

Supported Paper Types

Type	Structure	Reporting Guideline	Notes
Original Article	Full IMRAD	STROBE / CONSORT	Default
Case Report	Intro / Case / Discussion	CARE	Separate templates
Review Article	Thematic sections	-	Flexible structure
Letter / Short Communication	Condensed IMRAD	Same as original	Word limit focus
Systematic Review	PRISMA-compliant	PRISMA 2020	With PRISMA checklist
Study Protocol	SPIRIT-compliant	SPIRIT 2025	For trial registration papers

Workflow

Phase −1: Discovery (the research engine)

This phase is what separates a research engine from a manuscript factory. The rest of the skill assumes the research question and the data already exist. Phase −1 produces them — a novelty-checked, powered, pre-registered study plan — before Project Init. Read ~/.claude/skills/paper-writer/references/ai-for-science-model.md first for the operating model.

Phase −1 is re-enterable — enter at the first guardrail not yet passed. It is not all-or-nothing: a study that already has a sharpened question (but no novelty check, power, or pre-registration) enters mid-chain, not at the forge. Route by the Phase −1 entry matrix:

What the user arrives with	Enter at	How
(a) A raw clinical observation	−1.1 Forge	Run templates/research-question.md in Mode A (forge a question from the spark), then continue −1.2 → −1.3 → −1.4 in order.
(b) An existing question / advanced protocol, pre-data	−1.2 Novelty	Run templates/research-question.md in Mode B (resume/refine — back-fill PECO, single Attack pass, FINER) first, then −1.2 novelty, then −1.3 design as an AUDIT of the existing protocol (not a fresh draft — check it against templates/study-design.md, fix gaps), then −1.4 prereg, then run references/adversarial-review.md in design-stage mode (§0, pre-data) BEFORE the pre-registration lock so cheap design fixes land before freezing.
(c) Question + design + data all locked	Skip to Phase 0	Pure writing-up. Still confirm the 💡 IDEA and 📊 DATA gates are human-owned and that a pre-registration exists or is consciously waived (and disclosed as such).

−1.2 novelty is the mandatory minimum entry for any unpublished study — novelty cannot be assumed from the fact that a protocol is already being written. Only path (c) (already locked + data in hand) may skip it.

Start the project's accountability ledger now: create log/human-loop-ledger.md from ~/.claude/skills/paper-writer/templates/human-loop-ledger.md and declare the autonomy mode (Manual / Co-pilot / Autopilot). Record every gate decision in it from here on.

Step −1.1: Forge the research question (💡 IDEA gate)

Read ~/.claude/skills/paper-writer/templates/research-question.md. From the user's clinical observation, generate 5–15 candidate questions, debate and rank them by FINER, evolve the top 2–3 — then stop and have the human select. AI never auto-selects the question. Output: one sharpened research question with its PICO.

Step −1.2: Novelty check (guardrail: anti-reinvention)

Read ~/.claude/skills/paper-writer/references/novelty-check.md. Run a live-literature sweep on the selected question using the real literature tools (PubMed MCP, OpenAlex, Europe PMC, Semantic Scholar — see Phase 1 plumbing). Classify the gap: genuinely novel / incremental / already-answered / contested. An already-answered question is killed here at near-zero cost. Do not inflate novelty — that is the Sakana v2 failure mode.

Step −1.3: Design the study & power it

Read ~/.claude/skills/paper-writer/templates/study-design.md. Choose the design, operationalize every PICO element into a measured variable, define the single primary outcome, map confounders with a DAG, and run a sample-size/power calculation (justify the effect size from the novelty-check literature, not from hope). Check feasibility against the clinic's real volume. This design becomes both the pre-registration and, later, the Methods section.

Step −1.4: Pre-register & lock (guardrail: anti-HARKing)

Read ~/.claude/skills/paper-writer/templates/preregistration.md. Freeze the hypotheses and the primary analysis plan (OSF / UMIN-CTR / jRCT / PROSPERO) before the 📊 DATA gate. After the lock: pre-registered analyses are confirmatory; everything else is exploratory and labeled as such. This is the integrity backbone for publishing under your own name. For retrospective data, register before examining outcome data and disclose the data's pre-existence honestly.

The 📊 DATA gate: only after the plan is locked does the human supply real, IRB-approved data. AI never originates data. Proceed to Phase 0.

---

Phase 0: Project Initialization

When the user invokes this skill, ask for:

1. Working title (can change later)
2. Paper type (Original Article / Case Report / Review / Letter / Systematic Review)
3. Target journal (optional but recommended)
4. Language (English / Japanese / Both)
5. Research question in one sentence
6. Key data available (what Tables/Figures already exist?)

Step 0.1: Capture Journal Requirements

If a target journal is specified, look up and document:

• Word limits: total manuscript, abstract, each section (if specified)
• Citation style: Vancouver, APA, NLM, or other
• Required sections: some journals require separate Conclusion, others don't
• Abstract format: structured or unstructured, word limit
• Figure/Table limits: maximum number allowed
• Reporting guideline: which checklist the journal requires
• Special requirements: cover page format, line numbering, etc.
• AI disclosure: whether the journal requires AI usage disclosure, and where (Methods, Acknowledgments, or dedicated section). See references/ai-disclosure.md.
• Keywords: number required, MeSH preferred or free-text. See references/keywords-guide.md.
• Graphical abstract: required or optional. See templates/graphical-abstract.md.

Use WebSearch to look up the journal's "Instructions for Authors" page.

Record all requirements in the README.md under a "Journal Requirements" section.

Step 0.2: Select Reporting Guideline

Based on paper type and study design, select the appropriate reporting guideline:

Study Type	Guideline	Reference
Randomized Controlled Trial	CONSORT 2025	references/reporting-guidelines-full.md
Observational study (cohort, case-control, cross-sectional)	STROBE	references/reporting-guidelines-full.md
Systematic review / meta-analysis	PRISMA 2020	references/reporting-guidelines-full.md
Case report	CARE	references/reporting-guidelines-full.md
Diagnostic accuracy study	STARD 2015	references/reporting-guidelines-full.md
Quality improvement study	SQUIRE 2.0	references/reporting-guidelines-full.md
Study protocol (clinical trial)	SPIRIT 2025	references/reporting-guidelines-full.md
Prediction model (incl. AI/ML)	TRIPOD+AI 2024	references/reporting-guidelines-full.md
Animal research	ARRIVE 2.0	references/reporting-guidelines-full.md
Health economics	CHEERS 2022	references/reporting-guidelines-full.md

Read ~/.claude/skills/paper-writer/references/reporting-guidelines.md (summary) or references/reporting-guidelines-full.md (comprehensive) and note the key checklist items for the selected guideline. These items will be checked throughout the writing process.

Step 0.3: Create Project Directory

For Original Article / Review / Letter / Systematic Review:

{project-dir}/
├── README.md                        # Project dashboard (status, timeline, links)
│
├── 00_literature/                   # Phase 1: Literature
│   ├── search-strategy.md           #   Search terms, databases, dates
│   ├── literature-matrix.md         #   Structured comparison table
│   └── key-papers/                  #   Notes on important papers (1 file per paper)
│
├── 01_outline.md                    # Phase 2: Paper skeleton
│
├── sections/                        # Phase 3: Manuscript sections (writing order)
│   ├── 02_methods.md
│   ├── 03_results.md
│   ├── 04_introduction.md
│   ├── 05_discussion.md
│   ├── 06_conclusion.md
│   ├── 07_abstract.md
│   └── 08_title.md
│
├── tables/                          # Tables (numbered: table1_baseline.md, ...)
├── figures/                         # Figures + captions (fig1_caption.md, ...)
├── supplements/                     # Supplementary materials
│   ├── supplementary-tables/        #   e.g., tableS1_sensitivity.md
│   ├── supplementary-figures/       #   e.g., figS1_subgroup.md
│   └── appendices/                  #   Additional methods, datasets, etc.
│
├── data/                            # Research data (see templates/data-management.md)
│   ├── raw/                         #   Original data (READ-ONLY, gitignored)
│   ├── processed/                   #   Cleaned, de-identified data
│   ├── analysis/                    #   Statistical output, scripts
│   └── data-dictionary.md           #   Variable definitions
│
├── ethics/                          # Ethics & regulatory
│   ├── irb-approval.md              #   IRB approval details, number, dates
│   ├── informed-consent.md          #   Consent process documentation
│   ├── protocol.md                  #   Study protocol (SPIRIT if applicable)
│   └── registration.md              #   Trial/study registration (UMIN, ClinicalTrials.gov)
│
├── submissions/                     # Submission history (1 subfolder per attempt)
│   └── v1_{journal}/                #   e.g., v1_bmj/
│       ├── compiled-manuscript.md   #     Full compiled manuscript snapshot
│       ├── cover-letter.md          #     Cover letter
│       ├── title-page.md            #     Title page
│       ├── declarations.md          #     Ethics, COI, funding, AI disclosure
│       ├── highlights.md            #     Key points (if required)
│       ├── graphical-abstract.md    #     Graphical abstract (if required)
│       └── submission-log.md        #     Date, portal, manuscript #, status
│
├── revisions/                       # Revision rounds (Phase 8)
│   └── r1/                          #   Round 1
│       ├── reviewer-comments.md     #     Original reviewer comments
│       ├── response-letter.md       #     Point-by-point response
│       ├── revision-cover-letter.md #     Revision cover letter
│       ├── diff-summary.md          #     Changes made (section, line, change)
│       └── compiled-manuscript.md   #     Revised manuscript snapshot
│
├── coauthor-review/                 # Co-author feedback tracking
│   ├── review-tracker.md            #   Who reviewed, when, status
│   └── feedback/                    #   Individual feedback files
│
├── correspondence/                  # Editor & reviewer communication log
│   └── YYYY-MM-DD_{subject}.md      #   e.g., 2026-03-05_decision-letter.md
│
├── references/                      # Reference management
│   └── 09_references.md             #   Formatted reference list
│
├── checklists/                      # Quality control
│   ├── section-quality.md           #   Per-section quality scores
│   ├── submission-ready.md          #   Pre-submission checklist
│   ├── reporting-guideline.md       #   CONSORT/STROBE/etc. item tracking
│   ├── gate-state.md                #   Stage-gate iteration state
│   └── feedback-*.md                #   Auto-generated gate feedback
│
└── log/                             # Decision & progress log
    ├── decisions.md                 #   Key decisions with rationale
    ├── meetings.md                  #   Meeting notes (co-authors, supervisor)
    └── timeline.md                  #   Milestone targets & actual dates

For Case Report:

{project-dir}/
├── README.md                        # Project dashboard
│
├── 00_literature/
│   ├── search-strategy.md
│   ├── literature-matrix.md
│   └── key-papers/
│
├── 01_outline.md
│
├── sections/
│   ├── 02_case.md                   # Case presentation (CARE structure)
│   ├── 03_introduction.md           # Introduction (why reportable)
│   ├── 04_discussion.md
│   ├── 05_abstract.md               # Abstract (CARE format)
│   └── 06_title.md                  # Title (must contain "case report")
│
├── tables/
├── figures/
├── supplements/
│   ├── supplementary-tables/
│   ├── supplementary-figures/
│   └── appendices/
│
├── data/
│   ├── raw/
│   ├── processed/
│   ├── analysis/
│   └── data-dictionary.md
│
├── ethics/
│   ├── irb-approval.md
│   ├── informed-consent.md          # Patient consent for publication
│   └── patient-perspective.md       # Patient's perspective (CARE item)
│
├── submissions/
│   └── v1_{journal}/
│       ├── compiled-manuscript.md
│       ├── cover-letter.md
│       ├── title-page.md
│       ├── declarations.md
│       └── submission-log.md
│
├── revisions/
│   └── r1/
│       ├── reviewer-comments.md
│       ├── response-letter.md
│       ├── diff-summary.md
│       └── compiled-manuscript.md
│
├── coauthor-review/
│   ├── review-tracker.md
│   └── feedback/
│
├── correspondence/
│   └── YYYY-MM-DD_{subject}.md
│
├── references/
│   └── 07_references.md
│
├── checklists/
│   ├── section-quality.md
│   ├── submission-ready.md
│   ├── reporting-guideline.md
│   ├── gate-state.md
│   └── feedback-*.md
│
└── log/
    ├── decisions.md
    ├── meetings.md
    └── timeline.md

Read ~/.claude/skills/paper-writer/templates/project-init.md with the Read tool and use it to generate README.md. For Case Reports, use project-init-case.md instead.

File numbering follows the recommended writing order, not the reading order. This is intentional.

Step 0.4: Organize Research Data

If the user has existing research data (clinical records, CSV files, statistical output, etc.):

1. Create data/raw/, data/processed/, data/analysis/ directories
2. Read ~/.claude/skills/paper-writer/templates/data-management.md for the full template
3. Ask the user to place raw data files in data/raw/ — these files are READ-ONLY from this point
4. Create data/raw/README.md documenting the data source, extraction date, and IRB information
5. Create data/data-dictionary.md listing all variables with types, ranges, and labels
6. Confirm de-identification status — if not yet de-identified, create a processing plan in data/processed/README.md

Security rules:

• NEVER commit patient-identifiable data to git
• Add data/raw/*.csv, data/raw/*.xlsx etc. to .gitignore if the repository is shared
• Always confirm IRB approval number before proceeding with data analysis

Data flow: raw/ (never modify) → processed/ (clean, de-identify) → analysis/ (statistical output) → tables/ and figures/ (manuscript-ready)

Step 0.5: Data Analysis

If the user has quantitative data ready for analysis, Claude Code can execute Python scripts directly. Read ~/.claude/skills/paper-writer/templates/analysis-workflow.md for the full workflow.

Available analysis scripts:

Script	Purpose	Key Output
scripts/table1.py	Table 1 (baseline characteristics)	Markdown table with N, %, mean±SD, P values
scripts/analysis-template.py	Statistical analyses	Descriptive stats, t-test, logistic regression, survival
scripts/forest-plot.py	Forest plot (meta-analysis)	PNG + SVG

Workflow:

1. Inspect data: Load data/processed/cohort_final.csv, check shape, dtypes, missing values
2. Table 1: Run scripts/table1.py to generate baseline characteristics table → tables/table1.md
3. Primary analysis: Choose analysis type based on study design:
   • Cross-sectional / case-control → logistic regression (OR with 95% CI)
   • Cohort with time-to-event → survival analysis (Kaplan-Meier, log-rank)
   • Continuous outcome → linear regression
   • Group comparison → t-test / Mann-Whitney U
4. Subgroup & sensitivity analyses: By sex, age group, disease severity, etc.
5. Generate figures: Box plots, KM curves, forest plots, ROC curves
6. Link to manuscript: Map analysis output to Results section paragraphs

Analysis output directory: All results go to data/analysis/. Figures for the manuscript go to figures/.

Required Python packages: Install the utility-script dependencies from the skill root:

pip install -r ~/.claude/skills/paper-writer/requirements.txt

Statistical reporting requirements (before writing Results):

• Effect sizes with 95% confidence intervals
• P values to 3 decimal places (P < 0.001 for very small)
• Statistical test names specified
• Software and version documented
• Two-sided tests (unless justified)
• Multiple comparison correction (if >1 primary outcome)
• Missing data handling described

See references/statistical-reporting-full.md for detailed SAMPL guidelines and templates/analysis-workflow.md for step-by-step commands.

Phase 1: Literature Search & Organization

Step 1.1: Define Search Strategy

Create 00_literature/search-strategy.md with:

• Databases: PubMed, Google Scholar (always available); Scopus, CiNii (if user has institutional access)
• Search terms: MeSH terms + free-text keywords
• Inclusion/exclusion criteria for papers
• Date range

How to search — use REAL literature tools, not plain web search.

This skill runs in an environment with a real PubMed MCP and research APIs. These return structured, verifiable records (PMID, DOI, authors, abstract) — use them as the primary path. Plain WebSearch is a fallback, not the default.

Primary: PubMed MCP (biomedical, authoritative). Build the query with references/pubmed-query-builder.md, then:

• mcp__claude_ai_PubMed__search_articles — run the MeSH + free-text query
• mcp__claude_ai_PubMed__get_article_metadata — pull structured metadata per PMID
• mcp__claude_ai_PubMed__find_related_articles — snowball from a key seed paper
• mcp__claude_ai_PubMed__lookup_article_by_citation — resolve a citation to a PMID/DOI
• mcp__claude_ai_PubMed__get_full_text_article — fetch full text where available

Supplementary APIs (broader coverage; fetch via WebFetch / firecrawl_scrape / tavily_search):

• OpenAlex — https://api.openalex.org/works?search=... (filter by year, cited_by_count)
• Europe PMC — https://www.ebi.ac.uk/europepmc/webservices/rest/search?query=...&format=json (full text, preprints)
• Semantic Scholar — https://api.semanticscholar.org/graph/v1/paper/search?query=... (citation graph, influential-citation counts)
• Cochrane / PROSPERO / Epistemonikos — check for existing or in-progress systematic reviews

Why this matters: structured-record retrieval means every paper carries a real PMID/DOI, so the "is this citation fabricated?" risk drops sharply versus free-text web search. Still verify per references/citation-verification.md.

Workflow:

1. Ask the user for their 3–5 key papers (they usually know them) — use these as snowball seeds for find_related_articles
2. Run the PubMed MCP query; supplement with OpenAlex / Europe PMC / Semantic Scholar for non-PubMed and preprint coverage
3. De-duplicate by DOI; have the user validate the final list for completeness
4. Verify every citation resolves to a real record (references/citation-verification.md)

Step 1.2: Build Literature Matrix

Read ~/.claude/skills/paper-writer/templates/literature-matrix.md with the Read tool.

For each relevant paper found, extract and organize:

Author (Year)	Design	N	Population	Key Finding	Limitation	Relevance

Aim for 15-30 papers for an original article, 8-15 for a case report, 30-50 for a systematic review.

Step 1.3: Identify Key Papers

For the 3-5 most important papers, create individual notes in 00_literature/key-papers/ with:

• Full citation
• Study design and quality assessment
• Key results with exact numbers
• How it relates to the current paper
• What gap it leaves (that our paper addresses)

Phase 1.5: Screening Execution (Systematic Review only)

Applies only to Systematic Reviews. Skip for all other paper types.

Phase 1 builds a search; Phase 3-D writes the PRISMA Methods/Results. Between them sits the actual study selection — dedup, dual screening, and the record counts that fill the PRISMA flow diagram. This phase runs that pipeline.

Read ~/.claude/skills/paper-writer/templates/sr-screening-pipeline.md with the Read tool for the full procedure. In brief:

1. Prerequisite — registered protocol. Eligibility criteria must exist in 00_literature/protocol.md (from templates/sr-prospero.md) and the protocol must be registered (PROSPERO) BEFORE screening. Do not start otherwise.

2. Stage 1 — De-duplicate (deterministic). Place raw DB exports in 00_literature/screening/00_imported/ (one file per database), then run:

   python ~/.claude/skills/paper-writer/scripts/sr-dedup.py \
     --input 00_literature/screening/00_imported \
     --output 00_literature/screening/01_deduplicated.csv \
     --counts 00_literature/screening/counts/identification.json