Agent Skills: Medical Manuscript Writing

Medical Manuscript Writing

Transform manuscripts from data reports into persuasive scientific arguments.

The Core Shift

Stop reporting. Start arguing.

| Report Thinking | Argumentation Thinking | |----------------|----------------------| | "I did X, found Y, concluded Z" | "There's a problem, current answers fall short, here's a better one" | | Paragraphs present data | Every paragraph advances the argument | | Reader sees your lab notebook | Reader sees your insight |

Before writing any paragraph, ask: What role does this play in my argument? If you can't answer, the paragraph doesn't belong — or needs repositioning.

When to Use

• Writing a new original research manuscript
• Revising a draft that reads "flat" or "boring"
• Reviewing a colleague's manuscript for structural issues
• Preparing a response to reviewer comments
• Transitioning from thesis/report style to journal style

Master Checklist

Copy and track progress through each section:

Pre-Writing

• [ ] Define your nugget: the single insight that makes your problem solvable
• [ ] Define your one-sentence argument (what gap you fill and why it matters)
• [ ] Write a 3-sentence elevator pitch (problem → insight → result)
• [ ] Identify your target journal and its conventions
• [ ] Outline the logical chain: Gap → Approach → Key Finding → Implication
• [ ] Draft placeholder figures — they are the paper's skeleton
• [ ] Identify your audience (clinicians, methodologists, policy makers?)
• [ ] Write a shitty first draft early — perfection comes in revision

Detailed guidance: references/process.md

Title

• [ ] Condenses the key insight (not just the topic)
• [ ] Searchable — contains main variables, population, and study design
• [ ] Under journal character limit
• [ ] No abbreviations (unless universally recognized like ICU, HIV)

Abstract

• [ ] Follows journal's required structured format (Background/Methods/Results/Conclusions)
• [ ] Background uses Goal → Problem → Solution rhythm
• [ ] Results state primary outcome with effect size and 95% CI
• [ ] Conclusions state the clinical implication, not just the statistical finding
• [ ] No claims absent from the main text
• [ ] Word count within journal limit

Detailed guidance: references/abstract.md

Introduction

• [ ] Opens with a specific clinical dilemma, not a textbook sentence
• [ ] Literature builds a logical chain toward your gap (not a stack of citations)
• [ ] Gap statement is crisp and specific
• [ ] Final paragraph states exact study strategy (data, method, outcome)
• [ ] Every citation serves a purpose (importance, prior limitation, or theoretical basis)

Detailed guidance: references/introduction.md

Methods

• [ ] Organized by research logic, not by tool category
• [ ] Key methodological decisions include justification ("why this method")
• [ ] Sensitivity analyses target your biggest threats to validity
• [ ] Reporting follows a guideline (STROBE, CONSORT, PRISMA, etc.)

Detailed guidance: references/methods.md

Results

• [ ] Opens with a bird's-eye view before any details
• [ ] Baseline characteristics in text limited to clinically relevant differences
• [ ] Presentation order follows research questions, not analysis chronology
• [ ] No interpretation or speculation (no "This suggests..." or "This may be because...")
• [ ] Tables and figures referenced by finding, not narrated line-by-line

Detailed guidance: references/results.md

Discussion

• [ ] First paragraph is a conceptual elevator pitch (finding + clinical picture + significance)
• [ ] Interpretation organized in layers (biological → methodological → clinical)
• [ ] Inconsistent results honestly engaged, not ignored
• [ ] Literature comparison builds your explanatory framework, not a citation list
• [ ] Limitations are balanced: acknowledge → mitigate → contextualize
• [ ] Conclusion states clinical implication, not just statistical summary

Detailed guidance: references/discussion.md

Sentence-Level Polish

• [ ] Subjects are study variables or actions, not passive constructions
• [ ] Each paragraph's first and last sentences carry the main message
• [ ] No hedge stacking ("may possibly potentially suggest...")
• [ ] Eliminated empty adjectives ("interesting", "important", "noteworthy")
• [ ] Read aloud — every sentence flows naturally

Detailed guidance: references/sentence-craft.md

Figures & Tables

• [ ] Every figure has a single take-home message
• [ ] Figure legends are self-contained (method, sample, key stats, abbreviations)
• [ ] Tables show only study-relevant variables (extras go to supplement)
• [ ] Large-sample comparisons use SMD instead of p-values where appropriate

Detailed guidance: references/figures-tables.md

Overall Rhythm

• [ ] Information-dense paragraphs followed by interpretive breathing room
• [ ] No three consecutive paragraphs with the same "found A, p=B, consistent with C" pattern
• [ ] Transitions between sections feel guided, not mechanical
• [ ] Read aloud — if it sounds dull or stilted to you, it reads worse to others

Section Quick Reference

| Section | Goal | Fatal Mistake | Fix | |---------|------|--------------|-----| | Title | Condense key insight | Generic topic label ("A Study of X and Y") | Include variables + finding direction | | Abstract | Standalone argument | Missing structured rhythm | Goal → Problem → Solution in each sub-section | | Introduction | Build logical case for your study | Starting with "X is a leading cause of death" | Open with a specific clinical dilemma | | Methods | Earn reader trust | Listing tools without justification | Explain why for key decisions | | Results | Present facts that advance the argument | Smuggling interpretation ("suggests...") | Facts only; interpretation in Discussion | | Discussion | Provide conceptual significance | Restating results with p-values | Lead with meaning, not numbers | | Figures | Deliver one message per figure | Cluttered figures without clear takeaway | Design around the take-home message |

Common Anti-Patterns

| Anti-Pattern | Example | Better Approach | |-------------|---------|----------------| | Textbook opening | "Cancer is a leading cause of death worldwide" | Specific clinical dilemma your study addresses | | Citation stacking | "Smith (2020) found X. Jones (2021) found Y." | Synthesize into a logical chain with inline citations | | Vague study aim | "We aimed to explore the relationship between X and Y" | "We used [database] with [method] to test [specific hypothesis]" | | Lab-notebook Results | Narrating every row of Table 1 | Highlight only clinically meaningful differences | | Statistical Discussion | "HR was 2.4 (95% CI 1.8–3.2, p<0.001)" as Discussion opener | Lead with conceptual significance, not numbers | | Self-destructive Limitations | Listing every weakness until the study sounds worthless | Acknowledge → mitigate → contextualize | | Hedge stacking | "It is possible that this may potentially suggest..." | One hedge per claim: "This suggests..." | | Empty adjectives | "Interestingly, we found..." | Show the contrast or surprise directly | | Afterthought title | "A Study of LDH Levels in ICU Patients" | Condense the nugget: "Serial LDH Trajectories Predict 90-Day Mortality in Critically Ill Patients" | | No defined nugget | Starting to write without a core argument | Define the one insight that makes your problem solvable before writing | | Rough draft to senior author | Sending a messy draft expecting rescue | Polish first; let them focus on argument, not grammar |

Reviewer Psychology

Reviewers must: (1) summarize your paper, (2) identify strengths, (3) evaluate validity, (4) find weaknesses. Support them:

| Reviewer Need | How to Help | |--------------|-------------| | Summarize | Crystal-clear abstract + Discussion opener = easy summary | | Identify strengths | Explicit contribution statements in Introduction's final paragraph | | Evaluate validity | Sensitivity analyses with clear reporting in Results | | Find weaknesses | Honest limitations section (they will find them regardless) |

If a reviewer cannot quickly summarize your paper, your structure has failed — not the reviewer.

Detailed guidance: references/process.md

Proofreading Protocol

• [ ] Read for argument flow — does the logic build from Introduction through Conclusion?
• [ ] Read every word, caption, and abbreviation — detail pass
• [ ] Read as a naïve reader — where do you get confused?
• [ ] Read as a hostile reviewer — what would you attack?
• [ ] Verify all numbers in text match their corresponding tables and figures
• [ ] Have at least two co-authors proofread independently
• [ ] Assume your bibliography has errors — verify every citation

Detailed guidance: references/process.md

Quick Scan

Run the built-in scanner to catch mechanical anti-patterns (31 checks, section-aware):

# Full scan
python3 ~/.claude/skills/manuscript/scan-manuscript.py manuscript.md

# Errors only (high confidence)
python3 ~/.claude/skills/manuscript/scan-manuscript.py --severity error manuscript.md

# Check a single section from stdin
cat results.md | python3 ~/.claude/skills/manuscript/scan-manuscript.py --section Results

# JSON output / markdown checklist
python3 ~/.claude/skills/manuscript/scan-manuscript.py --json manuscript.md
python3 ~/.claude/skills/manuscript/scan-manuscript.py --checklist manuscript.md

# List all checks
python3 ~/.claude/skills/manuscript/scan-manuscript.py --list-checks

What it catches (~57% of this skill's scriptable guidance): hedge stacking, empty adjectives, interpretation in Results, textbook openings, vague aims, p-values without CIs, citation stacking (Introduction + Discussion), contractions, duplicate words, tautological acronyms (HIV virus), passive voice ratio, sentence monotony, table/figure narration, statistical Discussion openers, statistical conclusions, mechanical transitions, overclaiming, anthropomorphism, informal language, British/American spelling mix, nominalizations, wordy phrases, redundant modifiers, self-referential filler, sentence sprawl, double negatives, missing reporting guidelines, p-value ordering, monotonous results patterns.

What it cannot catch (~43%): argumentation quality, logical chains, gap specificity, interpretive framework depth, limitation balance. These require human judgment or AI-assisted review.

Related Skills

• /human-write — Scan for AI-flavored vocabulary
• /meta-manuscript-assembly — Assemble tables, figures, references for meta-analyses
• /scientific-figure-assembly — Create multi-panel publication figures
• /vale — Lint prose for style and grammar
• /strobe-check — Audit observational studies (cohort, case-control, cross-sectional) against STROBE
• /prisma-check — Audit systematic reviews and meta-analyses against PRISMA 2020
• /care-check — Audit case reports against CARE checklist
• /consort-check — Audit RCTs against CONSORT 2010
• /tripod-check — Audit prediction models and clinical AI against TRIPOD+AI