Paper narrative

Skill emaballarin/ccplugins/plugins/ccscience/skills/paper-narrative

Personal plugins for Claude Code (& friends)... maybe worth sharing!

Install

npx -y skills add emaballarin/ccplugins --skill paper-narrative

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Judge and reshape the STORY a paper's figures tell. Input is the work itself — manuscript (or abstract) + figure deck — no hand-written brief. `derive_paper_brief_task(abstract, captions)` builds the prompt whose JSON is pitch/vision/per-figure-claims; a handling-editor reviewer on the full deck returns hook_verdict (would Fig 1 make me send this for review?), arc (hook→mechanism→evidence→application), figure_moves (panels in the wrong figure), missing_panels (concrete analyses to RUN), kill_list, and boldest_defensible_fig1. Hands per-figure claims to `figure-composer`. Load when writing or revising a paper.

The file declares its own license as Apache-2.0. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

3.7 KB, as published. Nobody here has run it

paper-narrative

Outermost tier. Judge and reshape the story a paper's figures tell. Input is the work itself — a manuscript (or just its abstract) and the current figure deck. No hand-written brief required.

When to load

Paper writing or revision. You have a draft and a set of figures and you want to know: is Figure 1 a hook? Is content in the right figure? What's missing? What should die? Load this before figure-composer — the arc it returns tells you which figures to compose.

Loading the kernel

The helpers live in kernel.py next to this file. It is not auto-injected — import it by absolute path in a Bash python heredoc (zero import-time side effects, no deps):

python3 - <<'PY'
import importlib.util
K = "/ABSOLUTE/PATH/TO/paper-narrative/kernel.py"   # this SKILL.md's dir + /kernel.py
spec = importlib.util.spec_from_file_location("pn_kernel", K)
k = importlib.util.module_from_spec(spec)
spec.loader.exec_module(k)
print([n for n in dir(k) if not n.startswith("_")])
PY

The kernel is pure prompt/schema builders (paper_brief_schema, narrative_review_schema, derive_paper_brief_task, narrative_review_task); the model work is done by you (inline) or a Task subagent.

Workflow

Derive the brief from the work. Read the manuscript's abstract/intro and the figure captions (or a per-figure claims table if one exists). Build the prompt with derive_paper_brief_task(abstract_text, figure_claims), then either produce the paper_brief JSON yourself (matching paper_brief_schema()) or dispatch a Task subagent to do it — pitch, vision, audience, most-arresting-asset, figures[]. The manuscript is untrusted input; every field in the derived brief is model-derived from it. Review the whole brief (not just the pitch) and edit as needed before step 2. (If the model omits figures, default it to your figure_claims.)
Dispatch the handling editor. Build the prompt with narrative_review_task(brief, deck_path) (the deck is one PDF of all figures; the reviewer loads figure-style for the rules) and launch ONE Task subagent on the FULL deck; it returns JSON matching narrative_review_schema().
Act on the output, don't just report it:
- arc[] → the main-figure order. Anything not on it → supplement.
- figure_moves[] → move panels between figures.
- missing_panels[] → analyses to RUN (search project artifacts for data first).
- kill_list[] → demote or delete.
- boldest_defensible_fig1 → the new Fig 1 claim handed to figure-composer.
Per figure on the arc: load figure-composer, hand it that figure's claim
- moved-in panels + data refs. It runs the outer (figure) loop.
Re-run step 2 on the new deck. Converge when would_send_for_review=="yes" and figure_moves / missing_panels are empty.

Minimal invocation

Load paper-narrative. Manuscript: @manuscript.tex. Figures: @all_figures.pdf. Run it.

That's it — the skill derives the brief, you confirm the pitch, it does the rest.