/scientific-writing

name: scientific-writing
description: Use when writing or revising scientific manuscripts, abstracts, figures, or references for journal submission and you need full-paragraph prose, scientific structure, citation-style guidance, or reporting-guideline support.

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`.

The job, dependencies and acceptance criteria of each manuscript section are defined once in `paper-workflow`'s `references/section-contracts.md`; this skill drafts to them. Abstract length and structure, and other formats, come from the target journal, not from a generic template.

For LaTeX equation numbering, figure placement, table pagination or page-break requests, read `references/latex-layout.md`. A typesetting-only task uses the existing prose, figures and numerical content; it does not require a reverse outline, claim rewrite or figure-generation pass. Respect protected passages and author metadata. If paragraph boundaries also need repair, use `write-scientific-manuscript` for their scientific meaning before checking the rendered layout.

Visual Enhancement with Scientific Figures

When a manuscript would benefit from a schematic, workflow diagram, or conceptual figure, use this repository's `nature-figure` skill, which ships an OpenRouter AI-schematic route. It is not in the default recommended set because it needs a plotting backend or an `OPENROUTER_API_KEY`; install it from the Figure Stack (see the installation docs).

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 the `nature-figure` skill's OpenRouter route to generate publication-style schematics.
• 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 (via the `nature-figure` skill, once installed):**

export OPENROUTER_API_KEY="sk-or-..."
python ~/.agents/skills/nature-figure/scripts/generate_openrouter_schematic.py \
  --title "Your method" \
  --panel-map "left: problem; center: proposed mechanism; right: validated outcome" \
  --outdir figures --basename schematic --resolution 2K
# Claude Code (global install): replace ~/.agents/skills with ~/.claude/skills
# Claude Code (project-local install): replace ~/.agents/skills with .claude/skills

Requires `OPENROUTER_API_KEY`. Iterate on the panel map and title until the layout is right, then treat the output as a draft: Nature Portfolio journals do not accept images made with generative AI, so the submitted figure is redrawn by hand or in code. See `nature-figure`'s `references/openrouter-image-generation.md` for full options.

**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 `nature-figure` skill.

---

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 with the brief interpretation each one needs; broader meaning waits for the Discussion
• **Discussion**: Interpret results, state the scope of the work once in a closing paragraph, propose future directions

For detailed guidance on IMRAD structure, refer to `references/imrad_structure.md`. It is a general primer acro