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: Numb