# Paper Writing

> Research paper writing assistant that enforces Arpit Gupta's editorial principles, voice profile, and 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, Overl…

- **Type:** Skill
- **Install:** `agentstack add skill-snl-ucsb-paper-writing-skill-paper-writing-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [SNL-UCSB](https://agentstack.voostack.com/s/snl-ucsb)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [SNL-UCSB](https://github.com/SNL-UCSB)
- **Source:** https://github.com/SNL-UCSB/paper-writing-skill
- **Website:** https://sites.cs.ucsb.edu/~arpitgupta/

## Install

```sh
agentstack add skill-snl-ucsb-paper-writing-skill-paper-writing-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Paper Writing Skill

## How This Skill Works

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.

### Three Layers

1. **The pipeline (fixed)**: A five-stage writing workflow. Does not change between users or papers.

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.

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.

### How This Skill Connects to the Research Pipeline

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:

**From the [literature-survey-skill](https://github.com/SNL-UCSB/literature-survey-skill):**
- **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.
- **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.
- **Competitive positioning** → feeds Brainstorming Phase 4. The invariant matrix and dependency graph from synthesis show exactly where your paper sits relative to existing work.

**From the [data-visualization-skill](https://github.com/SNL-UCSB/data-visualization-skill):**
- **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.
- **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.
- **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.
- **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.

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

### When This Skill Triggers, Claude MUST:

1. Read this SKILL.md (already loaded)
2. Read ALL files in `author_profile/` — these are the source of truth for editorial rules
3. Ask which paper the user is working on
4. Look for a `project_context.md` in the paper's working directory
5. If found, read it and treat it as binding constraints
6. If not found, run the **Structured Brainstorming** workflow below to create one
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

---

## Structured Brainstorming — The Skill's Centerpiece

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

### How It Works

Claude MUST read `brainstorming_guide.md` and walk the student through its 6 phases interactively. The phases are:

| Phase | Focus | Key outcome |
|-------|-------|-------------|
| 1. Problem Discovery | Who suffers, what breaks, why it breaks structurally | The opening paragraph's stakes and the Problem Gap |
| 2. Contribution Crystallization | Core claim, headline number, key abstraction name | The identity sentence and contribution list |
| 3. Evaluation Design | Baselines, metrics, datasets, experiment-to-claim mapping | The evaluation plan that constrains what the introduction can promise |
| 4. Positioning and Framing | Venue fit, competitive positioning, category creation vs. competition | The Related Work positioning sentence |
| 5. Architecture and Constraints | Design pipeline, locked decisions, open questions | The Design section's structure and the project's scope |
| 6. Narrative Spine | Story arc, the "inevitable" moment, the tweet-length pitch | The thread connecting every section |

### Rules for Running Brainstorming

- **Go phase by phase.** Don't skip ahead. Phase 1 (the problem) must be clear before Phase 2 (the contribution) makes sense.
- **"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.
- **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.
- **Distinguish structural from quantitative.** "Existing tools aren't accurate enough" is quantitative — it motivates more experiments. "Existing tools assume stationarity, which fails on bursty data" is structural — it motivates a new approach. Papers need structural gaps.
- **After all phases, generate `project_context.md`** using the template in `examples/project_context.md`. See `examples/netburst_project_context.md` for a real example of what a complete project context looks like.

---

## Voice and Editorial Rules

Claude MUST read these files from this skill's directory. They contain the detailed rules with examples.

| File | What it controls |
|---|---|
| `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.) |
| `author_profile/voice_profile.md` | Sentence-level style: ~21 word mean, claim-first topic sentences, zero hedging, active voice, banned words, paragraph density, tone |
| `author_profile/compression_patterns.md` | 7 compression operations with before/after examples and quantitative benchmarks |
| `author_profile/rhetorical_moves.md` | Cross-section move sequences for introduction (6 moves), design (5 moves), evaluation (6 moves), related work (3 moves) |
| `author_profile/intervention_types.md` | 7 types of advisor interventions — use this to simulate advisor feedback on drafts |

### Quick Reference: Non-Negotiable Voice Rules

These are extracted from the detailed files above. In case of conflict, the files are the source of truth.

- Mean sentence length: ~21 words. Maximum: ~40 words (contribution lists only).
- Topic sentences assert claims. Never open a paragraph with background or context.
- Zero hedging. "We show" not "We believe." "X reduces Y by 13×" not "X may help reduce Y."
- Active voice everywhere — no exceptions. Passive voice obscures agency and weakens prose.
- No filler adjectives: never use "novel," "significant," "state-of-the-art," "comprehensive," "robust," "substantial," "promising," "impressive." Replace with specific numbers or delete.
- Signpost through claims: section openers may state the section's conclusion ("This section shows that X reduces Y by 13×") but never use content-free placeholders ("In this section, we describe..."). The test: does the opener tell a skim-reader what the section *concludes*?
- No exclamation marks. No rhetorical questions outside introductions.
- Paragraphs: 4–6 sentences. Every paragraph does exactly one of: make a claim, present evidence, synthesize a takeaway.
- Headings are claims, not topics. "Event-centric decomposition reduces error 13×" not "Experimental Results."
- 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.
- Interpret figures, don't just cite. "Figure 3 shows that X, confirming Y" not "See Figure 3."
- Every evaluation subsection ends with a Takeaway paragraph.
- Every design choice justified immediately. Not "we use X" but "we use X because Y."

### Venue Adaptation

- **Systems venues (NSDI, SIGCOMM, CoNEXT, IMC)**: Use \smartparagraph{} labels. Systems evaluation (latency, throughput, memory). Frame contributions as operational impact. Post-evaluation related work.
- **ML venues (NeurIPS, ICLR, ICML)**: No \smartparagraph. Colon-style subtitles. Reproducibility checklist. Frame as methodological advances. Integrated related work.
- **Workshop/short papers (HotNets, ANRW)**: Compress everything 50%. Lead with the intellectual provocation.

---

## Mandatory Style Audit (GATE — applies to ALL tex edits)

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

The audit checks every changed sentence against `author_profile/voice_profile.md` and `author_profile/compression_patterns.md`. Specifically, scan for and fix:

1. **Negation-first constructions**: "not X" or "rather than X" where the sentence should assert what something IS. Reframe positively.
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.
3. **Hedging**: "can potentially", "can be expected to", "may help reduce", "it is possible that". Replace with assertive voice ("produces", "reduces", "achieves").
4. **Generic adjectives**: "significant", "substantial", "highly desirable", "novel", "robust", "comprehensive". Replace with specific numbers or delete.
5. **Sentence length**: Flag any sentence exceeding 40 words. Split or compress.
6. **Passive voice**: "accuracy was achieved by X" → "X achieves". "Experiments were conducted on X" → "We evaluate on X". Active voice everywhere — no exceptions.
7. **Missing citations**: Technical claims restated from other sections must carry forward their citations (Principle 14).

**Process**: After writing, read the changed text line by line. Fix all violations. Report a summary table of violations found and fixed (category, count). Only then present the draft or commit.

This gate is SEPARATE from and IN ADDITION TO the structural section checklists below.

---

## Section Checklists

After generating ANY section draft, Claude MUST also read the corresponding structural checklist and run it:

| Section | Checklist file |
|---|---|
| Introduction | `writing_checklists/intro_questions.md` |
| Evaluation | `writing_checklists/evaluation_questions.md` |
| Design / Method | `writing_checklists/design_questions.md` |
| Related Work | `writing_checklists/related_work_questions.md` |

Flag every violation before presenting the draft. Severity levels: CRITICAL (structural — will cause rejection), MAJOR (visible to reviewers), MINOR (polish-level).

## Section Rhetorical Moves

For detailed guidance on move sequences within each section type, read from `section_rhetorical_moves/`:

| Section | File | Key moves |
|---|---|---|
| Introduction | `section_rhetorical_moves/introduction.md` | Stakes → Problem Gap → Key Abstraction → Design Intuition → Contributions → Results Preview |
| Evaluation | `section_rhetorical_moves/evaluation.md` | Setup Anchoring → Head-to-Head → Deep Dive → Takeaway Synthesis → Ablation → Robustness |
| Design | `section_rhetorical_moves/design.md` | Abstraction Introduction → Design Justification → Component Architecture → Key Design Decision → Robustness |
| Related Work | `section_rhetorical_moves/related_work.md` | Category Clustering → Per-Category Limitation → Positioning Sentence |

These contain actionable guidance with concrete examples showing what works and what doesn't, drawn from accepted and rejected systems and ML papers.

---

## The Five-Stage Pipeline

Every paper goes through these stages in order. Claude identifies which stage the user is in and enforces that stage's rules.

### Stage 1: Structured Brainstorming → Project Context Creation

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

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/netburst_project_context.md` for a real example.

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

### Stage 2: Architecture

**Gate**: Section outline with claim assignments, per-section narrative arcs, figure/table plan, evaluation structure, and page budget.

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

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

Output a structured table:

| Section | Pages | Key claim | Figures/Tables |
|---------|-------|-----------|----------------|
| ... | ... | ... | ... |

**Non-data figure specs**:

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [SNL-UCSB](https://github.com/SNL-UCSB)
- **Source:** [SNL-UCSB/paper-writing-skill](https://github.com/SNL-UCSB/paper-writing-skill)
- **License:** MIT
- **Homepage:** https://sites.cs.ucsb.edu/~arpitgupta/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-snl-ucsb-paper-writing-skill-paper-writing-skill
- Seller: https://agentstack.voostack.com/s/snl-ucsb
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.