Paper Writer Skill

A Claude Code skill for medical/scientific paper writing. Covers the entire manuscript lifecycle from literature search to submission, peer review response, and rejection handling.

日本語版はこちら → README.ja.md

Overview

Not just a manuscript factory (write → format → submit) but a research engine:
a discovery loop that generates and ranks research questions, checks their novelty
against the live literature, designs and powers the study, locks a pre-registered
plan, and — after the manuscript is drafted — red-teams its own central claim before
any journal sees it. Two things stay human and protected at every gate: the 💡 IDEA
(what is worth asking, what it means, what is ethical) and the 📊 DATA (real,
IRB-approved, never machine-originated). See
references/ai-for-science-model.md.

A pipeline that generates and manages IMRAD-format project directories with
structured Markdown files, a literature matrix, and quality checklists.

graph LR
    P0["−1. Discovery\n(question · novelty · design · pre-reg)"] --> P1[1. Literature Search]
    P1 --> P2[2. Outline]
    P2 --> P25[2.5 Tables/Figures]
    P25 --> P3[3. Draft]
    P3 --> P4[4. Humanize]
    P4 --> P5[5. References]
    P5 --> P6[6. Quality Review]
    P6 --> P65["6.5 Adversarial Review"]
    P65 --> P7[7. Pre-Submission]
    P65 -.->|KILL| P0
    P7 --> P8["8. Revision ①"]
    P8 --> P9["9. Post-Acceptance"]
    P7 -.-> P10["10. Rejection → Resubmit"]
    P10 -.-> P1

Architecture: Autonomous Stage-Gate System (v3.1)

Every phase is guarded by a quality gate. If the gate returns FAIL, the system automatically generates structured feedback, dispatches a fixer agent in revision_mode, and re-checks — up to 3 iterations before escalating to the user. No phase proceeds until its gate returns PASS.

flowchart TD
    subgraph "Per-Phase Loop (max 3 iterations)"
        A["Phase N Complete"] --> B{"Quality Gate"}
        B -->|PASS| C["→ Phase N+1"]
        B -->|FAIL iter < 3| D["Generate feedback.md"]
        D --> E["Fixer Agent\n(revision_mode)"]
        E --> B
        B -->|FAIL iter ≥ 3| F["⚠ Escalate to User"]
    end

    style B fill:#f9a825,stroke:#f57f17,color:#000
    style C fill:#66bb6a,stroke:#388e3c,color:#fff
    style F fill:#ef5350,stroke:#c62828,color:#fff

8 Quality Gates

flowchart LR
    subgraph "Phase 1"
        G1["📚 Literature\n≥10 papers\nAll DOIs valid"]
    end
    subgraph "Phase 2"
        G2["📋 Outline\nAll IMRAD sections\n≥2 citations mapped"]
    end
    subgraph "Phase 2.5"
        G25["📊 Tables/Figures\nAll designs complete\nJournal limits OK"]
    end
    subgraph "Phase 3"
        G3["✍️ Section Draft\nScore ≥80%\nMust Fix = 0"]
    end
    subgraph "Phase 4"
        G4["🔍 Humanize\nHigh-priority\nAI patterns = 0"]
    end
    subgraph "Phase 5"
        G5["📖 References\nFabrication = 0\nOrphan cites = 0"]
    end
    subgraph "Phase 6"
        G6["🔗 Cross-Section\nPASS or\nCONDITIONAL_PASS"]
    end
    subgraph "Phase 7"
        G7["📦 Submission\nAll docs ready\nWord count OK"]
    end

    G1 --> G2 --> G25 --> G3 --> G4 --> G5 --> G6 --> G7

Team Mode: 7 Parallel Agents (v3.0)

Phases are parallelized with specialized agents running concurrently:

flowchart TB
    subgraph P1["Phase 1 — Literature Search (3 parallel)"]
        L1[PubMed Searcher]
        L2[Google Scholar Searcher]
        L3[Domain DB Searcher]
    end

    subgraph P3["Phase 3 — Drafting (grouped parallel)"]
        direction LR
        D1[Methods] --> D3[Intro]
        D2[Results] --> D4[Conclusion]
    end

    subgraph P4["Phase 4 — Humanize (up to 6 parallel)"]
        H1[Humanizer × N sections]
    end

    subgraph P6["Phase 6 — Quality Review"]
        R1[Section Reviewer ×N]
        R2[Quality Gate — opus]
    end

    L1 & L2 & L3 --> MERGE["Merge Matrix"]
    MERGE --> D1 & D2
    D3 & D4 --> H1
    H1 --> R1
    R1 --> R2

Supported Paper Types

Usage

Invoke from Claude Code

/paper-writer

Or use natural language triggers:

• write paper / start manuscript / research paper
• 論文を書く / 論文執筆 / 原稿作成

Project Setup

The skill prompts you for:

1. Working title
2. Paper type (one of the 6 types above)
3. Target journal (optional, recommended)
4. Language (English / Japanese / Both)
5. Research question (one sentence)
6. Available data (existing tables/figures)

When a target journal is specified, the skill automatically looks up word limits, citation style, abstract format, and other requirements.

Generated Project Structure (v3.2)

Each paper project generates a comprehensive directory for managing the entire research lifecycle:

{project-dir}/
├── README.md                        # Project dashboard (status, timeline, links)
├── 00_literature/                   # Literature search & matrix
├── 01_outline.md                    # Paper skeleton
├── sections/                        # Manuscript sections (writing order)
│   ├── 02_methods.md ... 08_title.md
├── tables/                          # Tables (numbered)
├── figures/                         # Figures + captions
├── supplements/                     # Supplementary materials
│   ├── supplementary-tables/
│   ├── supplementary-figures/
│   └── appendices/
├── data/                            # Research data (raw → processed → analysis)
│   ├── raw/                         # Original data (READ-ONLY, gitignored)
│   ├── processed/                   # Cleaned, de-identified
│   ├── analysis/                    # Statistical output
│   └── data-dictionary.md
├── ethics/                          # IRB, consent, protocol, registration
├── submissions/                     # Submission history (v1_bmj/, v2_lancet/, ...)
│   └── v1_{journal}/               # Compiled manuscript + cover letter + declarations
├── revisions/                       # Revision rounds (r1/, r2/, ...)
│   └── r1/                          # Reviewer comments + response + diff
├── coauthor-review/                 # Co-author feedback tracking
├── correspondence/                  # Editor & reviewer communication log
├── references/                      # Formatted reference list
├── checklists/                      # Quality gates, reporting guideline tracking
└── log/                             # Decisions, meetings, timeline

File Structure

paper-writer/
├── SKILL.md                           # Main workflow definition
├── CHANGELOG.md                       # Version history
├── README.md                          # This file
├── README.ja.md                       # Japanese documentation
├── requirements.txt                   # Python dependencies for utility scripts
│
├── templates/                         # 37 files — Section templates
│   ├── project-init.md                # Project initialization (Original Article)
│   ├── project-init-case.md           # Project initialization (Case Report)
│   ├── research-question.md           # Question forge and FINER scoring
│   ├── study-design.md                # Study design, variables, power, feasibility
│   ├── preregistration.md             # Pre-registration lock template
│   ├── human-loop-ledger.md           # Human/AI accountability ledger
│   ├── literature-matrix.md           # Literature comparison matrix
│   ├── methods.md                     # Methods writing guide
│   ├── results.md                     # Results writing guide
│   ├── introduction.md                # Introduction writing guide
│   ├── discussion.md                  # Discussion writing guide
│   ├── conclusion.md                  # Conclusion writing guide
│   ├── abstract.md                    # Abstract writing guide (Original Article)
│   ├── cover-letter.md                # Cover letter template
│   ├── submission-ready.md            # Pre-submission checklist
│   ├── case-report.md                 # Case presentation (CARE-compliant)
│   ├── case-introduction.md           # Case report introduction
│   ├── case-abstract.md               # Case report abstract (CARE format)
│   ├── review-article.md              # Review article structure guide
│   ├── sr-outline.md                  # Systematic review outline
│   ├── sr-data-extraction.md          # SR data extraction template
│   ├── sr-prisma-flow.md              # PRISMA flow diagram
│   ├── sr-grade.md                    # GRADE evidence assessment
│   ├── sr-rob.md                      # Risk of bias assessment
│   ├── sr-prospero.md                 # PROSPERO registration template
│   ├── sr-screening-pipeline.md       # Dual-screening execution pipeline
│   ├── response-to-reviewers.md       # Response to reviewers template
│   ├── revision-cover-letter.md       # Revision cover letter
│   ├── declarations.md                # Declarations (ethics, COI, funding, AI disclosure)
│   ├── graphical-abstract.md          # Graphical abstract guide
│   ├── title-page.md                  # Title page template
│   ├── highlights.md                  # Key points / highlights (JAMA, BMJ, etc.)
│   ├── limitations-guide.md           # Limitations section guide
│   ├── acknowledgments.md             # Acknowledgments template
│   ├── proof-correction.md            # Post-acceptance proof correction guide
│   ├── data-management.md             # Data management (raw/processed/analysis)
│   └── analysis-workflow.md           # Data analysis workflow guide
│
├── references/                        # 30 files — Reference materials
│   ├── ai-for-science-model.md        # Research-engine operating model
│   ├── novelty-check.md               # Live-literature novelty check
│   ├── adversarial-review.md          # Design/manuscript red-team review
│   ├── imrad-guide.md                 # IMRAD structure and writing principles
│   ├── section-checklist.md           # Per-section quality checklist
│   ├── citation-guide.md              # Citation formatting and management
│   ├── citation-verification.md       # Citation verification guide
│   ├── reporting-guidelines.md        # Reporting guidelines summary
│   ├── reporting-guidelines-full.md   # 20+ reporting guidelines with checklists
│   ├── humanizer-academic.md          # AI writing detection (EN 18 + JP 13 patterns)
│   ├── statistical-reporting.md       # Statistical reporting guide
│   ├── statistical-reporting-full.md  # Extended SAMPL guide
│   ├── journal-selection.md           # Journal selection strategy
│   ├── pubmed-query-builder.md        # PubMed search query builder
│   ├── multilingual-guide.md          # Multilingual support guide
│   ├── coauthor-review.md             # Co-author review process
│   ├── ai-disclosure.md               # ICMJE 2023 AI disclosure guide
│   ├── tables-figures-guide.md        # Tables and figures creation guide
│   ├── keywords-guide.md              # Keywords and MeSH selection strategy
│   ├── supplementary-materials.md     # Supplementary materials strategy
│   ├── hook-compatibility.md          # Claude Code hook compatibility
│   ├── submission-portals.md          # Submission portal guide
│   ├── open-access-guide.md           # OA models, APCs, CC licenses
│   ├── clinical-trial-registration.md # Clinical trial registration guide
│   ├── abstract-formats.md            # Journal-specific abstract formats
│   ├── word-count-limits.md           # Word count limits by journal
│   ├── coi-detailed.md               # COI categories, CRediT taxonomy, ORCID
│   ├── desk-rejection-prevention.md   # Desk rejection prevention
│   ├── journal-reformatting.md        # Journal reformatting and cascading strategy
│   └── master-reference-list.md       # Master URL list (100+ links, 13 categories)
│
├── scripts/                           # 8 files — Utilities & Analysis
│   ├── compile-manuscript.sh          # Compile sections into single manuscript
│   ├── word-count.sh                  # Word count utility
│   ├── forest-plot.py                 # Forest plot generator
│   ├── sr-dedup.py                    # SR record parsing and de-duplication
│   ├── sr-pdf-link.py                 # Link full-text PDFs to records by DOI
│   ├── sr-prisma-count.py             # PRISMA flow counts and consistency checks
│   ├── table1.py                      # Table 1 generator (baseline characteristics)
│   └── analysis-template.py           # Statistical analysis template (t-test, logistic, survival)
│
├── tests/
│   └── test_scripts.py                # Regression tests for utility scripts
│
└── .github/workflows/
    └── tests.yml                      # CI: syntax checks + regression tests

Total: 83 tracked files (37 templates + 30 references + 8 scripts + tests + CI + root docs/config)

Workflow (10 Phases)

Reporting Guidelines (20+)

CONSORT 2025, STROBE, PRISMA 2020, CARE, STARD 2015, SQUIRE 2.0, SPIRIT 2025, TRIPOD+AI 2024, ARRIVE 2.0, CHEERS 2022, MOOSE, TREND, SRQR, COREQ, AGREE II, RECORD, STREGA, ENTREQ, PRISMA-ScR, GRADE

Language Support

AI Writing Detection (Humanizer)

A dedicated phase (Phase 4) to remove AI-generated writing patterns from academic manuscripts.

• English: 18 patterns (significance inflation, AI vocabulary, filler phrases, etc.)
• Japanese: 13 patterns (symbol overuse, rhythm monotony, academic-specific issues)
• Section-specific priority patterns
• Before/after examples included

Master Reference List

references/master-reference-list.md contains 100+ URLs organized in 13 categories:

1. Author Guidelines (ICMJE, EQUATOR, etc.)
2. Reporting Guidelines (CONSORT, STROBE, etc.)
3. Ethics & Registration (ClinicalTrials.gov, UMIN, etc.)
4. Statistics (SAMPL, Cochrane, etc.)
5. Literature Databases (PubMed, Google Scholar, etc.)
6. Reference Managers (Zotero, Mendeley, etc.)
7. Submission Portals (ScholarOne, etc.)
8. AI Disclosure (ICMJE, Nature policies, etc.)
9. Open Access (DOAJ, Sherpa Romeo, etc.)
10. Writing Support (editing services, etc.)
11. Figure/Table Tools (BioRender, GraphPad, etc.)
12. Journal Author Instructions (major journals)
13. Japanese Resources (Ichushi, CiNii, etc.)

Installation

Clone this repository into the Claude Code skills directory:

git clone https://github.com/kgraph57/paper-writer-skill.git ~/.claude/skills/paper-writer

Register the skill in Claude Code settings:

// Add to "skills" in ~/.claude/settings.json
{
  "skills": {
    "paper-writer": {
      "path": "~/.claude/skills/paper-writer"
    }
  }
}

Requirements

• Claude Code CLI
• WebSearch / WebFetch (used for literature search)
• Python 3 for utility scripts
• Python packages for analysis/PDF utilities: python -m pip install -r requirements.txt

Development

python -m py_compile scripts/*.py
bash -n scripts/*.sh
python -m unittest discover -s tests -v

License

Private repository.

Versions

• v3.2.0 (2026-03-05) — Research project folder management: comprehensive directory restructuring
• v3.1.0 (2026-03-05) — Autonomous Stage-Gate System: 8 quality gates with auto-fix loops
• v3.0.0 (2026-03-05) — Team Mode: 7 parallel agents for concurrent execution
• v2.1.0 (2026-02-17) — Data management & analysis integration, 4 new files
• v2.0.0 (2026-02-17) — Full lifecycle coverage, 16 new files, 10 phases
• v1.0.0 (2026-02-17) — Structural improvements, 6 new files, 5 paper types

See CHANGELOG.md for details.