Skip to content
Back to search

paper-writing

"Research paper writing assistant that enforces the SNL lab's editorial principles and voice profile (customizable) and a staged writing workflow. MANDATORY TRIGGERS: Use this skill whenever the user mentions writing a paper, drafting a section, revising a section, editing a paper, reviewing a draft, rewriting an introduction, writing an evaluation, polishing prose, compressing text, or any task involving .tex files, Overleaf, conference submissions, or paper deadlines. Also trigger when the user names their paper in a writing context. This skill should activate for ANY research writing task — sections, abstracts, rebuttals, camera-ready edits, cover letters, or response to reviewers."

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/snl-ucsb--paper-writing-skill/badge.svg)](/listings/snl-ucsb--paper-writing-skill)

HTML

<a href="/listings/snl-ucsb--paper-writing-skill"><img src="/api/listings/snl-ucsb--paper-writing-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/SNL-UCSB/paper-writing-skill.git
cd paper-writing-skill
./setup            # installs to ~/.claude/skills/paper-writing/

Then, in your paper's directory: run `claude`, and type `/paper-writing`. If a `project_context.md` exists, Claude loads it and continues; if not, it runs a structured brainstorming session (34 questions across 6 phases) to create one.

Requires Claude Code installed and signed in (https://docs.claude.com).

**New to the skill? Read [USAGE.md](USAGE.md)**: your first session, which mode for which situation, where outputs land, how to iterate, and how to keep unpublished work private.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 376 lines
  1. ---
  2. name: paper-writing
  3. description: "Research paper writing assistant that enforces the SNL lab's editorial principles and voice profile (customizable) and a staged writing workflow. MANDATORY TRIGGERS: Use this skill whenever the user mentions writing a paper, drafting a section, revising a section, editing a paper, reviewing a draft, rewriting an introduction, writing an evaluation, polishing prose, compressing text, or any task involving .tex files, Overleaf, conference submissions, or paper deadlines. Also trigger when the user names their paper in a writing context. This skill should activate for ANY research writing task — sections, abstracts, rebuttals, camera-ready edits, cover letters, or response to reviewers."
  4. ---
  5. # Paper Writing Skill
  6. ## How This Skill Works
  7. This skill encodes the writing methodology of the [Systems and Networking Lab (SNL)](https://github.com/SNL-UCSB) at UC Santa Barbara, derived from forensic analysis of 6 papers (8 submissions), 7,600+ Overleaf edits, 100+ tex file versions, and 5 peer review processes. See [*The Paper Behind the Paper*](https://sites.cs.ucsb.edu/~arpitgupta/blog/the-paper-behind-the-paper.html) for the full analysis. It works out of the box — the default rules are calibrated and battle-tested.
  8. ### Three Layers
  9. 1. **The pipeline (fixed)**: A five-stage writing workflow. Does not change between users or papers.
  10. 2. **The voice and editorial rules (defaults provided, customizable)**: Sentence-level style, structural rules, compression patterns, section checklists. These ship with the SNL lab's rules as defaults. Students may customize by editing files in `author_profile/` — see the README for what to change.
  11. 3. **The project context (per paper)**: Identity sentence, venue, contribution claims, locked decisions. Lives in a `project_context.md` in the paper's working directory.
  12. ### How This Skill Connects to the Research Pipeline
  13. This skill does not operate in isolation. It is part of a three-skill family, and the artifacts from the other two skills are direct inputs to the writing process:
  14. **From the [literature-survey-skill](https://github.com/SNL-UCSB/literature-survey-skill):**
  15. - **Gap analysis** → feeds Brainstorming Phase 1 (Problem Discovery). The gaps the survey identified — missing quadrants, shared assumptions that break, unexplored combinations — are the structural limitations that motivate your paper.
  16. - **Writing craft extractions** (Pass 3+) → feed the Architecture stage and section drafting. The introduction anatomy, evaluation architecture, and design craft you extracted from the best papers in your area are the models for your own paper's structure.
  17. - **Competitive positioning** → feeds Brainstorming Phase 4. The invariant matrix and dependency graph from synthesis show exactly where your paper sits relative to existing work.
  18. **From the [data-visualization-skill](https://github.com/SNL-UCSB/data-visualization-skill):**
  19. - **Exploration** (`exploration_log.md`) → feeds Brainstorming Phase 3 (Evaluation Design). The exploration forced you to look at your data from multiple angles before forming hypotheses. The surprises you found — distributions you didn't expect, subgroups that behaved differently — shape what claims are defensible and where the real contribution lives.
  20. - **Brainstorm** (`braindump.md`) → feeds the figure/table plan. Each braindump articulates what question a figure answers, what you expected to see, and what would surprise you. These are the hypotheses your evaluation must validate.
  21. - **Plan + Execute** (`plot_context.md`) → feeds the Architecture stage's figure/table plan. Each plot_context records intent, variable mappings, plot type rationale, and design decisions — ready-made entries for the paper's figure plan.
  22. - **Analyze** (WALTER narrations) → feeds Evaluation Move 4 (Takeaway Synthesis). The WALTER Result — "what is the takeaway? does it connect back to the hypothesis?" — is a first draft of the Takeaway paragraph for that experiment cluster.
  23. The three skills create a closed loop: the literature survey reveals the gap and teaches you how accepted papers communicate; data visualization forces you to understand what your evidence actually shows and what hypotheses it validates; paper writing turns both into a publishable argument. **If the student has artifacts from the other skills, Claude MUST load them.**
  24. ### When This Skill Triggers, Claude MUST:
  25. 1. Read this SKILL.md (already loaded)
  26. 2. Read ALL files in `author_profile/` — these are the source of truth for editorial rules
  27. 3. Ask which paper the user is working on
  28. 4. Look for a `project_context.md` in the paper's working directory
  29. 5. If found, read it and treat it as binding constraints
  30. 6. If not found, decide how to create one: if the ideas already exist in notes, drafts, code and related work, run **Story Mode** (`story_mode.md`); if they are mostly in the user's head, run **Structured Brainstorming** below
  31. 7. Check for artifacts from sibling skills — survey paper notes with craft extractions, `exploration_log.md`, `braindump.md`, `plot_context.md`, WALTER narrations. If found, load them as reference material for the relevant pipeline stages
  32. 8. Check for a **private overlay skill**: an installed skill whose name ends in `paper-writing-lab` (for example `~/.claude/skills/paper-writing-lab/` or `~/.claude/skills/<group>-paper-writing-lab/`). If present, read it: it carries a group's real worked cases, house rules and project records that cannot live in this public skill. Its project-specific guidance takes precedence over the defaults here; never copy its contents into this repository
  33. ---
  34. ## Story Mode — From a Group's Ideas to a Paper Story and Outline
  35. When the ideas for a paper are scattered across meeting notes, drafts, code, chat threads and related work, read `story_mode.md` and follow its ten steps (or its short path for workshop papers and short deadlines): read the whole record, connect the dots without inventing anything, place the idea in its intellectual history, read the closest work in depth, decide one core contribution, choose one framing, write a Draft 0 introduction with the motivation and skeleton, tie each claim to an evaluation question that could refute it, converge with review rounds and a calibration spec, and fill `project_context.md` so Stage 2 starts from the result. Co-authors read the result as one **story document** built from `story_document.md`: front matter, the paper's sections in order, a problem specification, anecdotes before trends, an evaluation plan that separates data available from data needed, and a figure for every main point. Triggers: "turn our notes into a <venue> outline", "what is the story for <venue>", "connect the dots", `/paper-writing story`.
  36. ---
  37. ## Structured Brainstorming — The Skill's Centerpiece
  38. **The biggest obstacle for students isn't writing — it's that their ideas live as unstructured intuitions.** They know something is interesting but can't articulate what or why. The brainstorming process transforms scattered thinking into a precise project context that drives every section of the paper.
  39. ### How It Works
  40. Claude MUST read `brainstorming_guide.md` and walk the student through its 6 phases interactively. The phases are:
  41. | Phase | Focus | Key outcome |
  42. |-------|-------|-------------|
  43. | 1. Problem Discovery | Who suffers, what breaks, why it breaks structurally | The opening paragraph's stakes and the Problem Gap |
  44. | 2. Contribution Crystallization | Core claim, headline number, key abstraction name | The identity sentence and contribution list |
  45. | 3. Evaluation Design | Baselines, metrics, datasets, experiment-to-claim mapping | The evaluation plan that constrains what the introduction can promise |
  46. | 4. Positioning and Framing | Venue fit, competitive positioning, category creation vs. competition | The Related Work positioning sentence |
  47. | 5. Architecture and Constraints | Design pipeline, locked decisions, open questions | The Design section's structure and the project's scope |
  48. | 6. Narrative Spine | Story arc, the "inevitable" moment, the tweet-length pitch | The thread connecting every section |
  49. ### Rules for Running Brainstorming
  50. - **Go phase by phase.** Don't skip ahead. Phase 1 (the problem) must be clear before Phase 2 (the contribution) makes sense.
  51. - **"I don't know" is a valid answer.** Flag it as an open question and move on. Gaps discovered now are cheap to fix; gaps discovered during review are expensive.
  52. - **Push back on vague answers.** "It's faster" → "Faster for whom? By how much? On what workload?" Every answer should be specific enough to appear in the paper.
  53. - **Distinguish structural from quantitative.** "Existing tools aren't accurate enough" is quantitative — it motivates more experiments. "Existing tools assume stationarity, which fails on non-stationary workloads" is structural — it motivates a new approach. Papers need structural gaps.
  54. - **After all phases, generate `project_context.md`** using the template in `examples/project_context.md`. See `examples/example_project_context.md` for a synthetic example of what a complete project context looks like.
  55. ---
  56. ## Voice and Editorial Rules
  57. Claude MUST read these files from this skill's directory. They contain the detailed rules with examples.
  58. | File | What it controls |
  59. |---|---|
  60. | `author_profile/editorial_principles.md` | 14 cross-paper principles with evidence (introduction-twice, named-over-vague, what→why→so-what headings, compress-after-expanding, etc.) |
  61. | `author_profile/craft_reference.md` | **How to write (the positive layer).** Sentence-level style (~21-word mean, claim-first, active voice, named-over-vague, no filler), composition craft, and three registers: base/terse, conceptual/position, warm/narrative. Read while drafting a paragraph. |
  62. | `author_profile/gate_mechanical.md` | **The single mechanical grep gate (M1–M18).** Em-dashes, antithesis, intensifiers, banned + pompous + fancy verbs, throat-clearing, passive voice, wordiness, qualifiers, term-drift — one grep script. Run on every tex edit; the passive-voice scan also runs in the base gate. |
  63. | `author_profile/gate_semantic.md` | **The single reader-judgment gate (S1–S31).** Define-before-use, followability, parse-accessibility, thesis-tie, lexical + decomposition consistency, non-duplication, rigor/grounding, honest positioning, figures, and the **closure gate**. Runs in the red-team/loop pass. |
  64. | `author_profile/compression_patterns.md` | 7 compression operations with before/after examples and quantitative benchmarks |
  65. | `author_profile/rhetorical_moves.md` | Cross-section move sequences for introduction (6 moves), design (5 moves), evaluation (6 moves), related work (3 moves) |
  66. | `author_profile/intervention_types.md` | 7 types of advisor interventions — use this to simulate advisor feedback on drafts |
  67. | `red_team_protocol.md` | **Independent adversarial red-team** (evidence-gated): after the mechanical audit, a reviewer that did NOT write the text re-runs `gate_mechanical.md` and applies `gate_semantic.md`, and must return CLEAN before text ships. |
  68. | `loop_mode.md` | Resumable `/loop` audit-and-fix protocol: a disk-backed ledger, one section per iteration, self-terminating when clean. |
  69. ### Quick Reference: Non-Negotiable Voice Rules
  70. These are extracted from the detailed files above. In case of conflict, the files are the source of truth.
  71. - Mean sentence length: ~21 words. Maximum: ~40 words (contribution lists only).
  72. - Topic sentences assert claims. Never open a paragraph with background or context.
  73. - Zero hedging. "We show" not "We believe." "X reduces Y by N×" not "X may help reduce Y."
  74. - Active voice everywhere — no exceptions. Passive voice obscures agency and weakens prose.
  75. - No filler adjectives: never use "novel," "significant," "state-of-the-art," "comprehensive," "robust," "substantial," "promising," "impressive." Replace with specific numbers or delete.
  76. - Signpost through claims: section openers may state the section's conclusion ("This section shows that X reduces Y by N×") but never use content-free placeholders ("In this section, we describe..."). The test: does the opener tell a skim-reader what the section *concludes*?
  77. - No exclamation marks. No rhetorical questions outside introductions.
  78. - Paragraphs: 4–6 sentences. Every paragraph does exactly one of: make a claim, present evidence, synthesize a takeaway.
  79. - Headings are claims, not topics. "Mechanism M reduces error N×" not "Experimental Results."
  80. - Named over vague: every mechanism, baseline, metric must have a proper name. If a term could apply to any paper in the field, it doesn't belong in this paper.
  81. - Interpret figures, don't just cite. "Figure 3 shows that X, confirming Y" not "See Figure 3."
  82. - Every evaluation subsection ends with a Takeaway paragraph.
  83. - Every design choice justified immediately. Not "we use X" but "we use X because Y."
  84. ### Venue Adaptation
  85. - **Systems venues (NSDI, SIGCOMM, CoNEXT, IMC)**: Use \smartparagraph{} labels. Systems evaluation (latency, throughput, memory). Frame contributions as operational impact. Post-evaluation related work.
  86. - **ML venues (NeurIPS, ICLR, ICML)**: No \smartparagraph. Colon-style subtitles. Reproducibility checklist. Frame as methodological advances. Integrated related work.
  87. - **Workshop/short papers (HotNets, ANRW)**: Compress everything 50%. Lead with the intellectual provocation.
  88. ---
  89. ## Mandatory Style Audit (GATE — applies to ALL tex edits)
  90. **Before presenting or committing ANY new or modified tex content, Claude MUST run a sentence-level style audit.** This is not optional, not triggered by the user, and not limited to full section drafts — it applies to every edit, including paragraph-level changes, subsection additions, and overview rewrites.
  91. The audit checks every changed sentence against `author_profile/gate_mechanical.md`, `author_profile/compression_patterns.md`, and `author_profile/craft_reference.md`. Specifically, scan for and fix:
  92. 0. **Mechanical gate (`gate_mechanical.md`) — run FIRST, with its greps.** Em-dashes (`---`, `—`, ` -- `) are BANNED. Antithesis/mirror flourishes ("X, not Y"; "whatever it is called"), editorializing closers ("the saving is the point", "is not real"), vacuous intensifiers ("in effect", "at its core"), rule-of-three decoration, throat-clearing openers ("Moreover", "Notably"), banned/pompous/fancy words, and content-free openers ("In this paper, we…") are BANNED. Target the plain, short, declarative register (`craft_reference.md`). Do NOT report the audit as passed without running the grep gate in that file.
  93. 1. **Negation-first constructions**: "not X" or "rather than X" where the sentence should assert what something IS. Reframe positively.
  94. 2. **Throat-clearing**: "We address this problem by", "To address this issue", "In order to", "It should be noted that", "Note that". Delete and lead with the action.
  95. 3. **Hedging**: "can potentially", "can be expected to", "may help reduce", "it is possible that". Replace with assertive voice ("produces", "reduces", "achieves").
  96. 4. **Generic adjectives**: "significant", "substantial", "highly desirable", "novel", "robust", "comprehensive". Replace with specific numbers or delete.
  97. 5. **Sentence length**: Flag any sentence exceeding 40 words. Split or compress.
  98. 6. **Passive voice**: "accuracy was achieved by X" → "X achieves". "Experiments were conducted on X" → "We evaluate on X". Active voice everywhere — no exceptions, including methods and evaluation. Run the passive-detection grep from `author_profile/gate_mechanical.md` (§Part C, M11) in this base gate; fix or justify every hit.
  99. 7. **Missing citations**: Technical claims restated from other sections must carry forward their citations (Principle 14).
  100. **Process**: After writing, (a) run the grep gate in `gate_mechanical.md` Part C and fix every hit, then (b) read the changed text line by line for the items above. Report a summary table of violations found and fixed (category, count), INCLUDING the grep counts (em-dashes, flourishes) — not just "audited". Never claim the audit passed on a mental pass alone. Then (c) run the **independent adversarial red-team** (`red_team_protocol.md`): a reviewer that did NOT write the text re-runs `gate_mechanical.md` and applies `author_profile/gate_semantic.md` (define-before-use, followability, thesis-tie, lexical + decomposition consistency, non-duplication, mappability, honest positioning, and the closure gate) with a fresh-reader lens, returning a findings list, not a yes/no. Only text that survives (a) + (b) + (c), with the grep output pasted as evidence, is presented or committed. Per `gate_semantic.md`'s **closure gate** (S31), iterate the red-team after every substantive change until a final closure reviewer returns zero CRITICAL/MAJOR; never defer residual items as "done."
  101. This gate is SEPARATE from and IN ADDITION TO the structural section checklists below.
  102. **Loop mode.** When invoked via `/loop` (e.g. "apply the paper-writing skill iteratively", "audit with loop"), follow `loop_mode.md`: a resumable, ledger-backed audit → red-team → fix cycle that processes one section per iteration and stops itself when every in-scope section is clean. The user need not specify which checks to run or when to stop — the protocol supplies those.
  103. ---
  104. ## Section Checklists
  105. After generating ANY section draft, Claude MUST also read the corresponding structural checklist and run it:
  106. | Section | Checklist file |
  107. |---|---|
  108. | Introduction | `writing_checklists/intro_questions.md` |
  109. | Evaluation | `writing_checklists/evaluation_questions.md` |
  110. | Design / Method | `writing_checklists/design_questions.md` |
  111. | Related Work | `writing_checklists/related_work_questions.md` |
  112. Flag every violation before presenting the draft. Severity levels: CRITICAL (structural — will cause rejection), MAJOR (visible to reviewers), MINOR (polish-level).
  113. ## Section Rhetorical Moves
  114. For detailed guidance on move sequences within each section type, read from `section_rhetorical_moves/`:
  115. | Section | File | Key moves |
  116. |---|---|---|
  117. | Introduction | `section_rhetorical_moves/introduction.md` | Stakes → Problem Gap → Key Abstraction → Design Intuition → Contributions → Results Preview |
  118. | Evaluation | `section_rhetorical_moves/evaluation.md` | Setup Anchoring → Head-to-Head → Deep Dive → Takeaway Synthesis → Ablation → Robustness |
  119. | Design | `section_rhetorical_moves/design.md` | Abstraction Introduction → Design Justification → Component Architecture → Key Design Decision → Robustness |
  120. | Related Work | `section_rhetorical_moves/related_work.md` | Category Clustering → Per-Category Limitation → Positioning Sentence |
  121. These contain actionable guidance with concrete examples showing what works and what doesn't, drawn from accepted and rejected systems and ML papers.
  122. ---
  123. ## The Five-Stage Pipeline
  124. Every paper goes through these stages in order. Claude identifies which stage the user is in and enforces that stage's rules.
  125. ### Stage 1: Structured Brainstorming → Project Context Creation
  126. **Gate**: The user must have a one-sentence identity statement and contribution claims written as results. If they don't, read `brainstorming_guide.md` and walk them through all 6 phases interactively. Don't rush — this is the most important stage. A vague project context produces a vague paper.
  127. After brainstorming, generate a `project_context.md` file using the template in `examples/project_context.md` and save it in the paper's working directory. See `examples/example_project_context.md` for a complete synthetic example.
  128. **Important:** After creating `project_context.md`, add it to the project's `.gitignore` (create the file if it doesn't exist). This file contains strategic framing notes and advisor commentary that should not be committed to shared repositories by default.
  129. ### Stage 2: Architecture
  130. **Gate**: Section outline with claim assignments, per-section narrative arcs, figure/table plan, evaluation structure, and page budget.
  131. **Craft reference**: If the student has run a literature survey (using the [literature-survey-skill](https://github.com/SNL-UCSB/literature-survey-skill) or manually), check for Pass 3+ paper notes with writing craft extractions — introduction anatomy, evaluation architecture, design section structure, and figure design choices from the strongest papers in their area. Load these as reference material for the architecture. The section structure of the best paper at your target venue is a better starting point for your outline than a generic template. Reading and writing develop together: craft patterns extracted during deep reading feed directly into the architecture of your own paper.
  132. **Figure/table plan from visualization artifacts**: If the student has been working with the [data-visualization-skill](https://github.com/SNL-UCSB/data-visualization-skill), check for `plot_context.md` files and WALTER narrations. Each `plot_context.md` records the intent, variable mappings, plot type rationale, and design decisions for a figure — these are ready-made entries for the figure/table plan below. Each WALTER narration (Hypothesis → Axes → Look here → Trend → Exception → Result) maps directly to the evaluation prose that will accompany the figure. The iteration the student did in the viz skill — exploring what the data shows, forming predictions, confronting surprises — has already determined which figures carry the argument. The architecture should reflect that.
  133. Output a structured table:
  134. | Section | Pages | Key claim | Figures/Tables |
  135. |---------|-------|-----------|----------------|
  136. | ... | ... | ... | ... |
  137. **Non-data figure specs**: For each figure in the plan that is NOT a data figure (architecture diagrams, pipeline illustrations, concept diagrams, comparison schematics), read `figure_synthesis_guide.md` and run spec mode to produce a `figure_spec.md`. Data figures (CDFs, bar charts, heatmaps, scatter plots) should be routed to the [data-visualization-skill](https://github.com/SNL-UCSB/data-visualization-skill). The boundary is clear: if the figure requires experimental data to render, it goes through `/viz`; if it illustrates structure, flow, or concepts, it goes through figure synthesis.
  138. ### Stage 3: Section Drafts
  139. **Enforced order**: Draft 0 Introduction → Evaluation → Design/Method → Background → Related Work → Final Introduction → Abstract.
  140. The introduction is written **twice**. This is the most impactful principle in the entire system (Principle 1).
  141. **Draft 0 Introduction** comes first. It is a framing scaffold — stakes, problem gap, rough contribution claims — that sets guardrails for the evaluation. Draft 0 clarifies what the paper is *trying* to show. It is explicitly disposable: it probably will not survive to the final version. Writing is a thinking tool, not just a communication tool — Draft 0 forces the student to externalize their framing before designing experiments.
  142. **The evaluation** comes next, constrained by Draft 0's guardrails. Then Design, Background, and Related Work.
  143. **The final introduction** is rewritten from scratch after the evaluation is complete. It promises exactly what the evidence supports — no more, no less. Draft 0 is reference material, not a starting point for editing. If the user asks to skip Draft 0 and go straight to evaluation, explain that evaluation without framing guardrails produces experiments that don't build toward a unified argument.
  144. **Per-section scaffolding**: Before writing any section's full prose, write the topic sentences first. Read them in sequence — they should form a coherent argument on their own. If the topic sentences don't flow, the paragraphs won't either. Fill in the full paragraphs only after the topic-sentence sequence holds together. In LaTeX, a practical technique is to annotate each paragraph with a purpose comment before writing prose:
  145. ```latex
  146. \section{Introduction}
  147. % Stakes: who suffers and why the domain matters.
  148. ...
  149. % Problem gap: structural limitation of current approaches.
  150. ...
  151. % Key abstraction: named concept that captures our insight.
  152. ...
  153. % Contributions: numbered, claim-first list.
  154. ...
  155. ```
  156. Each comment is a contract: the paragraph that follows must deliver on it. If a paragraph doesn't fit any comment, either the paragraph doesn't belong or a comment is missing.
  157. **Per-section audit**: After generating a draft, read and run the appropriate checklist. Flag every violation with severity level before presenting the draft.
  158. ### Stage 4: Integration
  159. Cross-section consistency pass:
  160. - **Terminology drift**: Is the same concept called by the same name everywhere?
  161. - **Claim-evidence mapping**: Does every introduction claim map to an evaluation subsection?
  162. - **Key abstraction propagation**: Does the named concept from Introduction Move 3 appear in Design Move 1, Evaluation setup, and Related Work positioning?
  163. - **Heading consistency**: Do section headings reflect the contribution order from the introduction?
  164. - **Identity stability**: Read the first sentence of every section — do they tell a coherent story?
  165. - **Flow audit**: Read the last sentence of paragraph N and the first sentence of paragraph N+1, throughout the paper. Does each transition work? Composition — the logical flow a reader can follow — is the most important aspect of technical writing. Readers forgive imperfect grammar but cannot follow broken logical progression. Structure produces flow, but structure alone doesn't guarantee it — the transitions between structural units matter.
  166. - **Signposting check**: Does each section open with a claim-bearing sentence that tells a skim-reader what the section concludes? Is there an outline paragraph at the end of the introduction? Are figures distributed throughout pages rather than clustered?
  167. - **Visual balance (landscaping)**: Check figure distribution across pages, paragraph length variation, and whitespace. Break up walls of text with signposts, figures, and paragraph headings. Avoid orphaned section headings at page bottoms.
  168. ### Stage 5: Compression
  169. Read `author_profile/compression_patterns.md` for the 7 specific operations. Apply in order:
  170. 1. Sentence shortening (remove subordinate clauses, qualifiers, throat-clearing)
  171. 2. Paragraph merging (multiple examples of same point → one best example)
  172. 3. Generic adjective removal ("significant" → specific number or delete)
  173. 4. Tutorial deletion (remove explanations the venue audience already knows)
  174. 5. Claim-first conversion (rewrite buried paragraphs so claim leads)
  175. 6. Takeaway insertion (add synthesis paragraphs after experiment clusters)
  176. 7. Figure/table promotion (move dense numerical comparisons from prose to visuals)
  177. Target: 30–50% reduction from first draft. Report character count before and after.
  178. **Do not pad to fill page limits.** If the paper is under the page limit after compression, that is fine. A short paper with appropriate content is better than a padded paper that reaches the limit. Padding introduces filler that weakens the argument.
  179. ### Pre-Submission Mechanical Checklist (Automated)
  180. After compression and before submission, Claude MUST automatically run these checks using shell commands on the paper's `.tex` and compiled `.pdf` files. Do not ask the student to run them manually — execute them and report results.
  181. **1. Page count.** Extract page count from the compiled PDF and compare against the venue's limit (from `project_context.md`). Flag whether references/appendices count — this varies by venue.
  182. ```bash
  183. pdfinfo paper.pdf | grep Pages
  184. ```
  185. **2. Broken references.** Search `.tex` source files for unresolved references that will render as `[?]` or `??` in the PDF. Also check the `.log` file for LaTeX warnings about undefined references and citations.
  186. ```bash
  187. grep -n "LaTeX Warning.*undefined" paper.log
  188. grep -rn '\\cite{' *.tex | grep -v '%' # list all citations for cross-check
  189. ```
  190. **3. Embedded fonts.** Verify all fonts are embedded. Non-embedded fonts cause rendering differences across machines and are rejected by some submission systems.
  191. ```bash
  192. pdffonts paper.pdf | grep -v "yes"
  193. ```
  194. If any font shows `no` in the `emb` column, flag it and suggest adding `\usepackage[T1]{fontenc}` or compiling with `GS_OPTIONS=-dPDFSETTINGS=/prepress`.
  195. **4. Figure quality.** Check that all included figure files are vector format (PDF/EPS) or high-resolution raster. List all figures referenced in the source and verify they exist.
  196. ```bash
  197. grep -rn '\\includegraphics' *.tex # list all figure references
  198. file figures/*.pdf figures/*.png 2>/dev/null # check file types
  199. ```
  200. Flag any PNG/JPG figures — these should be vector unless they are photographs or screenshots.
  201. **5. Anonymization (if double-blind).** Search all `.tex` files for author names, institution names, grant numbers, acknowledgment sections, and self-citations that could reveal identity.
  202. ```bash
  203. grep -rni 'AUTHOR_NAMES_HERE\|INSTITUTION_HERE\|\\thanks\|acknowledgment' *.tex
  204. ```
  205. Replace `AUTHOR_NAMES_HERE` and `INSTITUTION_HERE` with actual names from `project_context.md` before running.
  206. **6. Column balancing.** Check whether the `balance` package is loaded (for two-column formats). If not, suggest adding `\usepackage{balance}` and `\balance` before `\bibliography`.
  207. ```bash
  208. grep -rn 'balance' *.tex
  209. ```
  210. **7. Common LaTeX issues.** Scan for frequently missed mechanical problems:
  211. ```bash
  212. grep -rn '\\cite{.*}' *.tex | grep -v '~\\cite' # missing ~ before \cite (dangling references)
  213. grep -rn 'et al\.' *.tex | grep -v '~' # missing ~ after "et al."
  214. grep -rn '\\label{' *.tex | sort | uniq -d # duplicate labels
  215. ```
  216. **Report format**: Run all checks, then present a single summary table:
  217. | Check | Status | Details |
  218. |-------|--------|---------|
  219. | Page count | ✓ or ✗ | N pages (limit: M) |
  220. | Broken refs | ✓ or ✗ | List of undefined refs |
  221. | Embedded fonts | ✓ or ✗ | List of non-embedded fonts |
  222. | Figure quality | ✓ or ✗ | List of raster figures |
  223. | Anonymization | ✓ or ✗ | List of leaks found |
  224. | Column balance | ✓ or ✗ | Package present/missing |
  225. | LaTeX issues | ✓ or ✗ | Count of dangling refs, duplicate labels |
  226. Fix what can be fixed automatically (e.g., adding `~` before `\cite`). Flag what requires student decision (e.g., replacing a raster figure with vector).
  227. ---
  228. ## How to Respond to Common Requests
  229. ### "Help me write section X of paper Y"
  230. 1. Load the paper's `project_context.md`
  231. 2. Read all `author_profile/` files
  232. 3. Read the section's rhetorical moves from `section_rhetorical_moves/`
  233. 4. Identify which stage the paper is in — enforce introduction-twice ordering (Draft 0 intro → Evaluation → Design → Background → Related Work → Final intro → Abstract)
  234. 5. Write topic sentences first; verify they form a coherent argument before filling paragraphs
  235. 6. Generate the draft following the move sequence
  236. 7. Run the section checklist and flag violations with severity levels
  237. ### "Review / critique this draft"
  238. 1. Load `project_context.md`
  239. 2. Read `author_profile/intervention_types.md` for the 7 intervention types
  240. 3. Apply in order: framing → structural rewrite → background deletion → evaluation strengthening → terminology tightening → claim-first conversion → compression
  241. 4. Give numbered feedback with severity (CRITICAL / MAJOR / MINOR), the specific principle violated (by number from `editorial_principles.md`), and a concrete rewrite
  242. ### "Compress / tighten this section"
  243. 1. Read `author_profile/compression_patterns.md`
  244. 2. Apply the 7 operations in order
  245. 3. Show before/after with character counts
  246. 4. Normal compression: 30-50%. Over 50% signals a framing problem, not a wordiness problem.
  247. ### "I want to get feedback on this draft"
  248. 1. **First readings are precious.** Someone can read your work for the first time only once. Don't send your first draft to everyone simultaneously — chain your feedback. Send to one reader, incorporate their feedback, then send the revised version to the next reader. Each iteration strengthens the draft before it reaches the next pair of fresh eyes.
  249. 2. Help the student plan their feedback chain: who reads first (someone outside the subfield for framing clarity), who reads second (a domain expert for technical correctness), who reads last (the advisor, who sees the strongest version).
  250. 3. When asking a reader for feedback, tell them what to focus on: "Is the narrative in the introduction clear?" is more useful than "any thoughts?" Unfocused feedback wastes a first reading.
  251. 4. Use Claude's review mode (`author_profile/intervention_types.md`) to simulate a round of feedback *before* spending a human reader's first reading on an early draft.
  252. ### "Help me respond to reviewers"
  253. 1. Load `project_context.md` and the reviews
  254. 2. Classify each concern by severity: framing (most dangerous) → design → scope → rigor (most manageable)
  255. 3. For each concern: acknowledge → explain what changed → point to specific section/figure
  256. 4. Never be defensive. Never dismiss a concern. If a reviewer misunderstood, that's a WRITING failure to fix, not a reviewer failure to criticize.
  257. ### "I'm starting a new paper — where do I begin?"
  258. 1. Welcome them. Explain the five-stage pipeline — especially the introduction-twice principle.
  259. 2. Read `brainstorming_guide.md` and walk through all 6 phases to create their first `project_context.md`.
  260. 3. Emphasize: the brainstorming phase is the most important. A precise project context saves weeks of revision later.
  261. 4. After brainstorming: write a **Draft 0 introduction** — a disposable framing scaffold (stakes, problem gap, rough contributions) that sets guardrails for the evaluation. Then point them to `section_rhetorical_moves/evaluation.md` — they'll write the evaluation next, constrained by Draft 0.
  262. 5. Remind them: "Your first draft should be comprehensive — include everything. Compression comes later. The goal is to get material on paper, not to be concise. Draft 0 of the introduction will probably not survive — that's the point. It clarifies your thinking."
  263. ### "Turn our notes into a paper outline" / "What is the story for <venue>?"
  264. Read `story_mode.md` and run its ten steps (or the short path). Start with step 1 (read the whole record) even if the user offers a summary; ask where the notes, drafts, code and related-work PDFs live. Keep everything beyond the record in a separate section for the user to accept or reject.
  265. ### "I need a non-data figure (architecture diagram, pipeline illustration, etc.)"
  266. 1. Load the paper's `project_context.md`
  267. 2. Read `figure_synthesis_guide.md` and the relevant files in `figure_templates/`
  268. 3. Classify the figure by archetype (architecture overview, pipeline flow, component detail, concept illustration, comparison schematic, taxonomy, deployment diagram)
  269. 4. Select the generation backend: AI image generation (for visually rich figures like architecture overviews and concept illustrations) or TikZ (for precise structural figures like pipeline flows and taxonomy matrices). The guide has defaults per archetype, but the student can override.
  270. 5. Run spec mode — walk through archetype-specific questions to produce a `figure_spec.md`
  271. 6. Run generate mode — assemble an AI prompt or TikZ code, produce the figure
  272. 7. Run critique mode — check against claims, venue formatting, and design principles, and enforce caption terseness (G7: a bold takeaway plus at most one clause; flag captions over ~3 lines), and verify legibility by inspecting the rendered image (a checklist-green figure can still be an illegible mess)
  273. 8. **NOTE**: Data figures (CDFs, scatter plots, bar charts, heatmaps) should go through `/viz`, not through figure synthesis
README.md · README · 152 lines
  1. # paper-writing-skill
  2. A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skill that encodes a research-paper
  3. writing methodology: a five-stage pipeline, section-by-section rhetorical moves, a style audit that
  4. runs on every edit, an independent red-team, and a figure-synthesis workflow for non-data figures.
  5. The rules are empirical — distilled from forensic analysis of real paper revisions (7,600+ Overleaf
  6. edits, 100+ tex versions, 5 peer-review cycles across systems and ML venues). See
  7. [DESIGN.md](DESIGN.md) for the rationale and evidence behind each rule.
  8. It offloads the scaffolding — section structure, cross-section coherence, page-limit compression,
  9. voice consistency, figure generation — so the writer keeps the hard parts: what the paper claims,
  10. whether the evidence supports it, and how to position the work.
  11. **Who it's for:** PhD students and researchers writing conference or journal papers. Tuned for
  12. systems/networking (SIGCOMM, NSDI, CoNEXT, IMC) and ML (NeurIPS, ICLR, ICML); adaptable to any
  13. field (see [Customize](#customize-for-your-field)).
  14. ## Quick Start
  15. ```bash
  16. git clone https://github.com/SNL-UCSB/paper-writing-skill.git
  17. cd paper-writing-skill
  18. ./setup # installs to ~/.claude/skills/paper-writing/
  19. ```
  20. Then, in your paper's directory: run `claude`, and type `/paper-writing`. If a `project_context.md`
  21. exists, Claude loads it and continues; if not, it runs a structured brainstorming session (34
  22. questions across 6 phases) to create one.
  23. Requires Claude Code installed and signed in (https://docs.claude.com).
  24. **New to the skill? Read [USAGE.md](USAGE.md)**: your first session, which mode for which situation, where outputs land, how to iterate, and how to keep unpublished work private.
  25. ## How It Works
  26. Three layers: a **fixed pipeline**, **customizable rules** (defaults provided), and a per-paper
  27. **project context**.
  28. **Story mode** (`story_mode.md`) comes first when the ideas already exist across meeting notes, drafts, code and related work: ten steps (or a short path for workshop papers) turn that record into a paper story, an outline in the venue's structure, and a calibration spec, inventing nothing the record does not contain.
  29. **The pipeline** (five stages):
  30. 1. **Brainstorming** — 34 questions across 6 phases produce a `project_context.md` (the binding
  31. contract for every later session).
  32. 2. **Architecture** — section outline, claim assignments, figure/table plan, page budget.
  33. 3. **Section drafts** — enforced order: Draft 0 Introduction → Evaluation → Design → Background →
  34. Related Work → Final Introduction → Abstract. The introduction is written **twice**; topic
  35. sentences are written and checked for a coherent argument before full prose.
  36. 4. **Integration** — cross-section consistency (terminology, claims, headings, flow).
  37. 5. **Compression** — 7 operations, 30–50% target reduction.
  38. **The style audit.** Every tex edit passes a mandatory gate. The style layer is three files, split
  39. by mechanism:
  40. | File | Role |
  41. |---|---|
  42. | `author_profile/gate_mechanical.md` | The single **grep gate** (M1–M18): em-dashes, antithesis, filler/pompous/fancy words, passive voice (zero tolerance), wordiness, term-drift. Runs on every edit. |
  43. | `author_profile/gate_semantic.md` | The single **reader-judgment gate** (S1–S31): define-before-use, followability, coherence, consistency, rigor/grounding, honest positioning, figures, closure. Runs in the red-team/loop pass. |
  44. | `author_profile/craft_reference.md` | **How to write** (the positive layer): sentence-level style and three registers (base/terse, conceptual/position, warm/narrative). |
  45. **The red-team.** After the author's audit, an *independent* reviewer that did not write the text
  46. re-runs the greps and applies the semantic gate with a fresh-reader lens, returning findings — not a
  47. yes/no. Run it iteratively via `/loop` (`loop_mode.md`), which keeps a disk-backed ledger and stops
  48. itself when every section is clean. See `red_team_protocol.md`.
  49. **Figure synthesis** (`figure_synthesis_guide.md`). A three-mode workflow (spec → generate →
  50. critique) for non-data figures — architecture diagrams, pipeline flows, concept illustrations — with
  51. venue-specific styling. Data figures (plots) go through the separate `/viz` skill.
  52. ### Common workflows
  53. - "Turn our notes into a <venue> outline" — runs story mode on your notes, drafts, code and earlier reviews.
  54. - "Help me write the evaluation" — drafts the 6-move sequence, then runs the checklist.
  55. - "Review this introduction" — applies the intervention types, returns numbered feedback.
  56. - "Compress section 4" — applies the 7 compression operations, reports before/after counts.
  57. - "Audit with the paper-writing skill until clean" — runs the `/loop` red-team cycle.
  58. - "I need an architecture diagram" — walks the figure spec → generate → critique.
  59. ## What's in This Repo
  60. ```
  61. paper-writing-skill/
  62. ├── SKILL.md # Main skill file (Claude reads this)
  63. ├── USAGE.md # How to use the skill well (start here)
  64. ├── brainstorming_guide.md # 34 questions across 6 phases
  65. ├── story_mode.md # From a group's existing record to a story and outline
  66. ├── story_document.md # Template for the one-page story document co-authors read
  67. ├── figure_synthesis_guide.md # Non-data figure workflow
  68. ├── red_team_protocol.md # Independent, evidence-gated review
  69. ├── loop_mode.md # Resumable /loop audit-and-fix
  70. ├── setup # One-command installer
  71. ├── DESIGN.md # Rationale + evidence behind the rules
  72. ├── author_profile/ # Editorial rules (defaults, customizable)
  73. │ ├── editorial_principles.md # 14 principles with evidence
  74. │ ├── craft_reference.md # how to write (three registers)
  75. │ ├── gate_mechanical.md # the grep gate (M1–M18)
  76. │ ├── gate_semantic.md # the reader-judgment gate (S1–S31)
  77. │ ├── compression_patterns.md # 7 compression operations
  78. │ ├── rhetorical_moves.md # cross-section move sequences
  79. │ └── intervention_types.md # 7 advisor intervention types
  80. ├── writing_checklists/ # Post-draft structural checklists
  81. ├── section_rhetorical_moves/ # Per-section move sequences + examples
  82. ├── figure_templates/ # Venue styles, prompts, TikZ skeletons
  83. └── examples/ # project_context template + a synthetic filled-in example
  84. ```
  85. The rules, checklists, and move guides also work without Claude Code — print them for a lab
  86. workshop, or use the checklists for self-review before sending a draft to an advisor.
  87. ## Customize for Your Field
  88. Defaults ship for systems/networking and ML venues. Edit files in `author_profile/`:
  89. - **`craft_reference.md`** — sentence-length targets, tone, and the three registers.
  90. - **`gate_mechanical.md` / `gate_semantic.md`** — add or relax specific checks (keep the term-drift
  91. list current per paper).
  92. - **`editorial_principles.md`** — add or reprioritize principles (keep introduction-twice and
  93. named-over-vague; they are venue-agnostic).
  94. - **`compression_patterns.md`**, **`section_rhetorical_moves/`**, **`figure_templates/`** — tune
  95. compression intensity, add move examples from your field, adjust figure styling per venue.
  96. **For advisors:** fork the repo, encode your standards in `author_profile/`, and have students clone
  97. your fork — they get your group's conventions immediately. Students can further customize; the
  98. pipeline stays consistent.
  99. ## Private overlays
  100. This repository is public, so every example in it is synthetic. A research group can keep its real worked cases, house rules and project records in a **private overlay skill** installed next to this one: an installed skill whose name ends in `paper-writing-lab` (for example `~/.claude/skills/paper-writing-lab/` or `~/.claude/skills/<group>-paper-writing-lab/`). When an overlay is present, the skill reads it after its own files; nothing from the overlay should ever be copied into this repository.
  101. ## Troubleshooting
  102. - **`/paper-writing` not recognized** — re-run `./setup`; check `ls ~/.claude/skills/paper-writing/SKILL.md`.
  103. - **Rules not being followed** — invoke `/paper-writing` explicitly at the start; the skill only
  104. activates when invoked.
  105. - **Start a paper's context over** — delete `project_context.md` and invoke `/paper-writing` again.
  106. - **Updated the repo but Claude uses old rules** — run `./setup` again after `git pull`.
  107. Always edit files in this repo, not in `~/.claude/skills/`; `./setup` copies them into place.
  108. ## License
  109. MIT. If you use this in your research workflow, cite:
  110. ```
  111. @misc{paper-writing-skill,
  112. author = {Gupta, Arpit},
  113. title = {paper-writing-skill: A Claude Code skill for research paper writing},
  114. year = {2026},
  115. publisher = {GitHub},
  116. url = {https://github.com/SNL-UCSB/paper-writing-skill}
  117. }
  118. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.