Paper Writer Plugin

Personal Claude Code plugin for academic paper writing in ML / computational biology.

9 skills (procedural + reference) + 5 thin agents + 5 commands, designed so the same procedural knowledge can be invoked in main session or in an isolated subagent.

Architecture

• skills/ holds all procedural knowledge. Skills are reusable: load them in main session OR have an agent load them in isolation.
• agents/ are thin wrappers (~15 lines each). Each agent declares model, tools, and which skills to load — no procedure embedded.
• commands/ dispatch a specific agent as a subagent (for cases where you want isolation; the same workflow can run in main session without commands).

Skills

| Skill | Used by | |---|---| | repo-scanning-protocol | brainstormer | | outline-construction | outline-architect | | peer-review-protocol | peer-reviewer | | prose-editing-discipline | prose-polisher | | latex-conventions | draft-writer, prose-polisher | | claim-evidence-chain | outline-architect, draft-writer, peer-reviewer | | academic-style | draft-writer, prose-polisher | | reviewer-rubric | peer-reviewer | | figure-design-patterns | brainstormer |

Agents

All agents run on opus and have WebSearch + WebFetch.

| Agent | Tools (extra to web) | Skills | |---|---|---| | writing-brainstormer | Read, Glob, Grep, Bash, Write, Edit | repo-scanning-protocol, figure-design-patterns | | outline-architect | Read, Write | outline-construction, claim-evidence-chain | | draft-writer | Read, Write, Edit, Bash | claim-evidence-chain, academic-style, latex-conventions | | peer-reviewer | Read, Glob, Grep | peer-review-protocol, reviewer-rubric, claim-evidence-chain | | prose-polisher | Read, Edit | prose-editing-discipline, academic-style, latex-conventions |

Commands

| Command | Dispatches | |---|---| | /paper-pipeline [slug] [stage] | orchestrator — detects current stage from working/ and runs the right agent; pauses at each checkpoint | | /brainstorm-paper [slug] | writing-brainstormer | | /outline-paper [slug] | outline-architect | | /write-section [slug] [section-id] | draft-writer | | /review-paper [slug] | peer-reviewer | | /polish-paper [slug] | prose-polisher |

You can also invoke any agent directly in main session without a command — the skills load identically.

Suggested Pipeline

The full flow is brainstorm → outline → draft → review → polish. Each stage produces a file in papers/<slug>/working/ that the next stage consumes; the user owns the decisions between stages.

| # | Stage | Agent | Produces | You decide before this stage | |---|---|---|---|---| | 1 | brainstorm | writing-brainstormer | findings.md | repo path | | 2 | outline | outline-architect | outline.md | thesis, target venue, word budget | | 3 | draft | draft-writer (per section, looped) | draft-sections/<id>.tex | section order; you assemble draft.tex | | 4 | review | peer-reviewer | review.md | review depth; optional reviewer-persona focus | | 5 | polish | prose-polisher | polished.tex + polish-changelog.md | which reviewer comments to act on; scope |

Two ways to drive it:

• Step by step — run the per-stage command for each stage (/brainstorm-paper, /outline-paper, …). Most explicit; nothing happens you didn't ask for.
• Orchestrator — run /paper-pipeline <slug>. It detects which artifacts already exist and starts at the earliest missing stage, or starts at [stage] if you pass one explicitly. After each stage it stops, summarizes, and tells you what's next — it never auto-advances. Re-run later to resume from wherever you left off.

File Conventions

papers/<paper-slug>/
├── .bibsources          # paths to your master .bib files (one per line)
├── refs.bib             # plugin-managed; agents append verified entries here
├── working/
│   ├── findings.md
│   ├── outline.md
│   ├── draft-sections/<id>.tex
│   ├── draft.tex        # you assemble from draft-sections/
│   ├── review.md
│   ├── polished.tex
│   └── polish-changelog.md
└── final/               # camera-ready (you maintain)

Markdown for findings/outline/review; LaTeX for draft and polish onward. Markdown→LaTeX handoff happens at the outline.md → draft-sections/*.tex boundary.

Citation Discipline

Hybrid .bibsources lookup chain:

1. Look up citation key in master .bib files listed in papers/<slug>/.bibsources → if found, use it. 2. Else look up in papers/<slug>/refs.bib → if found, use it. 3. Else search online and verify the entry has a DOI or arXiv ID. 4. If verified: append to papers/<slug>/refs.bib with key lastname2024firstword. Master .bib files are read-only. 5. If unverifiable: emit [CITE: <description>] marker and report in chat.

Repo-Write Confirmation Gate

Agents have full write access in principle, but they MUST post a chat message naming the exact file and intended change before any Write/Edit outside papers/<slug>/. Silence is not consent — they wait for an explicit "yes / ok / go ahead".

Customization

The plugin ships voice/forbidden-pattern conventions in skills/academic-style/SKILL.md. Override per-repo by:

• Adding voice rules to your repo's CLAUDE.md (Claude Code loads it on top of the plugin), OR
• Editing your installed copy of academic-style/SKILL.md.

The plugin itself has no CLAUDE.md — it's portable across repos, and per-repo voice belongs in your repo, not in the plugin.

Install

git clone <this-repo> ~/.claude/plugins/paper-writer

Design Principles

1. Skills hold procedure. Agents are thin. Procedure is shareable between main session and subagents. 2. One responsibility per agent. New responsibility → new skill or new agent, never bolted on. 3. Files are the message-passing medium. Subagents communicate via papers/<slug>/working/. 4. The user drives the checkpoints. The /paper-pipeline orchestrator suggests the next stage and dispatches agents, but it never auto-advances past a decision point (thesis, section order, which reviewer comments to act on). The user is still the integration layer; the orchestrator just removes the "which command do I run next" friction.

Known Limitations

• No multi-persona reviewer (single persona by default).
• No LaTeX compilation (handle separately via tectonic / Overleaf / latexmk).
• No automatic figure regeneration; agent will ASK before touching analysis code.
• No automated assembly from draft-sections/*.tex to draft.tex — you control the assembly order.