# Paper Summary

> Deterministic PDF-to-markdown paper summarization for papercli workflows. Given one paper PDF or a directory of paper PDFs, produce schema-conformant markdown summaries and optionally update summarized_ids.txt.

- Skill: `jimezsa/paper-summary` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add jimezsa/paper-summary`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jimezsa/paper-summary/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: jimezsa (https://skillmd.com/u/jimezsa)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jimezsa/paper-summary

---


# Paper Summary Skill

Use this skill when PDFs have already been downloaded and the next step is to create deterministic `<run-folder>/pdf/<safe_id>.md` summaries from those PDFs.

For precise follow-up QA after the summaries exist, switch to the shared `pageindex-grounded` skill instead of stretching this skill into ad hoc question answering.

This skill is the canonical summary step for:

- `SKILLS/fast-research/SKILL.md`
- `SKILLS/pro-research/SKILL.md`
- `SKILLS/deep-research/SKILL.md`

## Update This Skill

Only do this if the user explicitly asks to update this skill from the GitHub repo.

To refresh this skill directly from the GitHub repo:

```bash
curl -fsSL https://raw.githubusercontent.com/jimezsa/papercli/main/SKILLS/paper-summary/SKILL.md \
  -o SKILLS/paper-summary/SKILL.md
curl -fsSL https://raw.githubusercontent.com/jimezsa/papercli/main/SKILLS/paper-summary/references/summary_schema.md \
  -o SKILLS/paper-summary/references/summary_schema.md
curl -fsSL https://raw.githubusercontent.com/jimezsa/papercli/main/SKILLS/paper-summary/scripts/gemini_parallel_summary.py \
  -o SKILLS/paper-summary/scripts/gemini_parallel_summary.py
```

## Mission

Given one paper PDF or a directory of paper PDFs:

1. Read the PDFs directly with Gemini.
2. Produce one markdown summary per paper that follows the canonical schema in `references/summary_schema.md`.
3. Write each summary as `<safe_id>.md`, next to `<safe_id>.pdf`, unless an explicit output directory is provided.
4. Optionally append original paper IDs to `<run-folder>/meta/summarized_ids.txt`.

## Prerequisites

- `python3` is installed and available in `PATH`.
- `google-genai` is installed: `python3 -m pip install google-genai`
- `GEMINI_API_KEY` is set in the environment.
- Network access is available when running the Gemini script.
- The PDFs already exist locally.
- Optional metadata JSON files exist in `<run-folder>/meta/<safe_id>.json`.

## Required Inputs

- A single PDF via `--pdf`, or a directory of PDFs via `--pdf-dir`.
- Optional `--metadata-dir` so the script can recover original paper IDs and metadata fallbacks.
- Optional `--summarized-ids` file to append successful original paper IDs.
- Optional `--failures-tsv` file to record summary failures in the same ledger used by the research skills.
- The active research run folder, normally `research/<YYYY-MM-DD>-<topic-slug>/`, when this is called from `fast-research`, `pro-research`, or `deep-research`.

## Hard Requirements

- Use the canonical schema from `references/summary_schema.md` unchanged.
- Output markdown only. Do not wrap the summary in code fences.
- Keep figures, tables, equations, captions, and page anchors as first-class evidence.
- Use metadata only as fallback and label it clearly.
- If evidence is missing, preserve the required missing-evidence labels instead of guessing.
- Do not silently skip failures. Either rerun the paper or record the failure upstream.

## Workflow

### 1. Confirm local inputs

- Verify the target PDF exists.
- When possible, keep PDF names aligned with the `safe_id` convention already used by the research skills.
- If metadata exists, keep the matching JSON at `<run-folder>/meta/<safe_id>.json`.

### 2. Run the Gemini batch summarizer

When this skill is called from a research run, set `RUN_ROOT` to the active run folder first:

```bash
RUN_ROOT="research/<YYYY-MM-DD>-<topic-slug>"
```

Single paper:

```bash
python3 SKILLS/paper-summary/scripts/gemini_parallel_summary.py \
  --pdf "$RUN_ROOT/pdf/<safe_id>.pdf" \
  --metadata-dir "$RUN_ROOT/meta" \
  --summarized-ids "$RUN_ROOT/meta/summarized_ids.txt" \
  --failures-tsv "$RUN_ROOT/meta/failures.tsv"
```

Batch mode:

```bash
python3 SKILLS/paper-summary/scripts/gemini_parallel_summary.py \
  --pdf-dir "$RUN_ROOT/pdf" \
  --metadata-dir "$RUN_ROOT/meta" \
  --summarized-ids "$RUN_ROOT/meta/summarized_ids.txt" \
  --failures-tsv "$RUN_ROOT/meta/failures.tsv" \
  --concurrency 4
```

Useful flags:

- `--model <name>`: override the default Gemini model.
- `--output-dir <dir>`: write summaries somewhere other than next to the PDFs.
- `--overwrite`: regenerate existing `.md` summaries.
- `--concurrency <n>`: lower this if the API starts rate limiting.

### 3. Review outputs

- Each successful run should create `<run-folder>/pdf/<safe_id>.md`.
- Check that the output preserves the canonical headings and evidence anchors.
- If a paper failed, inspect stderr, then rerun just that paper or keep the failure recorded in `<run-folder>/meta/failures.tsv`.

## Output Contract

- One markdown summary per processed PDF.
- Each summary follows the canonical schema in `references/summary_schema.md`.
- Successful runs may append the original paper ID to `<run-folder>/meta/summarized_ids.txt` when metadata is available.

## Canonical Assets

- Summary schema: `SKILLS/paper-summary/references/summary_schema.md`
- Batch summarizer: `SKILLS/paper-summary/scripts/gemini_parallel_summary.py`