Research

research — OpenAlex search + full-text reading

Find scholarly works on OpenAlex (free, no API key) and convert their open-access full text to Markdown with markitdown, then read only the parts you need.

Tooling

Run the bundled CLI with the skill's own virtualenv python:

~/.claude/skills/research/.venv/bin/python ~/.claude/skills/research/oa.py  ...

The venv is required (markitdown lives there). If import markitdown fails, install it: ~/.claude/skills/research/.venv/bin/pip install 'markitdown[pdf]'.

No email or other identifier is ever sent to OpenAlex. The normal API is free and keyless. If the user has an OpenAlex Premium key, save it once with oa.py set-key (stored at ~/.claude/skills/research/.api_key, mode 600); it is then sent only as the api_key query parameter. It can also come from the OPENALEX_API_KEY env var or a per-call --api-key flag. The skill works fully without any key — the key only matters for Premium rate limits. If the user mentions an OpenAlex API key, run set-key for them.

Workflow

1. Search to find candidate works:

`` oa.py search "graph neural networks for drug discovery" --year-from 2021 --sort cited_by_count:desc --limit 10 --abstracts ` Each result shows an id=W…, year, citation count, and an [OA+PDF] / [OA] / [closed] flag. Only [OA+PDF]` works can be fetched in full; for others you still get the abstract.

Useful options: --filter passes raw OpenAlex filters (repeatable), e.g. --filter authorships.author.id:A5023888391 for an author's works, or --filter type:review. --oa-only restricts to open access. --recent N keeps only the last N years. --json emits machine-readable output.

1. Expand the citation graph from any known work — the fastest way to the

research frontier: `` oa.py cites W2566079294 --recent 2 --limit 20 # newer work building on it oa.py refs W2566079294 # the work's own foundations oa.py related W2566079294 # concept neighbours ` cites defaults to newest-first, so it surfaces the cutting edge that grew out of a seminal paper. (refs/related` depend on OpenAlex having parsed the work — often sparse for raw arXiv preprints; published versions are richer.)

1. Fetch the full text of a chosen work to disk:

`` oa.py fetch W2741809807 ` Accepts an OpenAlex id, a DOI (10.7717/peerj.4375 or doi:…), or a url. It downloads the OA PDF, converts it to Markdown, saves it to ./research-papers/.md (override with --out-dir`), and prints metadata plus an outline with line numbers and an approximate token count.

1. Read only what you need. Do not read the whole file by default —

that defeats the point. Use the outline to Read the file with an offset and limit for a specific section, or Grep the file for a term. Pull the Methods or one Results subsection, not the entire 40-page paper.

Guidance

• For a literature survey, run a few searches with different phrasings/sorts,

collect the strongest [OA+PDF] works, fetch them, and read the relevant sections before synthesizing.

• Cite properly. Use the front-matter in each saved .md (title, authors,

year, DOI, OpenAlex id) when you reference a paper. Don't invent findings — quote or paraphrase from the fetched text and point to the section.

• If full text isn't open access ([closed] or no PDF), say so and work from

the abstract; offer to look for an alternative open version.

• markitdown extracts the PDF text layer (no OCR), so scanned papers come out

empty/garbled — flag that if the text looks broken. It also mangles dense two-column layouts (words run together, abstracts become broken tables); running prose sections usually survive, so prefer reading those, and when a passage looks corrupted say so rather than quoting noise. For a cleaner source, prefer an HTML version when one exists (arXiv HTML, PubMed Central) by passing its url to fetch.

• Saved papers persist in research-papers/; reuse an existing .md instead of

re-fetching the same work.

Use in an autoresearch / agent loop

Designed to plug into autonomous research loops (e.g. the program.md swarm in vast-autoresearch) where agents need fresh, implementable ideas — not prose.

• Harvest ideas from abstracts, not PDFs. In a loop the idea-dense signal is

the abstract. search "" --recent 2 --abstracts --json --limit 15 returns ~15 recent techniques in parsable JSON for the cost of one call — no PDF downloads. Only fetch a full paper when you've decided to implement a specific method and need its exact recipe (the saved .md then becomes the reference while you write code).

• --json everywhere so a subagent can parse `results[].{id,title,abstract,

date} deterministically and dedupe by id across rounds (track seen ids in findings.md`).

• Anchor + expand for the frontier. Find one strong paper for a focus area,

then cites --recent 1 --json to pull the newest work building on it. This is how you reach the cutting edge instead of re-finding canon.

• Map each loop focus to a query. For the slot focuses in vast-autoresearch:

optimizer → "learning rate schedule warmup Muon AdamW language model"; architecture → "transformer architecture depth width normalization activation language model"; data/throughput → "efficient pretraining batch size sequence packing throughput"; regularization/init → "weight initialization dropout embedding regularization transformer". Add --recent 2 --abstracts --json.

• Filter for the constraints before suggesting. The loop edits a single

train.py in pure PyTorch with a fixed dependency set and a 5-minute budget. Prefer techniques that are self-contained, dependency-free, and cheap to try; drop anything needing new packages, huge compute, or multi-file infra. Lead with the one-line change an agent can drop into the training loop.

Honest boundary: OpenAlex covers published papers and arXiv preprints well, but not GitHub-only / blog-only results (e.g. modded-nanogpt speedrun records, brand-new tricks shared only in repos or on X). For those, web search is the right tool — use this skill for the peer-reviewed/arXiv substrate and web search for the bleeding edge, and say which is which.

Drop-in program.md snippet

Add under the "NEVER STOP / if ideas run dry" clause so subagents mine the literature for their focus area:

When ideas in your focus area run dry, query the literature before guessing.
Run (no email is sent; OpenAlex is keyless):

  ~/.claude/skills/research/.venv/bin/python ~/.claude/skills/research/oa.py \
      search "" --recent 2 --abstracts --json --limit 15

Skim the returned abstracts for a concrete, self-contained technique that fits a
single-file pure-PyTorch train.py and the 5-minute budget (no new deps). To go to
the frontier, pick one strong paper and run `... oa.py cites  --recent 1
--json`. Pick ONE idea, note its source (title + OpenAlex id) in findings.md, and
implement it as your next experiment. If a method needs the exact recipe, fetch
it: `... oa.py fetch ` and read only the Method section. Skip anything
needing new packages or infra — OpenAlex won't have GitHub-only speedrun tricks;
use web search for those.

Source & license

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

• Author: bednarjosef
• Source: bednarjosef/claude-research-skill
• License: MIT

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