# Citation Survey

> Survey citing or referenced papers for a given seed paper using OpenAlex API. Use when the user asks to find follow-up papers, citing papers, references, or related literature for a specific paper identified by DOI or arXiv ID. Also use when asked to check prior work, search for related publications, or build a literature survey around a specific paper.

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

---


# Citation Survey Skill

Survey citing or referenced papers using the OpenAlex API.

All paths below are relative to this skill's base directory. Construct the full path by prepending the base directory shown at the top of this skill's context.

## Usage

### Find papers that cite a given work

```bash
uv run <base-dir>/scripts/citation_survey.py citing --doi <DOI>
uv run <base-dir>/scripts/citation_survey.py citing --arxiv <ARXIV_ID>
```

### Find references of a given work

```bash
uv run <base-dir>/scripts/citation_survey.py refs --doi <DOI>
```

### Filter results by keywords in title/abstract

```bash
uv run <base-dir>/scripts/citation_survey.py citing --doi <DOI> --filter "keyword1,keyword2"
```

### Save results to JSON

```bash
uv run <base-dir>/scripts/citation_survey.py citing --doi <DOI> --output results.json
```

### Show abstracts

```bash
uv run <base-dir>/scripts/citation_survey.py citing --doi <DOI> --verbose
```

## Options

- `direction`: `citing` (papers that cite this work) or `refs` (references of this work)
- `--doi`: DOI of the seed paper
- `--arxiv`: arXiv ID of the seed paper (alternative to --doi)
- `--filter`: Comma-separated keywords to filter by title/abstract
- `--max-results`: Maximum number of results (default: 2000)
- `--output`: Save results to JSON file
- `--verbose`: Show abstracts in output
- `--api-key`: OpenAlex API key (supported, but leaks into shell history/process lists)
- `--api-key-file`: Read OpenAlex API key from a file

## Examples

Find papers citing Hackl et al. (2020) about Kähler geometry:
```bash
uv run <base-dir>/scripts/citation_survey.py citing --doi 10.21468/SciPostPhys.9.4.048 --filter "variational principle,kähler,neural quantum"
```

Find references of a paper by arXiv ID:
```bash
uv run <base-dir>/scripts/citation_survey.py refs --arxiv 2004.01015
```

## API Key

OpenAlex API requires an API key (free account at https://openalex.org/settings/api).
Prefer `OPENALEX_API_KEY` or `--api-key-file`.
`--api-key` is still supported, but command-line secrets may be visible in shell history or process listings.
The script works without a key but with stricter rate limits.

## Notes

- Uses OpenAlex API (free tier available)
- Rate limiting: 0.15s delay between paginated requests
- Network, timeout, and HTTP errors are reported as short user-facing messages instead of Python tracebacks
- Abstract reconstruction from inverted index (OpenAlex format)
- For arXiv-only papers, DOI resolution may fail; use --arxiv instead