# 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.

- **Type:** Skill
- **Install:** `agentstack add skill-jimezsa-opencolab-paper-summary`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jimezsa](https://agentstack.voostack.com/s/jimezsa)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jimezsa](https://github.com/jimezsa)
- **Source:** https://github.com/jimezsa/opencolab/tree/main/projects/SKILLS/paper-summary
- **Website:** https://opencolab.ai/

## Install

```sh
agentstack add skill-jimezsa-opencolab-paper-summary
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Paper Summary Skill

Use this skill when PDFs have already been downloaded and the next step is to create deterministic `/pdf/.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 `.md`, next to `.pdf`, unless an explicit output directory is provided.
4. Optionally append original paper IDs to `/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 `/meta/.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/-/`, 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 `/meta/.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/-"
```

Single paper:

```bash
python3 SKILLS/paper-summary/scripts/gemini_parallel_summary.py \
  --pdf "$RUN_ROOT/pdf/.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 `: override the default Gemini model.
- `--output-dir `: write summaries somewhere other than next to the PDFs.
- `--overwrite`: regenerate existing `.md` summaries.
- `--concurrency `: lower this if the API starts rate limiting.

### 3. Review outputs

- Each successful run should create `/pdf/.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 `/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 `/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`

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jimezsa](https://github.com/jimezsa)
- **Source:** [jimezsa/opencolab](https://github.com/jimezsa/opencolab)
- **License:** MIT
- **Homepage:** https://opencolab.ai/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jimezsa-opencolab-paper-summary
- Seller: https://agentstack.voostack.com/s/jimezsa
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.