OpenAlex Academic Search
Search query: $ARGUMENTS
Role & Positioning
This skill uses OpenAlex as a comprehensive open academic graph source:
| Skill |
Source |
Best for |
/arxiv |
arXiv API |
Latest preprints, cutting-edge unrefereed work |
/semantic-scholar |
Semantic Scholar API |
Published venue papers (IEEE, ACM, Springer) with citation counts |
/openalex |
OpenAlex API |
Open citation graph, institutional affiliations, funding data, comprehensive metadata |
/deepxiv |
DeepXiv CLI |
Layered reading: search, brief, section map, section reads |
/exa-search |
Exa API |
Broad web search: blogs, docs, news, companies, research papers |
/gemini-search |
Gemini MCP / CLI |
AI-powered broad literature discovery |
Use OpenAlex when you want:
- Open citation data — fully open citation graph (no API key required for basic use)
- Institutional affiliations — author institutions and collaborations
- Funding information — NSF, NIH, and other funding sources
- Comprehensive metadata — topics, keywords, abstract, open access status
- Cross-database coverage — indexes 250M+ works from multiple sources
Constants
- MAX_RESULTS = 10 — Default number of results. Override with
— max: 20.
- DEFAULT_SORT = relevance — Sort by relevance. Override with
— sort: citations or — sort: date.
- OPENALEX_FETCHER — canonical name
openalex_fetch.py, resolved per
shared-references/integration-contract.md §2
(Policy D1 — standalone /openalex has no documented inline fallback,
so unresolved helper terminates with an explicit error).
Overrides (append to arguments):
/openalex "topic" — max: 20 — return up to 20 results
/openalex "topic" — year: 2023- — papers from 2023 onward
/openalex "topic" — year: 2020-2023 — papers from 2020 to 2023
/openalex "topic" — type: article — only journal articles
/openalex "topic" — type: preprint — only preprints
/openalex "topic" — open-access — only open access papers
/openalex "topic" — min-citations: 50 — minimum 50 citations
/openalex "topic" — sort: citations — sort by citation count (descending)
/openalex "topic" — sort: date — sort by publication date (newest first)
Setup
Prerequisites
Python 3.7+ with requests library:
pip install requests
Optional: API key and email — Set the variables you use in the same shell before starting Claude Code so helper commands inherit them:
export OPENALEX_API_KEY='your-key-here'
export OPENALEX_EMAIL='your-email@example.com'
claude
The helper reads OPENALEX_API_KEY and OPENALEX_EMAIL from its process environment. A separate tool-shell export does not update an already running host. If you keep credentials in an environment file, load it explicitly before starting the host rather than relying on automatic .env loading.
Get API keys (optional but recommended):
- OpenAlex API key: Free tier $1/day (10,000 list calls, 1,000 search calls) from openalex.org
- Email for polite pool: Faster response times (no registration needed)
Verify Setup
python3 "$OPENALEX_FETCHER" search "machine learning" --max 3
(Resolve $OPENALEX_FETCHER via the canonical chain first — see Step 2 below.)
Workflow
Step 1: Parse Arguments
Parse $ARGUMENTS for:
- query: The research topic (required)
- max: Override MAX_RESULTS
- year: Publication year filter (e.g.,
2023-, 2020-2023)
- type: Work type filter (
article, preprint, book, book-chapter, dataset, dissertation)
- open-access: Only include open access papers
- min-citations: Minimum citation count threshold
- sort: Sort order (
relevance, citations, date)
Step 2: Locate Script
Resolve $OPENALEX_FETCHER via the canonical strict-safe chain (see
shared-references/integration-contract.md §2).
Policy D1: there is no native inline fallback for OpenAlex
(retrieval requires the requests SDK + optional API key — the
fetcher script encapsulates pagination, throttling, and per-source
parameters), so unresolved helper terminates with explicit remediation.
cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills.txt ]; then
ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null) || true
fi
if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then
ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true
fi
OPENALEX_FETCHER=".aris/tools/openalex_fetch.py"
[ -f "$OPENALEX_FETCHER" ] || OPENALEX_FETCHER="tools/openalex_fetch.py"
[ -f "$OPENALEX_FETCHER" ] || { [ -n "${ARIS_REPO:-}" ] && OPENALEX_FETCHER="$ARIS_REPO/tools/openalex_fetch.py"; }
[ -f "$OPENALEX_FETCHER" ] || {
echo "ERROR: openalex_fetch.py not resolved at .aris/tools/, tools/, \$ARIS_REPO/tools/, or via ~/.aris/repo." >&2
echo " Fix: rerun bash tools/install_aris.sh or smart_update.sh (refreshes ~/.aris/repo), export ARIS_REPO, or copy the helper to tools/." >&2
echo " Also ensure 'requests' is installed: pip install requests" >&2
exit 1
}
Step 3: Execute Search
Basic search:
python3 "$OPENALEX_FETCHER" search "QUERY" --max 10
With filters:
python3 "$OPENALEX_FETCHER" search "QUERY" --max 10 \
--year 2023- \
--type article \
--open-access \
--min-citations 20 \
--sort citations
Get specific work by DOI:
python3 "$OPENALEX_FETCHER" work "10.1109/TWC.2024.1234567"
Get specific work by OpenAlex ID:
python3 "$OPENALEX_FETCHER" work "W2741809807"
Step 4: Parse Results
The script returns structured JSON with:
title: Paper title
authors: List of author names
publication_year: Year published
venue: Journal/conference name
venue_type: Type of venue (journal, repository, conference, etc.)
cited_by_count: Number of citations
is_oa: Boolean for open access status
oa_status: Open access type (gold, green, bronze, hybrid, closed)
oa_url: Direct PDF link if available
doi: DOI identifier
openalex_id: OpenAlex work ID
abstract: Full abstract text
topics: Top 3 research topics
keywords: Top 5 keywords
type: Work type (article, preprint, etc.)
Step 5: Present Results
Format results as a structured table:
| # | Title | Venue | Year | Citations | OA | Summary |
|---|-------|-------|------|-----------|----|---------|
| 1 | ... | IEEE TWC | 2024 | 156 | ✓ | ... |
| 2 | ... | NeurIPS | 2023 | 89 | ✓ | ... |
For each paper, also show:
- DOI: Canonical identifier
- OpenAlex ID: For cross-reference
- Open Access: Status (gold/green/bronze/hybrid/closed) and PDF link
- Topics: Top research topics
- Abstract: First 200 characters or full text
Step 6: Offer Follow-up
After presenting results, suggest:
/semantic-scholar "DOI:..." — get S2 citation context and related papers
/arxiv "arXiv:XXXX.XXXXX" — fetch arXiv preprint if available
/research-lit "topic" — sources: openalex, semantic-scholar — combined multi-source review
/novelty-check "idea" — verify novelty against literature
Key Rules
- OpenAlex is fully open — no API key required for basic use, but recommended for higher rate limits
- Comprehensive metadata — OpenAlex provides richer metadata than most sources (institutions, funding, topics)
- Citation data is open — unlike Semantic Scholar, all citation data is freely accessible
- Rate limits: Without API key, very limited (~$0.01/day). With free API key: 10,000 list calls/day, 1,000 search calls/day.
- Polite pool: Set
OPENALEX_EMAIL environment variable for faster response times
- Cross-reference with other sources: OpenAlex indexes papers from arXiv, PubMed, Crossref, etc. — use DOI/arXiv ID to cross-reference
- If OpenAlex API is unreachable or rate-limited, suggest using
/semantic-scholar, /arxiv, or /research-lit "topic" — sources: web as alternatives.
OpenAlex vs Other Sources
| Feature |
OpenAlex |
Semantic Scholar |
arXiv |
| Coverage |
250M+ works |
200M+ papers |
2.4M+ preprints |
| Citation data |
Fully open |
Partially open |
None |
| Institutions |
✓ Full affiliations |
✓ Limited |
✗ |
| Funding |
✓ NSF, NIH, etc. |
✗ |
✗ |
| Open access |
✓ Full OA status |
✓ PDF links |
✓ All papers |
| API key |
Optional (free) |
Optional (free) |
Not required |
| Rate limits |
1,000 searches/day (free key) |
Unknown |
1 req/3s |
| Abstract |
✓ Full text |
✓ TLDR |
✓ Full text |
| Best for |
Comprehensive metadata, institutions, funding |
Citation counts, venue info |
Latest preprints |
When to use OpenAlex over S2:
- Need institutional affiliation data
- Need funding information
- Want fully open citation graph
- Need comprehensive topic/keyword metadata
- Working with non-CS fields (OpenAlex covers all disciplines)
When to use S2 over OpenAlex:
- Need real-time citation counts (S2 updates faster)
- Need "highly influential citations" metric
- Need paper recommendations
- CS/AI-focused research (S2 has better CS coverage)
1---2name: openalex-23description: Search academic papers via OpenAlex API for open citation data, institutional affiliations, and funding information. Use when user says "openalex search", "search openalex", "open citation graph", or wants comprehensive academic metadata beyond arXiv/Semantic Scholar.4argument-hint: "[search-query]"5allowed-tools: Bash(*), Read, Write6metadata:7 source: https://skillmd.com/skills/wanshuiyin/openalex-28---910# OpenAlex Academic Search1112Search query: $ARGUMENTS1314## Role & Positioning1516This skill uses OpenAlex as a **comprehensive open academic graph** source:1718| Skill | Source | Best for |19|-------|--------|----------|20| `/arxiv` | arXiv API | Latest preprints, cutting-edge unrefereed work |21| `/semantic-scholar` | Semantic Scholar API | Published venue papers (IEEE, ACM, Springer) with citation counts |22| `/openalex` | OpenAlex API | **Open citation graph, institutional affiliations, funding data, comprehensive metadata** |23| `/deepxiv` | DeepXiv CLI | Layered reading: search, brief, section map, section reads |24| `/exa-search` | Exa API | Broad web search: blogs, docs, news, companies, research papers |25| `/gemini-search` | Gemini MCP / CLI | AI-powered broad literature discovery |2627Use OpenAlex when you want:28- **Open citation data** — fully open citation graph (no API key required for basic use)29- **Institutional affiliations** — author institutions and collaborations30- **Funding information** — NSF, NIH, and other funding sources31- **Comprehensive metadata** — topics, keywords, abstract, open access status32- **Cross-database coverage** — indexes 250M+ works from multiple sources3334## Constants3536- **MAX_RESULTS = 10** — Default number of results. Override with `— max: 20`.37- **DEFAULT_SORT = relevance** — Sort by relevance. Override with `— sort: citations` or `— sort: date`.38- **OPENALEX_FETCHER** — canonical name `openalex_fetch.py`, resolved per39 [`shared-references/integration-contract.md`](../shared-references/integration-contract.md) §240 (Policy D1 — standalone `/openalex` has no documented inline fallback,41 so unresolved helper terminates with an explicit error).4243> Overrides (append to arguments):44> - `/openalex "topic" — max: 20` — return up to 20 results45> - `/openalex "topic" — year: 2023-` — papers from 2023 onward46> - `/openalex "topic" — year: 2020-2023` — papers from 2020 to 202347> - `/openalex "topic" — type: article` — only journal articles48> - `/openalex "topic" — type: preprint` — only preprints49> - `/openalex "topic" — open-access` — only open access papers50> - `/openalex "topic" — min-citations: 50` — minimum 50 citations51> - `/openalex "topic" — sort: citations` — sort by citation count (descending)52> - `/openalex "topic" — sort: date` — sort by publication date (newest first)5354## Setup5556### Prerequisites57581. **Python 3.7+** with `requests` library:59 ```bash60 pip install requests61 ```62632. **Optional: API key and email** — Set the variables you use in the same shell **before starting Claude Code** so helper commands inherit them:64 ```bash65 export OPENALEX_API_KEY='your-key-here'66 export OPENALEX_EMAIL='your-email@example.com'67 claude68 ```6970 The helper reads `OPENALEX_API_KEY` and `OPENALEX_EMAIL` from its process environment. A separate tool-shell `export` does not update an already running host. If you keep credentials in an environment file, load it explicitly before starting the host rather than relying on automatic `.env` loading.71723. **Get API keys** (optional but recommended):73 - **OpenAlex API key**: Free tier $1/day (10,000 list calls, 1,000 search calls) from [openalex.org](https://openalex.org/)74 - **Email for polite pool**: Faster response times (no registration needed)7576### Verify Setup7778```bash79python3 "$OPENALEX_FETCHER" search "machine learning" --max 380```8182(Resolve `$OPENALEX_FETCHER` via the canonical chain first — see Step 2 below.)8384## Workflow8586### Step 1: Parse Arguments8788Parse `$ARGUMENTS` for:89- **query**: The research topic (required)90- **max**: Override MAX_RESULTS91- **year**: Publication year filter (e.g., `2023-`, `2020-2023`)92- **type**: Work type filter (`article`, `preprint`, `book`, `book-chapter`, `dataset`, `dissertation`)93- **open-access**: Only include open access papers94- **min-citations**: Minimum citation count threshold95- **sort**: Sort order (`relevance`, `citations`, `date`)9697### Step 2: Locate Script9899Resolve `$OPENALEX_FETCHER` via the canonical strict-safe chain (see100[`shared-references/integration-contract.md`](../shared-references/integration-contract.md) §2).101Policy D1: there is no native inline fallback for OpenAlex102(retrieval requires the `requests` SDK + optional API key — the103fetcher script encapsulates pagination, throttling, and per-source104parameters), so unresolved helper terminates with explicit remediation.105106```bash107cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1108if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills.txt ]; then109 ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null) || true110fi111if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then112 ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true113fi114OPENALEX_FETCHER=".aris/tools/openalex_fetch.py"115[ -f "$OPENALEX_FETCHER" ] || OPENALEX_FETCHER="tools/openalex_fetch.py"116[ -f "$OPENALEX_FETCHER" ] || { [ -n "${ARIS_REPO:-}" ] && OPENALEX_FETCHER="$ARIS_REPO/tools/openalex_fetch.py"; }117[ -f "$OPENALEX_FETCHER" ] || {118 echo "ERROR: openalex_fetch.py not resolved at .aris/tools/, tools/, \$ARIS_REPO/tools/, or via ~/.aris/repo." >&2119 echo " Fix: rerun bash tools/install_aris.sh or smart_update.sh (refreshes ~/.aris/repo), export ARIS_REPO, or copy the helper to tools/." >&2120 echo " Also ensure 'requests' is installed: pip install requests" >&2121 exit 1122}123```124125### Step 3: Execute Search126127**Basic search:**128```bash129python3 "$OPENALEX_FETCHER" search "QUERY" --max 10130```131132**With filters:**133```bash134python3 "$OPENALEX_FETCHER" search "QUERY" --max 10 \135 --year 2023- \136 --type article \137 --open-access \138 --min-citations 20 \139 --sort citations140```141142**Get specific work by DOI:**143```bash144python3 "$OPENALEX_FETCHER" work "10.1109/TWC.2024.1234567"145```146147**Get specific work by OpenAlex ID:**148```bash149python3 "$OPENALEX_FETCHER" work "W2741809807"150```151152### Step 4: Parse Results153154The script returns structured JSON with:155- `title`: Paper title156- `authors`: List of author names157- `publication_year`: Year published158- `venue`: Journal/conference name159- `venue_type`: Type of venue (journal, repository, conference, etc.)160- `cited_by_count`: Number of citations161- `is_oa`: Boolean for open access status162- `oa_status`: Open access type (gold, green, bronze, hybrid, closed)163- `oa_url`: Direct PDF link if available164- `doi`: DOI identifier165- `openalex_id`: OpenAlex work ID166- `abstract`: Full abstract text167- `topics`: Top 3 research topics168- `keywords`: Top 5 keywords169- `type`: Work type (article, preprint, etc.)170171### Step 5: Present Results172173Format results as a structured table:174175```176| # | Title | Venue | Year | Citations | OA | Summary |177|---|-------|-------|------|-----------|----|---------| 178| 1 | ... | IEEE TWC | 2024 | 156 | ✓ | ... |179| 2 | ... | NeurIPS | 2023 | 89 | ✓ | ... |180```181182For each paper, also show:183- **DOI**: Canonical identifier184- **OpenAlex ID**: For cross-reference185- **Open Access**: Status (gold/green/bronze/hybrid/closed) and PDF link186- **Topics**: Top research topics187- **Abstract**: First 200 characters or full text188189### Step 6: Offer Follow-up190191After presenting results, suggest:192193```text194/semantic-scholar "DOI:..." — get S2 citation context and related papers195/arxiv "arXiv:XXXX.XXXXX" — fetch arXiv preprint if available196/research-lit "topic" — sources: openalex, semantic-scholar — combined multi-source review197/novelty-check "idea" — verify novelty against literature198```199200## Key Rules201202- **OpenAlex is fully open** — no API key required for basic use, but recommended for higher rate limits203- **Comprehensive metadata** — OpenAlex provides richer metadata than most sources (institutions, funding, topics)204- **Citation data is open** — unlike Semantic Scholar, all citation data is freely accessible205- **Rate limits**: Without API key, very limited (~$0.01/day). With free API key: 10,000 list calls/day, 1,000 search calls/day.206- **Polite pool**: Set `OPENALEX_EMAIL` environment variable for faster response times207- **Cross-reference with other sources**: OpenAlex indexes papers from arXiv, PubMed, Crossref, etc. — use DOI/arXiv ID to cross-reference208- If OpenAlex API is unreachable or rate-limited, suggest using `/semantic-scholar`, `/arxiv`, or `/research-lit "topic" — sources: web` as alternatives.209210## OpenAlex vs Other Sources211212| Feature | OpenAlex | Semantic Scholar | arXiv |213|---------|----------|------------------|-------|214| **Coverage** | 250M+ works | 200M+ papers | 2.4M+ preprints |215| **Citation data** | Fully open | Partially open | None |216| **Institutions** | ✓ Full affiliations | ✓ Limited | ✗ |217| **Funding** | ✓ NSF, NIH, etc. | ✗ | ✗ |218| **Open access** | ✓ Full OA status | ✓ PDF links | ✓ All papers |219| **API key** | Optional (free) | Optional (free) | Not required |220| **Rate limits** | 1,000 searches/day (free key) | Unknown | 1 req/3s |221| **Abstract** | ✓ Full text | ✓ TLDR | ✓ Full text |222| **Best for** | Comprehensive metadata, institutions, funding | Citation counts, venue info | Latest preprints |223224**When to use OpenAlex over S2:**225- Need institutional affiliation data226- Need funding information227- Want fully open citation graph228- Need comprehensive topic/keyword metadata229- Working with non-CS fields (OpenAlex covers all disciplines)230231**When to use S2 over OpenAlex:**232- Need real-time citation counts (S2 updates faster)233- Need "highly influential citations" metric234- Need paper recommendations235- CS/AI-focused research (S2 has better CS coverage)