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-writerDesign 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/*.textodraft.tex— you control the assembly order.
