Skip to content
Back to search

paper-orchestra

Phased, evidence-first research-paper workflow - research planning, verified literature review with a source-evidence matrix, paper outline, section drafting, critical peer-style review, and optional LaTeX preparation. Use when the user wants to plan, write, review, or restructure an academic/technical paper, thesis chapter, or research report from ideas, notes, logs, or experimental results; when they ask for a literature review or citation verification; when they want a full research workflow run autonomously from a single topic; or when they invoke /paper-orchestra (optionally with a mode such as auto, plan, lit, outline, write, review, latex).

Safety scan

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

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ziyad-altamimi--paper-orchestra-claude-skill/badge.svg)](/listings/ziyad-altamimi--paper-orchestra-claude-skill)

HTML

<a href="/listings/ziyad-altamimi--paper-orchestra-claude-skill"><img src="/api/listings/ziyad-altamimi--paper-orchestra-claude-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.

Claude Code loads personal skills from `~/.claude/skills/<skill-name>/SKILL.md`, and project skills from `.claude/skills/<skill-name>/SKILL.md` inside a repository. The repository root of this project *is* the skill folder, so you can clone it straight into place.

The extra repository files (`README.md`, `LICENSE`, `.gitignore`) sit next to `SKILL.md` and don't affect the skill.

Linux and macOS

Personal install (available in all your projects):

mkdir -p ~/.claude/skills
git clone https://github.com/Ziyad-Altamimi/paper-orchestra-claude-skill.git ~/.claude/skills/paper-orchestra

Project install (shared with collaborators through that project's repository):

mkdir -p .claude/skills
git clone https://github.com/Ziyad-Altamimi/paper-orchestra-claude-skill.git .claude/skills/paper-orchestra

Windows (PowerShell)

Personal install:

New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills" | Out-Null
git clone https://github.com/Ziyad-Altamimi/paper-orchestra-claude-skill.git "$env:USERPROFILE\.claude\skills\paper-orchestra"

Project install, run from your project root:

New-Item -ItemType Directory -Force ".claude\skills" | Out-Null
git clone https://github.com/Ziyad-Altamimi/paper-orchestra-claude-skill.git ".claude\skills\paper-orchestra"

The target folder name must be `paper-orchestra` so that it matches the skill's `name`. Start a new Claude Code session after installing. To update later, run `git pull` inside the skill folder.

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 · 247 lines
  1. ---
  2. name: paper-orchestra
  3. description: Phased, evidence-first research-paper workflow - research planning, verified literature review with a source-evidence matrix, paper outline, section drafting, critical peer-style review, and optional LaTeX preparation. Use when the user wants to plan, write, review, or restructure an academic/technical paper, thesis chapter, or research report from ideas, notes, logs, or experimental results; when they ask for a literature review or citation verification; when they want a full research workflow run autonomously from a single topic; or when they invoke /paper-orchestra (optionally with a mode such as auto, plan, lit, outline, write, review, latex).
  4. argument-hint: "[auto \"topic\" | plan|lit|outline|write|review|latex|all] [project path or topic]"
  5. ---
  6. # PaperOrchestra (Claude Code adaptation)
  7. A phased research-writing workflow that turns raw materials (idea notes, experiment logs, data, figures) into a grounded paper. It adapts the *methodology* of Google Research's PaperOrchestra (outline -> literature review -> section writing -> review-driven refinement -> formatting) to Claude Code's own tools. It does **not** run, wrap, or reproduce the PaperOrchestra Python software, its agents, its LLM backends, or its autoraters. See `references/provenance.md`.
  8. ## Non-negotiable integrity rules
  9. These override any user request for speed, length, or polish.
  10. 1. **Never fabricate** references, authors, titles, venues, years, DOIs, URLs, quotations, statistics, experimental results, figures, or citation keys.
  11. 2. Every citation in a draft must map to a row in the source-evidence matrix with status `verified` (or be visibly flagged `[CITATION NEEDED: ...]`).
  12. 3. Every number in a draft must trace to a user-provided file (log, CSV, notebook output) by path. If it cannot, write `[DATA MISSING: ...]` instead.
  13. 4. Label content explicitly as one of: **Verified** (checked against a source you opened this session), **Assumption** (reasonable but unconfirmed - state why), **Missing** (needed but not available).
  14. 5. Quotations: only verbatim text you actually read in the source, kept short, with location (page/section). Otherwise paraphrase and cite.
  15. 6. Do not claim superiority over a cited work unless the user's own results compare against it directly. Otherwise frame it as related, concurrent, or orthogonal work.
  16. 7. Do not invent experiments a reviewer asks for. Record them as limitations or future work.
  17. 8. **Limitations are always stated honestly** (this deliberately departs from the original refinement prompt, which told the model to avoid stating limitations).
  18. 9. Keep proposed methods, hypotheses, and planned experiments distinct from actual results. Never describe a proposed experiment as completed, never claim an empirical contribution without supporting data, and never turn an untested hypothesis into a conclusion.
  19. 10. No ghost-authorship deception: drafts are the user's work product to review, edit, and take responsibility for. Remind the user of their institution's AI-use and disclosure policy when a draft is meant for submission.
  20. ## Where files go
  21. - All outputs live in the **active research project**, never in this skill folder.
  22. - Project root = the path given in the arguments, else the current working directory. Confirm it with the user on first use.
  23. - Default layout (create only what the chosen phase needs):
  24. ```
  25. <project>/paper-orchestra/
  26. 00_project_brief.md # phase 1
  27. 01_research_plan.md # phase 1
  28. 02_evidence_matrix.md # phase 2 (+ optional .csv twin)
  29. 02_literature_review.md # phase 2
  30. references.bib # phase 2 (verified entries only)
  31. 03_outline.md # phase 3
  32. 04_sections/<nn>_<name>.md # phase 4
  33. 05_review_report.md # phase 5
  34. 06_latex/ # phase 6 (optional)
  35. worklog.md # append-only log of decisions per phase
  36. ```
  37. - If the user already has a structure (e.g. `paper/`, `thesis/`, `docs/`), propose using it instead.
  38. - **Never overwrite** an existing file without explicit permission. Before writing, check whether the target exists (Glob/Read). If it does, ask: overwrite, write a versioned copy (`_v2`), or append. Default to a versioned copy if the user is unavailable.
  39. - Never delete user files.
  40. ## Phase selection
  41. Parse the first argument (`$ARGUMENTS`) or the user's request:
  42. | Arg | Phase | Needs as input |
  43. |---|---|---|
  44. | `plan` | 1. Research planning | topic/idea, any notes |
  45. | `lit` | 2. Literature review + evidence matrix | research questions or outline |
  46. | `outline` | 3. Paper outline | brief/plan, results, target venue |
  47. | `write` | 4. Section writing | outline, evidence matrix, data |
  48. | `review` | 5. Critical review | an existing draft |
  49. | `latex` | 6. LaTeX preparation (optional) | approved sections, verified .bib |
  50. | `all` / none | Full workflow, phase by phase, with approval gates | - |
  51. | `auto ["topic"]` | Full workflow, all six phases, **no approval gates** - see *Autonomous mode* | a topic (or inferable context) |
  52. Anything other than `auto` uses the approval-based workflow below. Running a single phase is fully supported. If a phase's inputs are missing, say what is missing, offer to run the earlier phase, or proceed with clearly marked assumptions - the user chooses.
  53. ## Phase gates
  54. (Manual modes only. `auto` skips these gates - see *Autonomous mode*.)
  55. Work one phase at a time. At the end of each major phase:
  56. 1. Write the phase's output file(s) and a short entry in `worklog.md`.
  57. 2. Report: what was produced (paths), Verified / Assumption / Missing counts, open questions.
  58. 3. **Ask for approval before starting the next phase** (use AskUserQuestion when available: Approve & continue / Revise this phase / Stop here). Do not chain phases silently.
  59. ## Phase 0 - Intake (always, brief)
  60. - Glob the project for existing materials: `*.md`, `*.tex`, `*.bib`, `*.csv`, `*.json`, `*.ipynb`, `*.pdf`, logs, figure folders. Read what is relevant.
  61. - Establish: research question, contribution claim, audience/venue, page or word limit, citation style, deadline, **literature cutoff date** (default: today), and which phases the user wants.
  62. - Map inputs to PaperOrchestra-style roles: *idea* (method, contributions), *experimental log* (results, ablations, metrics), *template/guidelines* (venue rules), *figures*.
  63. ## Phase 1 - Research planning
  64. Output `00_project_brief.md` and `01_research_plan.md` containing:
  65. - Problem statement, research question(s), hypotheses, and scope boundaries.
  66. - Claimed contributions, each scoped strictly to the evidence the user has (no over-generalisation beyond the datasets/scenarios actually evaluated).
  67. - Methodology summary and evaluation design (data, baselines, metrics, threats to validity).
  68. - Evidence inventory: what results exist, what is missing, what is assumed.
  69. - Literature search strategy, split as in PaperOrchestra:
  70. - **Introduction (macro context):** impact/urgency of the problem, surveys, foundational works. 3-5 queries.
  71. - **Related work (micro, technical):** 2-4 methodology clusters; per cluster: what to investigate, a *limitation hypothesis*, narrow queries to test it, and the *bridge* to the user's approach.
  72. - **Citation hints:** every dataset, tool, framework, metric, standard, and baseline mentioned needs a canonical source. If you do not know the exact source, write `source introducing '<name>'` - never guess authors.
  73. ## Phase 2 - Evidence-based literature review
  74. Source discovery, in priority order:
  75. 1. User's local files (PDFs, .bib, notes) - Read them.
  76. 2. Connected research tools if present (e.g. a scholarly-search MCP such as Consensus, Exa, or a Google Drive/Zotero connector).
  77. 3. WebSearch / WebFetch: publisher pages, DOI resolver (`https://doi.org/<doi>`), arXiv, ACM DL, IEEE Xplore, Semantic Scholar, Crossref, official standards bodies (NIST, ISO, IETF RFCs, MITRE ATT&CK), vendor documentation.
  78. Verification procedure for each candidate source:
  79. - Open the landing page or document. Confirm title, authors, year, venue, and DOI/URL match.
  80. - Confirm the source is published before the cutoff date; later work may only be called concurrent.
  81. - Confirm the specific claim it will support by reading the abstract or the relevant section. Record where (abstract, section, page).
  82. - Deduplicate by normalised title.
  83. - Assign status: `verified`, `partially-verified` (metadata confirmed, claim only from abstract/secondary), `unverified` (found but not opened / paywalled / mismatch), `rejected` (does not support the claim or does not exist as described).
  84. Outputs:
  85. - `02_evidence_matrix.md` - template in `references/templates.md`. Columns: ID, citation key, full reference, DOI/URL, source type, claim(s) supported, where in source, used in section(s), verification status, verified on (date), notes.
  86. - `02_literature_review.md` - synthesis organised by theme/cluster (not a paper-by-paper list): consensus, disagreements, gaps, and how the gap motivates the user's work. Cite matrix IDs/keys only.
  87. - `references.bib` - only `verified` and `partially-verified` entries; BibTeX built from the metadata you confirmed, not from memory.
  88. - A gap list: claims that still need a source.
  89. ## Phase 3 - Paper outline
  90. Output `03_outline.md` (template in `references/templates.md`):
  91. - Section hierarchy following the venue template if provided (no orphan subsections: if X.1 exists, X.2 must too).
  92. - Per subsection: content bullets that point to specific source materials (e.g. "Formalise the scoring rule from `idea.md` section 2"), not generic instructions; the evidence-matrix IDs to cite; and the data files that feed each table or figure.
  93. - Figure/table plan: id (semantic, e.g. `fig_pipeline_overview`), type (plot/diagram/table), data source path, purpose.
  94. - Sizing: approximate words per section against the page/word limit.
  95. - An explicit Limitations subsection and a reproducibility/artifact plan.
  96. ## Phase 4 - Section writing
  97. - Write one section (or a small group) at a time into `04_sections/`, in the user's chosen language and style. Ask which section to start with if unclear; default order: Method -> Experiments/Results -> Related Work -> Introduction -> Conclusion -> Abstract.
  98. - Tables use exact values from the user's data files; cite the file path in a source comment (`<!-- source: results/run3.csv -->`).
  99. - Describe figures only as they actually appear; do not interpret beyond what the data shows.
  100. - Include ablations/analysis of what worked, what did not, and why - only if supported.
  101. - Mark inline: `[CITATION NEEDED: claim]`, `[DATA MISSING: what]`, `[ASSUMPTION: what, why]`.
  102. - Preserve already-approved sections; edit them only for consistency and say what changed. Prefer returning changed passages rather than regenerating whole documents.
  103. ## Phase 5 - Critical review
  104. Act as a rigorous, fair reviewer (adapted from PaperOrchestra's review-driven refinement loop). Output `05_review_report.md` containing:
  105. - Summary; Strengths; Weaknesses; Questions to authors; an overall assessment with a 1-10 score and confidence, and the reasoning behind both.
  106. - The **quality checklist** results (below), each item pass / issue / n/a with location.
  107. - A prioritised revision plan. For each item: addressable by rewriting with existing evidence, or requires new evidence (cannot be fabricated; becomes a limitation or future work).
  108. - Only after approval, apply revisions (at most ~3 review->revise rounds, as in the original loop), logging each change in `worklog.md` (addressed weaknesses, integrated answers, actions taken). Stop early when no material issue remains.
  109. ### Quality checklist
  110. **Methodology**
  111. - Research question, hypotheses, and contributions are explicit and consistent across abstract, intro, and conclusion.
  112. - Method is described in enough detail to re-implement; design choices are justified.
  113. - Baselines, datasets/scenarios, and metrics are appropriate and cited; evaluation matches the claims' scope.
  114. - Threats to validity (internal, external, construct) are discussed.
  115. **Citations**
  116. - Every `\cite`/reference resolves to a `verified` or `partially-verified` matrix row; no orphan or unused keys.
  117. - Each cited source actually supports the sentence it is attached to.
  118. - No post-cutoff work presented as a baseline that was beaten; no superiority claims without direct comparison.
  119. - Quotations are verbatim, short, and located.
  120. **Reproducibility**
  121. - Data sources, versions, configurations, environment, random seeds, and hardware are stated or marked missing.
  122. - Every number traces to a file; tables match the data exactly (spot-check by re-reading the source files or recomputing with code).
  123. - Artifact availability (code, data, scenario definitions) is stated, including restrictions.
  124. **Limitations**
  125. - A dedicated limitations discussion exists and covers scope, data, generalisability, and threats to validity.
  126. - Unanswered reviewer questions needing new experiments are listed honestly.
  127. **Academic integrity**
  128. - No fabricated content; all `[CITATION NEEDED]`, `[DATA MISSING]`, `[ASSUMPTION]` markers are resolved or consciously kept.
  129. - Paraphrases are genuinely re-expressed, not close copies; prior work is credited.
  130. - Ethics: human subjects, sensitive data, or dual-use/security concerns addressed (e.g. responsible disclosure, anonymisation).
  131. - AI-assistance disclosure handled per the venue's or institution's policy.
  132. ## Phase 6 - LaTeX preparation (optional)
  133. - Use the user's venue template if present in the project; otherwise ask, or offer a minimal `article` skeleton. Do not download templates without asking.
  134. - Convert approved sections into `06_latex/main.tex` (+ `sections/*.tex`), using `references.bib`, `booktabs` tables, `\label`/`\ref` for all figures and tables, and figure paths that exist.
  135. - Keep the template preamble intact; check `\begin`/`\end` pairing; keep unresolved markers as visible `\textcolor{red}{...}` notes.
  136. - If `latexmk`/`pdflatex`/`bibtex` already exist, offer to compile and report errors and warnings (undefined citations or references, overfull boxes). Do not install a TeX distribution or any other dependency.
  137. ## Autonomous mode (`auto`)
  138. Invocation: `/paper-orchestra auto "Research Topic"` or `/paper-orchestra auto`. Runs Phases 0-6 end to end **without approval gates**. Every integrity rule above still applies in full; autonomy changes who decides routine choices, never what may be claimed.
  139. ### Topic resolution
  140. 1. Use the quoted topic if given (any further argument is the project path).
  141. 2. Otherwise infer it from the current conversation, then from project context (README, idea/notes files, existing drafts). State the inferred topic in the first progress update and in `research-worklog.md`.
  142. 3. Only if neither yields a clear topic, ask **once**. If still unanswered, stop with status **Blocked**.
  143. ### Defaults for non-critical decisions
  144. Do not stop to ask about these; pick a default, record it under "Defaults applied" in `research-worklog.md`, and continue:
  145. - Venue: generic academic manuscript (Abstract, Introduction, Related Work, Method/Approach, Evaluation or Evaluation Plan, Discussion, Limitations, Conclusion, References).
  146. - Length: about 6,000-8,000 words. Citation style: numeric (`plainnat`/`unsrtnat`). Language: the language of the request.
  147. - Literature cutoff: today. Project root: argument path, else current working directory.
  148. - Section order, figure plan, and wording choices: your judgment, documented.
  149. ### When to stop anyway
  150. Pause only for: a fundamentally ambiguous topic (see above); an action needing authentication, permission, or private resources you cannot reach; or an irreversible or destructive action. Missing data is **not** a reason to stop - it changes the output type (below).
  151. ### Evidence-dependent output type
  152. - **Results present** (logs, CSVs, notebooks with outputs): write a full empirical manuscript from that data.
  153. - **No results**: write a rigorous research proposal / draft. The Evaluation section becomes an *Evaluation Plan* (design, datasets or scenarios, baselines, metrics, analysis) under a visible `PENDING EVALUATION - no results reported` banner; contributions are phrased as proposed; the abstract and conclusion make no empirical claims.
  154. - **Source verification unavailable** (no web access or connectors): continue with local sources only, mark every unchecked reference `unverified`, and keep them out of factual claims.
  155. ### Output layout (auto mode)
  156. ```
  157. <project>/paper-orchestra/
  158. research-plan.md # Phase 1
  159. source-evidence-matrix.md # Phase 2 (matrix template in references/templates.md)
  160. literature-review.md # Phase 2
  161. paper-outline.md # Phase 3
  162. manuscript.md # Phase 4, revised in Phase 5
  163. critical-review.md # Phase 5, one section per round
  164. limitations.md # limitations, threats to validity, reproducibility requirements
  165. research-worklog.md # progress, defaults, decisions, per-phase counts
  166. latex/main.tex # Phase 6
  167. latex/references.bib # Phase 6, verified/partially-verified entries only
  168. ```
  169. Create other files only when genuinely needed. Keep all intermediate artifacts so the run is auditable.
  170. **No overwrites:** before writing, check each target. If it exists, never replace it. If `paper-orchestra/` already holds a previous run, write this run to `paper-orchestra/run-YYYYMMDD-HHMM/` with the same layout; for single existing files, write `<name>.rN.md`. Record which choice was made in the worklog. Within the run, revisions of `manuscript.md` are preserved as `manuscript.r0.md`, `manuscript.r1.md`, ... before each review round edits the current file.
  171. ### Execution
  172. 1. **Phase 0-1:** intake and planning as described above -> `research-plan.md`.
  173. 2. **Phase 2:** search and verify -> `source-evidence-matrix.md`, `literature-review.md`. Aim for enough verified sources to support every claim; a smaller verified set beats a larger unverified one.
  174. 3. **Phase 3:** outline -> `paper-outline.md`.
  175. 4. **Phase 4:** draft the whole manuscript -> `manuscript.md`, with inline `[CITATION NEEDED]`, `[DATA MISSING]`, `[ASSUMPTION]`, and `[PROPOSED]` markers where applicable.
  176. 5. **Phase 5:** up to **three** review-and-revision rounds. Each round: write a review (checklist + scored assessment) to `critical-review.md`, snapshot the manuscript, apply fixes that existing evidence supports, log what was resolved and what was not. Stop early when a round finds no material issue that can be fixed with available evidence. Unresolvable items go to `limitations.md`.
  177. 6. **Phase 6:** generate `latex/main.tex` and `latex/references.bib` from the final manuscript; check `\cite` keys against the .bib and `\begin`/`\end` pairing. If `latexmk`/`pdflatex` already exist, compile once and record the result; never install anything. Then run the final validation: the full quality checklist, plus a search of the manuscript for unresolved markers.
  178. ### Progress updates
  179. After each phase, send one or two lines (phase done, key counts, any default applied). Do not ask for confirmation.
  180. ### Final report
  181. End with (template in `references/templates.md`): research title; research questions; number of `verified` sources (and partially-verified/unverified counts); phases completed; main findings **supported by evidence** (each with its source or data file; none if no results); outstanding evidence and experimental requirements; review issues identified vs. resolved; paths to all generated files; and a final status:
  182. - **Complete** - all claims supported, empirical results present where claimed, no unresolved critical markers.
  183. - **Draft Pending Evidence** - workflow finished but results, sources, or data are missing (e.g. evaluation pending). Never call this Complete.
  184. - **Blocked** - could not proceed (unclear topic, required access unavailable); state what is needed.
  185. ## Tool usage summary
  186. - Glob / Grep / Read for local materials; Write / Edit for outputs (after existence checks).
  187. - WebSearch / WebFetch (or connected scholarly MCPs) for discovery and verification; record the URL actually opened.
  188. - Bash only for local checks, e.g. recomputing a table value, grepping cite keys against the .bib, or compiling LaTeX with tools already installed.
  189. - AskUserQuestion at phase gates and for overwrite decisions (manual modes only); a task list for multi-phase runs, including `auto`.
  190. ## Reference files
  191. - `references/templates.md` - evidence matrix, outline, review report, worklog, limitations, and auto-mode final report templates.
  192. - `references/example-miyar-alert-investigation.md` - short worked example (security alert investigation study).
  193. - `references/provenance.md` - origin and relationship to PaperOrchestra.
README.md · README · 206 lines
  1. # PaperOrchestra Skill for Claude Code
  2. An evidence-first academic research and paper-writing skill for [Claude Code](https://docs.claude.com/en/docs/claude-code/overview), inspired by Google Research's [PaperOrchestra](https://github.com/google-research/paper-orchestra) multi-agent framework.
  3. The skill guides Claude Code through a phased workflow that turns raw research materials (idea notes, experiment logs, data, figures) into a grounded paper draft. It never invents citations or results, and it marks every claim as verified, assumed, or missing.
  4. > **Not an official Google project.** This is an independent adaptation of PaperOrchestra's *methodology*. It contains no PaperOrchestra code and does not run its Python pipeline. See [Attribution](#attribution).
  5. ## What the skill does
  6. `paper-orchestra` is a single Claude Code skill (`SKILL.md` plus reference files). When you invoke it, or when Claude Code decides it fits your request, it:
  7. - plans the research question, contributions, evaluation design, and literature search strategy
  8. - finds and **verifies** sources with the tools available in your session, and records them in a source-evidence matrix
  9. - builds a paper outline linked to evidence and data files
  10. - drafts sections using only verified sources and your own data
  11. - reviews the draft like a critical peer reviewer, against a quality checklist
  12. - optionally prepares a LaTeX version using a template already in your project
  13. Everything it writes goes into your research project, not into the skill folder.
  14. ## Key features
  15. - **Phased workflow with approval gates.** Claude stops after each major phase and asks before moving on.
  16. - **Autonomous mode (`auto`).** Give a topic once and Claude runs all six phases without stopping. It applies documented defaults, runs up to three review-and-revision rounds, and finishes with an honest status: *Complete*, *Draft Pending Evidence*, or *Blocked*.
  17. - **Run one phase or all of them.** For example, review an existing draft without running the earlier phases.
  18. - **Source-evidence matrix.** Each source gets a DOI or URL, the claims it supports, where in the source each claim appears, and a verification status (`verified`, `partially-verified`, `unverified`, `rejected`).
  19. - **Explicit evidence labels.** Content is marked **Verified**, **Assumption**, or **Missing**. Drafts use inline markers such as `[CITATION NEEDED: ...]`, `[DATA MISSING: ...]`, and `[ASSUMPTION: ...]`.
  20. - **No overwrites.** Existing files are never overwritten without your permission.
  21. - **Quality checklist** covering methodology, citations, reproducibility, limitations, and academic integrity.
  22. - **No dependencies.** It uses Claude Code's built-in tools (file reading and writing, search, web search and fetch) and any research connectors you already have.
  23. ## How the workflow works
  24. ```text
  25. Intake -> 1. plan -> 2. lit -> 3. outline -> 4. write -> 5. review -> 6. latex (optional)
  26. ^ approval gate after each phase, or run any single phase directly
  27. ```
  28. 1. **Intake.** Claude scans your project for existing materials (Markdown, LaTeX, BibTeX, CSV, JSON, notebooks, PDFs, logs, figures). It confirms the research question, target venue, length limit, citation style, literature cutoff date, and which phases you want.
  29. 2. **Phases.** Each phase writes its output files and appends to a `worklog.md`. It then reports what was produced, how many items are verified, assumed, or missing, and any open questions.
  30. 3. **Gate.** You choose to approve and continue, revise the phase, or stop.
  31. ## Installation
  32. Claude Code loads personal skills from `~/.claude/skills/<skill-name>/SKILL.md`, and project skills from `.claude/skills/<skill-name>/SKILL.md` inside a repository. The repository root of this project *is* the skill folder, so you can clone it straight into place.
  33. The extra repository files (`README.md`, `LICENSE`, `.gitignore`) sit next to `SKILL.md` and don't affect the skill.
  34. ### Linux and macOS
  35. Personal install (available in all your projects):
  36. ```bash
  37. mkdir -p ~/.claude/skills
  38. git clone https://github.com/Ziyad-Altamimi/paper-orchestra-claude-skill.git ~/.claude/skills/paper-orchestra
  39. ```
  40. Project install (shared with collaborators through that project's repository):
  41. ```bash
  42. mkdir -p .claude/skills
  43. git clone https://github.com/Ziyad-Altamimi/paper-orchestra-claude-skill.git .claude/skills/paper-orchestra
  44. ```
  45. ### Windows (PowerShell)
  46. Personal install:
  47. ```powershell
  48. New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills" | Out-Null
  49. git clone https://github.com/Ziyad-Altamimi/paper-orchestra-claude-skill.git "$env:USERPROFILE\.claude\skills\paper-orchestra"
  50. ```
  51. Project install, run from your project root:
  52. ```powershell
  53. New-Item -ItemType Directory -Force ".claude\skills" | Out-Null
  54. git clone https://github.com/Ziyad-Altamimi/paper-orchestra-claude-skill.git ".claude\skills\paper-orchestra"
  55. ```
  56. The target folder name must be `paper-orchestra` so that it matches the skill's `name`. Start a new Claude Code session after installing. To update later, run `git pull` inside the skill folder.
  57. ## Usage
  58. Run the full workflow, phase by phase:
  59. ```text
  60. /paper-orchestra
  61. ```
  62. Run everything autonomously from one topic, with no approval gates:
  63. ```text
  64. /paper-orchestra auto "Counterfactual evidence checks for SOC alert investigation"
  65. /paper-orchestra auto
  66. ```
  67. Without a topic, Claude infers it from the conversation or project files and asks once only if it can't. Auto mode writes `research-plan.md`, `literature-review.md`, `source-evidence-matrix.md`, `paper-outline.md`, `manuscript.md`, `critical-review.md`, `limitations.md`, `research-worklog.md`, and `latex/main.tex` + `latex/references.bib` into `paper-orchestra/`. If a previous run exists, it uses a new `run-YYYYMMDD-HHMM/` folder instead. If no experimental results exist, the output is a research proposal with the evaluation clearly marked as pending, never invented results.
  68. Run a single phase:
  69. ```text
  70. /paper-orchestra plan
  71. /paper-orchestra lit
  72. /paper-orchestra review
  73. ```
  74. ### Choosing the research project directory
  75. The second argument is the project path. If you leave it out, the skill uses Claude Code's current working directory, and it confirms the location with you the first time.
  76. ```text
  77. /paper-orchestra plan ./my-thesis
  78. /paper-orchestra review ~/research/alert-triage-study
  79. ```
  80. By default, outputs are written to a `paper-orchestra/` folder inside the project:
  81. ```text
  82. <project>/paper-orchestra/
  83. 00_project_brief.md
  84. 01_research_plan.md
  85. 02_evidence_matrix.md
  86. 02_literature_review.md
  87. references.bib
  88. 03_outline.md
  89. 04_sections/
  90. 05_review_report.md
  91. 06_latex/
  92. worklog.md
  93. ```
  94. If your project already has a structure such as `paper/`, `thesis/`, or `docs/`, the skill offers to use that instead.
  95. You don't have to use the slash command. The skill's description lets Claude Code pick it up automatically for requests like "do a literature review for my paper" or "review this draft critically".
  96. ## Workflow phases
  97. | Phase | Purpose | Main outputs |
  98. |---|---|---|
  99. | `plan` | **Research planning.** Problem, research questions, hypotheses, scoped contributions, evaluation design, evidence inventory, and a literature search strategy (broad context for the introduction; methodology clusters with limitation hypotheses for related work). | `00_project_brief.md`, `01_research_plan.md` |
  100. | `lit` | **Literature review and evidence matrix.** Discovers sources from local files, connected research tools, and the web. Checks each source's metadata, publication date against the cutoff, and the specific claim it supports. | `02_evidence_matrix.md`, `02_literature_review.md`, `references.bib` |
  101. | `outline` | **Paper structure.** Section hierarchy (following a venue template if you provide one), content bullets tied to source materials, citations per subsection, a figure and table plan, word budget, and limitations and reproducibility sections. | `03_outline.md` |
  102. | `write` | **Evidence-based drafting.** Writes sections one at a time. Uses exact values from your data files, cites only verified sources, and marks gaps inline. | `04_sections/*.md` |
  103. | `review` | **Critical review.** Strengths, weaknesses, questions, a score with rationale, checklist results, and a prioritized revision plan. Revisions are applied only after your approval, for up to about three rounds. | `05_review_report.md` |
  104. | `latex` | **LaTeX preparation (optional).** Converts approved sections into LaTeX using your venue template or a minimal `article` skeleton. Offers to compile only if a TeX toolchain is already installed. | `06_latex/` |
  105. Use `all`, or no phase argument, for the full workflow with approval gates, or `auto` for the full workflow without them.
  106. ## Example research use cases
  107. - Turning experiment logs and notes into a conference or workshop paper draft
  108. - Building a verified literature review and BibTeX file for a thesis chapter
  109. - Critically reviewing an existing manuscript before submission
  110. - Planning a study's evaluation design and threats to validity before running experiments
  111. - Preparing a security-operations study. `references/example-miyar-alert-investigation.md` shows a short worked example: a study of investigating a Wazuh alert on a Windows endpoint, with placeholder values only.
  112. ## Project structure
  113. ```text
  114. paper-orchestra-claude-skill/
  115. ├── SKILL.md # Skill definition (frontmatter + workflow)
  116. ├── README.md # This file
  117. ├── LICENSE # MIT
  118. ├── .gitignore
  119. └── references/
  120. ├── templates.md # Evidence matrix, outline, review, worklog templates
  121. ├── example-miyar-alert-investigation.md # Short worked example
  122. └── provenance.md # Origin and relationship to PaperOrchestra
  123. ```
  124. ## Academic integrity and evidence verification
  125. The skill's integrity rules override requests for speed or polish:
  126. - It never fabricates references, authors, DOIs, URLs, quotations, statistics, results, figures, or citation keys.
  127. - Every citation must match a `verified` or `partially-verified` row in the evidence matrix. Anything else is flagged as `[CITATION NEEDED]`.
  128. - Every number must trace to a file you provided. Anything else is flagged as `[DATA MISSING]`.
  129. - It doesn't claim to beat a cited work unless your own results compare against it directly.
  130. - Reviewer requests for new experiments are recorded as limitations or future work, never invented.
  131. - Limitations are always stated.
  132. - Drafts are your work product to check and take responsibility for. Follow your institution's or venue's policy on disclosing AI assistance.
  133. Verification depends on what Claude can actually open in your session. Paywalled or unreachable sources stay `unverified` until you supply them.
  134. ## Limitations
  135. - This is a prompt-based workflow, not software. Output quality depends on the model, your materials, and the tools available in your Claude Code session.
  136. - Literature discovery is limited to your local files, any research connectors you have set up, and web search and fetch. It doesn't replace a systematic database search.
  137. - Claude can still make mistakes. Check every citation and number before you submit anything.
  138. - LaTeX compilation works only if `latexmk`, `pdflatex`, or `bibtex` is already installed. The skill does not install dependencies.
  139. - It doesn't reproduce PaperOrchestra's plotting agent, automated scoring (autoraters), or reported benchmark results.
  140. ## Attribution
  141. This skill is an independent adaptation inspired by **PaperOrchestra** by Google Research:
  142. - Repository: <https://github.com/google-research/paper-orchestra> (Apache License 2.0)
  143. - Paper: Yiwen Song, Yale Song, Tomas Pfister, Jinsung Yoon. *PaperOrchestra: A Multi-Agent Framework for Automated AI Research Paper Writing.* arXiv:2604.05018, 2026.
  144. Only the high-level methodology was adapted: outlining, literature review with verification, section writing, review-driven refinement, and formatting. No source code, prompts, templates, or other files from PaperOrchestra are included. This repository is **not affiliated with, endorsed by, or officially supported by Google** or the PaperOrchestra authors. See [`references/provenance.md`](references/provenance.md) for what was adapted and where this skill deliberately differs.
  145. ## License
  146. Released under the [MIT License](LICENSE). PaperOrchestra itself is licensed separately under the Apache License 2.0 by Google LLC. Its license is not affected by, and does not apply to, the files in this repository.

Ratings and comments

Sign in to rate this skill.

Sign in

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