how-to-technical-writing

Installed resources

Keep the working directory at the user's project. Resolve this SKILL.md with Path(path).resolve() to follow symlinks. Bare helpers/, references/, and template paths are relative to that real directory. skills/<name>/... refers to the installed skill found by public name in the agent's catalog, not the user's project. Dependencies need not be siblings; report and install missing skills before the dependent step. Shared writing files are bundled in how-to-write-ideas-report/references/.

Writing style guide

These sentence and paragraph rules guide write-paper drafts, review-paper findings and proposed fixes, and how-to-write-ideas-report and survey report prose.

Related resources:

• Checkable form of these rules: checklist.md.
• Notation Rulebook and Figure Rulebook: skills/write-paper/SKILL.md.
• Reasons behind every rule: skills/write-paper/references.md.
• Model paper: skills/write-paper/sources/1807.01815_Ho2019_quantum-scars.md.

The rules come from Martinis, von Delft, and a language-polish checklist for teaching material. The guardrails prevent mechanical edits from changing manuscript content.

Rules

Clarity outranks these rules. When they conflict, keep the clearer sentence.

Conceptual clarity and semantic coherence

• Explain concepts with existing concepts. Do not use concepts never explained, or that are not a common sense to explain a new idea.
• Define at the point of need. Introduce a term or symbol only when the argument needs it. Every definition is used later in the paper.
• Set up before calculating. Before a derivation, state the system, the assumptions or boundary conditions, the symbols, and the quantity being computed. Use a labelled setup figure when geometry matters.
• One job per paragraph. Each paragraph has its own mission. Start with a topic sentence, support it with detail, and end with a transition or emphasis. Do not mix different jobs in the same paragraph.
• Locality rule. Keep each paragraph on one object and each section on its job. Avoid connecting to concepts not within current scope, previewing later sections, or adding unused interpretations. Keep cross-references only when the current step depends on them, and say why: "by the linearity of Eq. (3)". In paper writing, abstracts, introduction, and conclusions are exempt.
• Do not repeat yourself. Cut sentences that do not carry new information or new examples. A second appearance of a fact is a pointer, never a restatement. A number, count, or list stated in two places can drift, so state it once and point to it.
• The delete test. A sentence stays only if removing it leaves a gap that something later in the section depends on. Run the test against the whole section, not the next sentence, so a setup for a later payoff survives.
• Trust the structure. Do not re-describe in words what an equation, table, or figure already shows. At most one clause points at what to look at. The text says what a feature means, not what shape it has.
• Pay every promise. Every "we will show", "surprisingly", or "the key link" has a later line that pays it with a result, theorem, or figure. A promise paid only by a hint is cut or paid.