chanw-research/claude-code-paper-writing/scientific-writing

Scientific Writing

Overview

This is the core journal-writing skill in this repository. Use it to turn a stable scientific story into clear, well-structured manuscript prose while keeping citations, figures, and reporting standards aligned.

Scientific writing is a process for communicating research with precision and clarity. Write manuscripts using IMRAD structure, citations (APA/AMA/Vancouver), figures/tables, and reporting guidelines (CONSORT/STROBE/PRISMA). Apply this skill for research papers and journal submissions.

Critical Principle: Always write in full paragraphs with flowing prose. Never submit bullet points in the final manuscript. Use a two-stage process: first create section outlines with key points from verified notes, literature, and results, then convert those outlines into complete paragraphs.

For revision-heavy journal manuscripts, do not jump from stale prose directly to polishing. First stabilize the section with a reverse outline and a claim-evidence map, then rewrite the paragraphs.

When to Use This Skill

This skill should be used when:

• Writing or revising any section of a scientific manuscript (abstract, introduction, methods, results, discussion)
• Structuring a research paper using IMRAD or other standard formats
• Formatting citations and references in specific styles (APA, AMA, Vancouver, Chicago, IEEE)
• Creating, formatting, or improving figures, tables, and data visualizations
• Applying study-specific reporting guidelines (CONSORT for trials, STROBE for observational studies, PRISMA for reviews)
• Drafting abstracts that meet journal requirements (structured or unstructured)
• Preparing manuscripts for submission to specific journals
• Improving writing clarity, conciseness, and precision
• Ensuring proper use of field-specific terminology and nomenclature
• Addressing reviewer comments and revising manuscripts

For title, abstract, cover-letter, or top-level logic decisions, read references/editor-first-impression.md.

Visual Enhancement with Scientific Figures

When a manuscript would benefit from a schematic, workflow diagram, or conceptual figure, use an installed figure-generation skill if one is available, such as inno-figure-gen. This repository does not ship that optional skill in the default install set.

Before finalizing any document:

1. Add at least one figure when it materially improves comprehension.
2. Prefer 2-3 figures for longer papers (methods flowchart, results visualization, conceptual diagram).

How to generate figures:

• Use an installed figure-generation skill such as inno-figure-gen to generate publication-style diagrams.
• Write prompts that specify academic style, white background, clean labels, colorblind-friendly colors, and high contrast.
• Save outputs under a local figures/ directory in the current project.

Example command when `inno-figure-gen` is installed:

uv run ~/.codex/skills/inno-figure-gen/scripts/generate_image.py \
  --prompt "Publication-style scientific schematic of your method; white background; clean labels; colorblind-friendly palette; high contrast" \
  --filename "figures/output.png" \
  --resolution 2K
# Claude Code (global install): replace ~/.codex/skills with ~/.claude/skills
# Claude Code (project-local install): replace ~/.codex/skills with .claude/skills

Requires GEMINI_API_KEY or an explicit --api-key. Iterate on the prompt until the figure is publication-ready.

When to add figures:

• Study design and methodology flowcharts (CONSORT, PRISMA, STROBE)
• Conceptual framework diagrams
• Experimental workflow illustrations
• Data analysis pipeline diagrams
• Biological pathway or mechanism diagrams
• System architecture visualizations
• Any complex concept that benefits from visualization

For detailed guidance on creating figures, refer to the figure-generation skill you have installed.

Core Capabilities

1. Manuscript Structure and Organization

IMRAD Format: Guide papers through the standard Introduction, Methods, Results, And Discussion structure used across most scientific disciplines. This includes:

• Introduction: Establish research context, identify gaps, state objectives
• Methods: Detail study design, populations, procedures, and analysis approaches
• Results: Present findings objectively without interpretation
• Discussion: Interpret results, acknowledge limitations, propose future directions

For detailed guidance on IMRAD structure, refer to references/imrad_structure.md.

Alternative Structures: Support discipline-specific formats including:

• Review articles (narrative, systematic, scoping)
• Case reports and case series
• Meta-analyses and pooled analyses
• Theoretical/modeling papers
• Methods papers and protocols

2. Section-Specific Writing Guidance

Editor-First Front Door: Make the title, abstract, introduction, Results, discussion, and cover letter answer the same four questions in the same order:

• why did the study need to be done
• what did you do
• what did you find
• how does the study advance the field

If these sections answer different versions of the story, the manuscript will feel fragmented even when the prose is locally strong.

Abstract Composition: Craft concise, standalone summaries (100-250 words) that capture the paper's purpose, methods, results, and conclusions. Support both structured abstracts (with labeled sections) and unstructured single-paragraph formats. Make the abstract state the problem, the aim/method, the key result, and the implication. Do not spend most of the space on generic background or report only that results were significant.

Title and Cover Letter: Make the title a concise summary of the main contribution, ideally about 20 words or fewer. Prefer concrete keywords, avoid question-form titles, avoid unnecessary abbreviations, and avoid making the method the title unless the method itself is the main contribution. Make the cover letter about one page, state significance, journal fit, readership fit, and one or two key findings, and do not turn it into a second abstract or a full result list.

Top-Level Logic: Keep one visible chain across the manuscript:

• topic
• published work
• unresolved problem
• objective
• methodology
• results and figures
• summary of findings
• interpretation
• implication for the field

Introduction Development: Build compelling introductions that:

• Establish the research problem's importance
• Review relevant literature systematically
• Identify knowledge gaps or controversies
• State clear research questions or hypotheses
• Explain the study's novelty and significance

Methods Documentation: Ensure reproducibility through:

• Detailed participant/sample descriptions
• Clear procedural documentation
• Statistical methods with justification
• Equipment and materials specifications
• Ethical approval and consent statements

Results Presentation: Present findings with:

• Logical flow from primary to secondary outcomes
• Integration with figures and tables
• Statistical significance with effect sizes
• Objective reporting without interpretation

Discussion Construction: Synthesize findings by:

• Relating results to research questions
• Comparing with existing literature
• Acknowledging limitations honestly
• Proposing mechanistic explanations
• Suggesting practical implications and future research

3. Citation and Reference Management

Apply citation styles correctly across disciplines. For comprehensive style guides, refer to references/citation_styles.md.

Major Citation Styles:

• AMA (American Medical Association): Numbered superscript citations, common in medicine
• Vancouver: Numbered citations in square brackets, biomedical standard
• APA (American Psychological Association): Author-date in-text citations, common in social sciences
• Chicago: Notes-bibliography or author-date, humanities and sciences
• IEEE: Numbered square brackets, engineering and computer science

Best Practices:

• Cite primary sources when possible
• Include recent literature (last 5-10 years for active fields)
• Balance citation distribution across introduction and discussion
• Verify all citations against original sources
• Use reference management software (Zotero, Mendeley, EndNote)

4. Figures and Tables

Create effective data visualizations that enhance comprehension. For detailed best practices, refer to references/figures_tables.md.

When to Use Tables vs. Figures:

• Tables: Precise numerical data, complex datasets, multiple variables requiring exact values
• Figures: Trends, patterns, relationships, comparisons best understood visually

Design Principles:

• Make each table/figure self-explanatory with complete captions
• Use consistent formatting and terminology across all display items
• Label all axes, columns, and rows with units
• Include sample sizes (n) and statistical annotations
• Follow the "one table/figure per 1000 words" guideline
• Avoid duplicating information between text, tables, and figures

Common Figure Types:

• Bar graphs: Comparing discrete categories
• Line graphs: Showing trends over time
• Scatterplots: Displaying correlations
• Box plots: Showing distributions and outliers
• Heatmaps: Visualizing matrices and patterns

5. Reporting Guidelines by Study Type

Ensure completeness and transparency by following established reporting standards. For comprehensive guideline details, refer to references/reporting_guidelines.md.

Key Guidelines:

• CONSORT: Randomized controlled trials
• STROBE: Observational studies (cohort, case-control, cross-sectional)
• PRISMA: Systematic reviews and meta-analyses
• STARD: Diagnostic accuracy studies
• TRIPOD: Prediction model studies
• ARRIVE: Animal research
• CARE: Case reports
• SQUIRE: Quality improvement studies
• SPIRIT: Study protocols for clinical trials
• CHEERS: Economic evaluations

Each guideline provides checklists ensuring all critical methodological elements are reported.

6. Writing Principles and Style

Apply fundamental scientific writing principles. For detailed guidance, refer to references/writing_principles.md.

Clarity:

• Use precise, unambiguous language
• Define technical terms and abbreviations at first use
• Maintain logical flow within and between paragraphs
• Use active voice when appropriate for clarity

Conciseness:

• Eliminate redundant words and phrases
• Favor shorter sentences (15-20 words average)
• Remove unnecessary qualifiers
• Respect word limits strictly

Accuracy:

• Report exact values with appropriate precision
• Use consistent terminology throughout
• Distinguish between observations and interpretations
• Acknowledge uncertainty appropriately

Objectivity:

• Present results without bias
• Avoid overstating findings or implications
• Acknowledge conflicting evidence
• Maintain professional, neutral tone

7. Writing Process: From Outline to Full Paragraphs

CRITICAL: Always write in full paragraphs, never submit bullet points in scientific papers.

Scientific papers must be written in complete, flowing prose. Use this two-stage approach for effective writing:

Stage 1: Create Section Outlines with Key Points

When starting a new section:

1. Gather the relevant literature and data from verified local notes, trusted web sources, or an installed literature-search skill
2. Create a structured outline with bullet points marking:

• Main arguments or findings to present
• Key studies to cite
• Data points and statistics to include
• Logical flow and organization

1. These bullet points serve as scaffolding—they are NOT the final manuscript