Communityライティング&編集github.com

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-outline とは?

report-outline is a Claude Code agent skill that 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).

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/larsw/report-writing-skills/tree/HEAD/skills/report-outline

Installed? Explore more ライティング&編集 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Report outline

The outline is the backbone of a technical report. Writing the text is craft; deciding what goes in which "drawer", and in which order, is the creative part, and it decides whether the report has an inner logic a reader can follow. A reader with basic technical knowledge but no knowledge of the project must be able to understand the finished report without asking the author anything. Every step below serves that reader.

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

0. Find the governing rules first

Before proposing anything, find out whether the university, company, customer or journal prescribes a structure, template, page limit, cover/title page, citation style or numbering scheme. Look in the repo (templates, *.adoc skeletons, README, a style guide) and ask the user if nothing turns up. Their rules win over everything in this skill; the defaults here fill the gaps.

1. Analyze the task

Write a short task card (in the conversation or in notes/task.adoc, as the user prefers). Answer from what the user gave you; mark the gaps and ask about the ones that change the outline.

  • What exactly is the task, and who set it (supervisor, customer, team, self)?
  • What must the report contain? List mandatory content.
  • Who reads it, what do they already know, what do they expect? Who decides (grader, customer, reviewer)?
  • Why is it written: to document, to decide, to prove, to teach, to be graded?
  • Which media and formats (AsciiDoc or LaTeX to HTML/PDF, slides later)?
  • Which work steps, help (people, equipment, literature) and deadlines? Which are time-critical?
  • Does the task statement already contain a usable title?

Time planning when the user asks for it: estimate realistically, then double it; start writing no later than one third into the project; budget about 1 day for title and outline, about 3 pages of text per day, and 1–2 weeks for corrections, final check and delivery.

2. Title

The same requirements apply to the title, every heading, and every figure and table title:

  • contains the main keywords (people find reports through database search)
  • short, precise, true; promises nothing the report does not deliver and triggers no wrong associations
  • concrete enough to create interest; reads well aloud
  • secondary aspects go into a subtitle (Main title: subtitle or Main title - subtitle)

Method: write down the task, list the keywords, combine them into 5–8 variants, read them aloud, pick one and say why. If a self-coined term or acronym is central to the work, it belongs in the title. Weak patterns to avoid: "Contribution to …", "Investigation of some aspects of …", titles that drop the core topic. A working title is fine early on; settle the final one with the supervisor or customer.

3. Core message, 4-point and 10-point structure

Build the outline top-down so the logic fixed early cannot get lost when sections are later added or split.

  1. Core message: one sentence stating the main topic, target or result of the report. Insist on one sentence even when it is hard; that difficulty is the point.
  2. 4-point structure: split the core message into 3–4 main items (e.g. "State of the art - test rig design - test execution - test results").
  3. 10-point structure: expand into 8–10 chapters. Pick one ordering principle per level and apply it consistently: time sequence, starting conditions, project targets, alternatives, components/assemblies, input to output, direction of force, direction of flow (data, energy, material), improvement steps, related topics.
  4. Detailed structure: subdivide the large chapters. Before writing a chapter, sketch its subsections or decide consciously that it needs none. The detailed outline keeps growing while the text is written.
  5. Last check (when the report is done): numbers and wording of the outline/ToC match the headings in the text exactly.

Use the conventional chapter names the target readers expect (a lab report reader looks for "Test setup", "Test procedure", "Results"). For common report types, start from a pattern in references/structure-patterns.md and adapt it rather than inventing from scratch; a pattern lets you skip steps 2–3. If the supervisor publishes a pattern, theirs wins.

4. Rules every outline must pass

Check these on every outline you produce or review, and say which rule a change fixes.

Line of argument (check this first; it is what supervisors usually mean by "lacks logic")

  • The introduction states a goal or research question, and the conclusion chapter answers exactly that.
  • The order follows the work: problem → background → requirements → concept/design → implementation or experiment → evaluation method → results → discussion → conclusions. Evaluation criteria and method come before results; a design decision is justified where it is made, not in a later chapter.
  • Requirements defined early are checked again in the evaluation.
  • Background covers what the reader needs for this work, not a catalogue of every tool used.

Logic of the headings

  • A subdivision needs at least two parts. A 2.1 without a 2.2 is illogical: merge it into the parent or add a sibling.
  • Headings at one level are of equal weight and form a consistent sequence. If "technical evaluation" is a subsection, "economic evaluation" cannot be a sibling chapter.
  • Each heading stands on its own and says what the part contains. One-word headings ("Conditions", "Description", "Test rig") usually need sharpening ("Calibrating the measuring devices"); standard names (Introduction, Summary, References, Appendix) are fine.
  • Siblings share a grammatical pattern where it helps (all "Preparing …", "Calibrating …", "Mounting …").
  • The heading is not part of the text: the first sentence under it must be a complete sentence that would make sense without the heading.

Form (ISO 2145 numbering, the default when the venue sets nothing)

  • Arabic numerals, a point between levels, no point after the last number: "2.1 Test setup", not "2.1. Test setup". LaTeX numbers this way by default; Asciidoctor's built-in :sectnums: prints "2.1." - accept it rather than hand-typing numbers.
  • Prefer at most 3 numbered levels and at most 9 siblings under one parent; deeper detail becomes unnumbered run-in headings (AsciiDoc .Title block titles, LaTeX \paragraph{}, or bold lead-ins) that stay out of the ToC.
  • Chapter 0 may hold a preface; n.0 may hold a chapter introduction.
  • No punctuation at the end of headings, no full sentences, no citations, no ALL CAPS.
  • Abstract, preface, ToC, task statement and declarations get headings but no numbers. The reference list gets a chapter number; appendices get letters (A, B, …). One "Appendix" chapter with A.1, A.2 … usually reads better than many lettered appendices.

Order of parts (ISO 7144, adapt to the institution): cover/title page → (task statement, declaration of authorship, acknowledgements) → abstract → preface → contents → lists of figures/tables/abbreviations/symbols → chapters 1…n → references → appendices → index. Introduction is the first chapter, summary/conclusions the last text chapter. Figures and tables belong next to the text that discusses them, not in an appendix; only bulky material (protocols, drawings, raw data, large tables) goes there.

5. Map content to the outline

For each section of the detailed outline, write one line on what it must deliver (claim, data, figure, table, source). Check that every important statement will have a visualization (figure, table, equation) or at least a list, and that nothing in the outline is there only because material happened to be available. For reports over about 20 pages, collect material per chapter. This content map is what report-drafting works from.

6. Style sheet

For anything longer than a few pages, or written by more than one person, start a style sheet now; consistency problems are cheap to prevent and expensive to fix. Use references/style-sheet-template.adoc as the starting point and fill in what is already decided (terms, spellings, units, numbering, citation style). In teams, agree the outline (finer than 10 points), the style sheet and the toolchain before anyone writes, and announce outline changes immediately.

7. Document skeleton (AsciiDoc or LaTeX)

If the user wants files, generate a skeleton in their markup. Use the project's existing template or class if there is one.

  • AsciiDoc: references/asciidoc-skeleton.md: a master document with the header attributes and one include file per chapter (01-introduction.adoc, …), blank lines between the includes.
  • LaTeX: references/latex-skeleton.md: main.tex with the preamble (siunitx, caption, biblatex, cleveref, glossaries) and one \included file per chapter (chapters/01-introduction.tex, …).

Each chapter file holds its heading, its subsection headings with labels/IDs, and a one-line comment per section from the content map. Do not invent body text in a skeleton.

Output

Unless the user asks for only one piece, deliver in this order:

  1. Task card with open questions (short)
  2. Title variants with a recommendation
  3. Core message (one sentence)
  4. 4-point and 10-point structure, then the detailed outline with the one-line content map
  5. Notes on which pattern or ordering principle you used, and any rule from section 4 you had to apply
  6. Style sheet stub and AsciiDoc or LaTeX skeleton, if relevant

When reviewing an existing outline instead, list each problem with the rule it breaks and a concrete fix (rewritten heading or re-nesting), then show the corrected outline. If the report-review skill is installed alongside this one, its linter (python3 ../report-review/scripts/lint_report.py <master.adoc|main.tex>, relative to this skill's directory) catches lone subsections, level skips, hand-typed numbers and heading punctuation mechanically.

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

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.

関連スキル