CommunityWriting & Editinggithub.com

report-drafting

Draft the content of technical and scientific reports - introduction, state of the art, methods/test setup, results, discussion, summary/conclusions, abstract, appendices - together with their figures, tables, PlantUML diagrams, charts, formulas, computations and citations, in AsciiDoc, LaTeX or plain prose. Use this whenever someone asks to write, draft, expand, or turn notes, data, measurements, code or bullet points into a section of a report, thesis, lab report, design report, project report or technical documentation; to create or improve a figure, diagram, chart, caption, table or evaluation/decision matrix for one; to set up equations or a load calculation; or to add citations and a reference list - even if they just say "write up these results".

What is report-drafting?

report-drafting is a Claude Code agent skill that draft the content of technical and scientific reports - introduction, state of the art, methods/test setup, results, discussion, summary/conclusions, abstract, appendices - together with their figures, tables, PlantUML diagrams, charts, formulas, computations and citations, in AsciiDoc, LaTeX or plain prose. Use this whenever someone asks to write, draft, expand, or turn notes, data, measurements, code or bullet points into a section of a report, thesis, lab report, design report, project report or technical documentation; to create or improve a figure, diagram, chart, caption, table or evaluation/decision matrix for one; to set up equations or a load calculation; or to add citations and a reference list - even if they just say "write up these results".

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/larsw/report-writing-skills/tree/HEAD/skills/report-drafting

Installed? Explore more Writing & Editing skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

Report drafting

A technical report must let a reader with general technical knowledge, but no knowledge of the project, understand exactly what the author meant without being able to ask. Every rule below follows from that. Three things must be clear in every section:

  1. the technical statement itself (facts, data, conclusions),
  2. what was already known and what is new,
  3. what the author did personally.

Method follows H. Hering, How to Write Technical and Scientific Reports (3rd ed., Springer 2025), Ch. 3.

Before writing

  • Rules first. Check for a template, house style, journal guidelines or a style sheet (style-sheet.adoc, see report-outline). Their conventions override the defaults here.
  • Work from the outline. If there is an outline or content map, draft against it. If there is none and the section is longer than a page, sketch its subsections first (or decide consciously that none are needed). For a whole report with no outline, use report-outline first.
  • Know the reader. Who reads this section, what do they already know, what will they do with it? Experts on a project routinely overestimate what readers know.

Never invent

Do not invent measurements, results, citations, part numbers, instrument data or sources. When information is missing, mark the gap so the author can search for it:

// ###Un: maximum deviation of the old sensor? (needed for the comparison)
The new sensor deviates from linearity by at most 3 %, the old one by at most +###+ %.
% ###Un: maximum deviation of the old sensor? (needed for the comparison)
The new sensor deviates from linearity by at most \qty{3}{\percent}, the old one by at most \#\#\#~\%.
  • Comment markers: ###Un (unknown fact or value), ###Lit (citation or bibliographic data missing), ###iS (introductory or connecting sentence still needed), ###Fig / ###Tab (planned figure or table).
  • A visible gap inside a sentence is written +###+ in AsciiDoc (a bare ### is highlight markup there) and \#\#\# in LaTeX (a bare # is an error).
  • Mark only what blocks the text: a value a sentence needs, a claim that needs a source, a decision that changes the content. Collect secondary missing details (inventory numbers, firmware versions, settings) in one ###Un comment block per section, or as empty cells in an equipment table, instead of dozens of inline gaps; a chapter riddled with markers is hard to read and to finish.
  • An unconfirmed fact that the text relies on (a configuration "to be checked", an assumed value) must be visibly marked in the rendered text too ("4s3p (to be confirmed)"), not only in a comment; otherwise the draft states a guess as fact.
  • Do not write a conclusion that depends on a missing value ("this meets the required accuracy of +###+ %"). Phrase it conditionally ("this meets a requirement of up to x % of span") or leave the conclusion as a marked gap.
  • Tell the user which gaps you left, grouped by what they need to look up.

How to write each part

Read references/sections.md for the recipe of the part you are drafting: abstract, introduction, state of the art, methods/test setup (with the reproducibility list), results, discussion, summary/conclusions, appendices, front matter. The essentials:

  • Introduction and summary are read first and by almost everyone. Write them with the most care. The introduction gives the starting situation, relevance, task/goal and the route through the report. The summary says what was asked, what was achieved, where the difficulties were, what was not done and why, and recaps the chapters in order.
  • Guide with words. Every chapter and section opens with a sentence that says what comes and why, and ends (where useful) with a sentence that says what it means or leads to the next part. A heading is never followed directly by a figure, table, list or citation.
  • The heading is not part of the text. The first sentence must make sense without the heading ("The measuring devices were calibrated with …", not "…was done with …").
  • One name per thing. The same part, process or quantity always gets the same term; synonyms make readers think a different thing is meant. Name parts by their function ("retaining plate", "input gear", "carrying frame"), not generically ("plate", "gear", "the design", "variant 1"). With an assembly drawing, add the position number at first mention: "cover plate (23)".
  • Numbers instead of adjectives. "much more linear" becomes "max. 3 % deviation instead of 7.6 %". If the number does not matter, drop the adjective.
  • Plain sentences. At most about 25–30 words, one new fact per sentence, at most six sentences per paragraph, subject and verb early, explicit connectives ("therefore", "because", "if … then"). report-copyedit has the full rule set; follow it while drafting so the copyedit pass stays light.
  • Voice. Follow the venue. Traditional engineering reports are impersonal (passive, "we" only for the team in the summary); most journals now prefer active voice and "we". Either way, the actor must be unambiguous: "by the operator" vs "by the controller".
  • Tense. Present tense for facts and for what the report shows; past tense for what was done in the experiments.
  • Cite as you write: every statement, value, figure or table taken from elsewhere gets its citation now, not later. See references/citations.md.
  • Reproducibility. Methods and test sections must let someone repeat the work and get the same result (equipment, settings, specimens, instruments, formulas with sources). See references/sections.md.
  • Overview in figures, detail in text. Plan for each important statement whether it is shown, written, or both. Make figures and tables while writing the text, not at the end; late figures look rushed.

Figures, diagrams and charts

Read references/figures.md before creating or revising any figure, PlantUML diagram or chart. Core rules:

  • Caption below the figure; it says what is shown, where, and under which conditions ("Pressure measuring points P in the cooling channel of the die-casting mould", not "Measuring points"). Borrowed figures carry the source in the caption.
  • Every figure gets an anchor ID and at least one cross-reference in the text, placed before or next to it, and the text says what the reader should see in it.
  • Didactic reduction: show only what supports the statement, at most about 4–7 main elements; one visual encoding (arrow style, colour) = one meaning, explained in a legend.
  • Chart axes carry quantity and unit ("Force in N" or "Force / N", never "Force [N]"), values increase up and to the right, time runs left to right, linear scales include zero, and nothing is stretched to exaggerate.
  • Readable when printed in greyscale and for colour-blind readers: never rely on colour alone.

Tables

Read references/tables.md for tables, evaluation (weighted scoring) tables and morphological boxes. Core rules: caption above the table; header row and first column understandable without the text; units in the header, not in every cell; every table referenced in the text; large number tables go to the appendix with a chart in the text. In evaluation tables, all points are benefit points from the user's perspective (more cost or weight gets fewer points), every table has its own legend, and the winner is stated explicitly.

Formulas, units and computations

Read references/formulas-units.md for equations, computations and notation. Core rules: symbols italic, units upright, a space between number and unit (5 mm, 20 °C), every symbol explained right before or after the formula or in a legend below it; computations go formula → substituted values → result → selection statement ("selected: bearing 6305, C = 25 kN > C_req = 23.8 kN").

Markup: AsciiDoc or LaTeX

Write in the markup the report already uses, and keep the project's conventions (class, preamble, macros, one sentence per line) unless asked otherwise.

  • AsciiDoc: references/asciidoc.md has the patterns for captions, IDs, cross-references, PlantUML blocks, stem equations, bibliographies, footnotes, admonitions and includes. Use <<id>> cross-references and explicit IDs ([#fig-…], [#tab-…], [#eq-…], [#sec-…]).
  • LaTeX: references/latex.md has the patterns for figures, tables (booktabs, siunitx columns), equations, siunitx units, biblatex citations, cleveref references, glossaries, PlantUML and pgfplots. In floats the order is graphic → \caption → \label for figures and \caption → \label → tabular for tables; units always through siunitx (\qty{5}{\milli\metre}); references through \cref (or Figure~\ref).

Never hard-code numbers such as "Figure 3" or "Sect. 2.1"; let the markup generate them.

After drafting a section

Check before handing it over:

  • Opening sentence under every heading; nothing (figure, table, list, citation) directly after a heading
  • Every figure/table: caption in the right place, ID, referenced and interpreted in the text, source if borrowed
  • Every borrowed statement, value, figure and table cited; every citation resolvable
  • Terms match the style sheet / earlier chapters; abbreviations defined at first use
  • No vague comparatives where a number exists; no invented facts; gaps marked with ###
  • Numbers and units in the right notation; symbols explained
  • Section delivers what the outline's content map promised

If the report-review skill is installed alongside this one, its linter (../report-review/scripts/lint_report.py <master.adoc|main.tex>, relative to this skill's directory) checks captions and their position, labels/IDs, cross-references, citations, lone subsections and number–unit spacing mechanically, for AsciiDoc and LaTeX.

Finish by telling the user what you drafted, which ### gaps remain, and any assumption you made about voice, terminology or notation.

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

report-copyedit

Copyedit and line-edit technical and scientific writing (reports, theses, lab reports, papers, specifications, design docs, technical documentation) for clarity, precision, consistent terminology and correct notation, without changing the technical content. Use this whenever someone asks to copyedit, proofread, line-edit, tighten, simplify, polish the language of, improve the readability or flow of, or "fix the English in" a technical text, AsciiDoc, LaTeX or Markdown file; to make terms, units, abbreviations, hyphenation or capitalization consistent; or to build a style sheet from an existing draft. For a whole-document pre-submission review (structure, figures, references, checklist) use report-review instead.

report-outline

Plan a technical or scientific report before and while drafting it - analyze the assignment, write and test title variants, condense the core message into one sentence, grow a 4-point then 10-point then detailed outline, pick a structure pattern for the report type (lab/test report, design report, project report, thesis, manual, research paper), and set up a style sheet and an AsciiDoc or LaTeX skeleton. Use this whenever someone is starting or reorganizing a report, thesis, lab report, design report, project report or technical documentation and asks for an outline, structure, table of contents, chapter plan, section order, working title or title ideas, or asks "how should I organize this?" - and also to check an existing outline or ToC for logic (lone subsections, unequal siblings, vague headings).

report-presentation

Turn a technical report, thesis or project into a talk and slide deck, review and polish existing slides or a talk script, and prepare rehearsal, delivery and Q&A - including thesis defenses, project status talks, conference talks and 3-10 minute short statements. Builds decks in asciidoctor-reveal.js (AsciiDoc) or LaTeX Beamer with PlantUML diagrams and speaker notes, and checks them with a deck statistics script. Use this whenever someone asks to make slides, a deck, a presentation or a talk from a report or results, to review, critique or improve slides or speaker notes, to fit a talk into N minutes, to plan a defense or a status update, or to prepare for questions after a talk.

report-review

Review a technical or scientific report, thesis, lab report, design report or technical document as a whole before submission or release - structure and logic, completeness, clarity for a reader without project knowledge, figures and tables, citations and reference list, formulas and notation, terminology consistency, cross-references, open TODO markers and output quality - using a mechanical AsciiDoc/LaTeX linter plus a checklist, and produce a prioritized findings report with concrete fixes. Use this whenever someone asks to review, check, audit, assess, give feedback on, "look over", or do a final/pre-submission/QA pass on a report or thesis (AsciiDoc, LaTeX, Markdown, PDF or Word), asks "is this ready to hand in?", or wants supervisor-style feedback on a draft chapter.

Related Skills