Skip to content
Get packs

Guide · Agent skill

How to use the OpenAlex Academic Search agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The openalex skill lets an AI agent search the OpenAlex open academic database and return structured paper details such as authors, venue, citation counts, open-access links, abstracts, topics and keywords. It is aimed at researchers doing literature reviews, students building reference lists with DOIs and affiliations, and anyone assembling a filtered dataset of papers. By the end of this guide you will know what the skill does, how to install it, how to phrase requests that trigger it, and what it needs to run.

OpenAlex Academic Searchwanshuiyin/Auto-claude-code-research-in-sleep · MIT

Quick start

  1. 1Download and unzip. Download the openalex ZIP from this page and unzip it so the folder containing SKILL.md is ready to place.
  2. 2Place the skill folder. Move it into ~/.claude/skills/ for personal use, into a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
  3. 3Install requests. Run pip install requests with Python 3.7 or newer.
  4. 4Set optional variables. Export OPENALEX_API_KEY and OPENALEX_EMAIL in your shell, then start Claude Code so the helper inherits them.
  5. 5Confirm the helper is found. Make sure openalex_fetch.py resolves from .aris/tools/, tools/, or the ARIS repository location; rerun the ARIS install script if it does not.
  6. 6Ask for a search. Use a phrase like search OpenAlex for a topic, adding year, type, open-access or citation filters as needed.

What is an agent skill and what does the openalex skill do?

An agent skill is a folder containing a SKILL.md file that tells an AI agent how to perform a specific task. When a request matches the skill's description, the agent follows the instructions in that file, which here include running a helper script that queries the OpenAlex API.

Once installed, the skill can search OpenAlex for papers matching a topic and filter them by year, work type, open-access status, minimum citation count and sort order. It can also look up one specific paper by its DOI or its OpenAlex ID.

  • Topic search with up to 10 results by default (up to 20 with a max override)
  • Filters for publication year, work type, open access, minimum citations and sort order
  • Lookup of a single work by DOI or OpenAlex work ID
  • Structured fields including authors, venue, citation count, open-access status and PDF link, DOI, abstract, top topics and top keywords

Install the openalex skill from its ZIP file

Download the ZIP for the openalex skill from this directory page, then unzip it. The skill is a folder whose main file is SKILL.md. Place that folder in one of the locations below.

For a personal install available in all your projects, put it in ~/.claude/skills/. For a single project, put it in the project's .claude/skills/ folder. If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.

  • Personal: ~/.claude/skills/ (available across projects)
  • Project: .claude/skills/ inside the project folder (available only there)
  • Claude apps: Settings → Capabilities → Skills, then upload

Install the Python requirements and set optional keys

The helper script needs Python 3.7 or newer and the requests library. Install requests with pip before using the skill.

An OpenAlex API key and an email address are optional. The key raises your rate limits, and the email gives you access to OpenAlex's polite pool, which the source describes as faster response times with no registration needed. Set the variables in the same shell before you start Claude Code, because the helper reads them from its process environment. The source warns that exporting them in a separate tool shell does not update an already running host.

  • Python 3.7+ is required
  • requests is required: pip install requests
  • OPENALEX_API_KEY is optional and recommended for higher limits
  • OPENALEX_EMAIL is optional and gives access to the polite pool
pip install requests export OPENALEX_API_KEY='your-key-here' export OPENALEX_EMAIL='your-email@example.com' claude

Make sure the helper script can be found

The skill relies on a helper script named openalex_fetch.py. It looks for this file in .aris/tools/, then tools/ in the current project, then in an ARIS repository location resolved from the ARIS_REPO variable or from ~/.aris/repo. If the script is not found, the skill stops with an error rather than falling back to a built-in method.

If you see that error, the source suggests rerunning tools/install_aris.sh or smart_update.sh, exporting ARIS_REPO, or copying the helper into tools/.

  • Searched locations: .aris/tools/, tools/, $ARIS_REPO/tools/, or via ~/.aris/repo
  • Fix options: rerun tools/install_aris.sh or smart_update.sh, export ARIS_REPO, or copy openalex_fetch.py into tools/

Trigger the skill with natural requests

The skill's description lists phrases that should activate it: "openalex search", "search openalex" and "open citation graph". You can also ask for comprehensive academic metadata beyond arXiv or Semantic Scholar. You can phrase requests in plain language and add filters as part of the request.

You can also call the skill directly with a query and optional overrides appended after an em dash, as shown in the source.

  • "Search OpenAlex for papers on retrieval-augmented generation from 2023 onward, sorted by citations"
  • "Use openalex to find open-access articles on graph neural networks with at least 50 citations"
  • "Look up the OpenAlex record for DOI 10.1109/TWC.2024.1234567"
  • Direct form: /openalex "topic" — year: 2020-2023 — max: 20
/openalex "topic" — max: 20 /openalex "topic" — year: 2023- /openalex "topic" — type: article /openalex "topic" — open-access /openalex "topic" — min-citations: 50 /openalex "topic" — sort: citations

Run example searches and lookups

The helper script accepts a search command with the query in quotes, and a work command that takes a DOI or an OpenAlex ID. Filters are passed as flags. The first example below runs a basic search capped at 10 results. The second adds several filters. The last two show lookups by DOI and by OpenAlex ID.

Results come back as structured JSON. The agent then presents them as a table with title, venue, year, citations and open-access status, and lists the DOI, OpenAlex ID, open-access link, topics and an abstract summary for each paper.

  • Filter types accepted: article, preprint, book, book-chapter, dataset, dissertation
  • Open-access statuses returned: gold, green, bronze, hybrid, closed
  • Abstracts are shown as the first 200 characters or the full text, per the skill's presentation rules
python3 "$OPENALEX_FETCHER" search "QUERY" --max 10 python3 "$OPENALEX_FETCHER" search "QUERY" --max 10 \ --year 2023- \ --type article \ --open-access \ --min-citations 20 \ --sort citations python3 "$OPENALEX_FETCHER" work "10.1109/TWC.2024.1234567" python3 "$OPENALEX_FETCHER" work "W2741809807"

Know the safety notes: scripts and network access

This skill runs scripts and uses the network. Its allowed tools include running shell commands, reading files and writing files. The helper script sends requests to the OpenAlex API, and the skill reads your OPENALEX_API_KEY and OPENALEX_EMAIL values from the environment when they are set.

The source notes that the helper does not automatically load a .env file. If you store credentials in one, load it explicitly in your shell before starting the host. Review the helper script before running it if you need to confirm what it does.

  • Runs scripts: yes (the helper openalex_fetch.py via python3)
  • Uses network: yes (queries the OpenAlex API)
  • Reads environment variables OPENALEX_API_KEY and OPENALEX_EMAIL when set
  • Does not auto-load .env files

Tips for better results

Use the work command when you already have a DOI, since it returns that exact record. Use filters to narrow large topics rather than asking for more results. The skill suggests pairing OpenAlex with other sources: arXiv for the latest preprints, Semantic Scholar for published venue papers, and a general web search for cutting-edge work.

Because the skill returns an email address and API key only as environment settings, keep credentials in your shell and not in shared files.

  • Use DOI or OpenAlex ID lookups for a known paper
  • Combine year, type and citation filters to build a focused dataset
  • For very recent preprints, use arXiv or a general web search instead
  • The skill suggests follow-ups such as /semantic-scholar with a DOI and /arxiv with an arXiv ID

What people use it for

  • Building a literature review table with citation counts and open-access links in one place
  • Compiling a reference list with DOIs and author affiliations
  • Creating a dataset of papers filtered by year, work type or minimum citations
  • Looking up the OpenAlex record for a paper you already have a DOI for

Frequently asked questions

Is the openalex skill free to use?

The source says OpenAlex is fully open and needs no API key for basic use. It lists an optional API key with a free tier and describes an email address for the polite pool as needing no registration. The skill itself is released under the MIT licence.

What do I need to install before using the openalex skill?

You need Python 3.7 or newer and the requests library, installed with pip install requests. The helper script openalex_fetch.py must also be resolvable from the ARIS repository layout. An API key and email are optional.

Where do I put the openalex skill folder?

Place it in ~/.claude/skills/ for use across all projects, or in a project's .claude/skills/ folder for one project. In the Claude apps, upload it under Settings → Capabilities → Skills.

Why does the skill say openalex_fetch.py was not found?

The helper is searched in .aris/tools/, tools/, the ARIS_REPO location, or through ~/.aris/repo. The source suggests rerunning tools/install_aris.sh or smart_update.sh, exporting ARIS_REPO, or copying the helper into tools/.

Why are my OPENALEX_API_KEY settings ignored?

The helper reads these variables from its process environment when it starts. Export them in the same shell before starting Claude Code. The source notes that a separate tool-shell export does not update an already running host, and that .env files are not loaded automatically.

How does openalex compare with arXiv and Semantic Scholar?

According to the skill, arXiv is best for the latest preprints, Semantic Scholar for published venue papers with citation counts, and OpenAlex for the open citation graph, institutional affiliations, funding data and broad metadata. The skill positions OpenAlex as a complement to these rather than a replacement.

Can the skill find very recent preprints?

Not as its main strength. The skill recommends arXiv or a general web search for cutting-edge, very recent work, so use those when recency is the priority.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Choose the openalex skill if you want citation counts, open-access links, DOIs and author affiliations gathered in one structured place, and you are comfortable installing Python and requests. Pick arXiv, Semantic Scholar or a general web search instead if you mainly need the newest preprints or do not want to run a helper script.

Download the skill