使い方
- インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
- 必要なツール、認証情報、対応環境を原文で確認します。
- 入力と成果物を指定し、出力を資料と照合します。
npx skills add https://github.com/google-deepmind/science-skills --skill literature-search-openalex開始前の確認
- 導入にはモデル契約、API枠、ファイルへのアクセス許可は含まれません。
- スター数や導入数は活動の指標であり、独立した品質・安全性試験ではありません。
見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。
OpenAlex Skill
Prerequisites
- `uv`: Read the
uvskill and follow its Setup instructions to ensure
uv is installed and on PATH.
- User Notification: If .licenses/literaturesearchopenalex_LICENSE.txt
does not already exist in the workspace root directory then (1) prominently notify the user to check the terms at https://help.openalex.org/ and to always check the license of the papers retrieved by the skill for any restrictions, then (2) create the file recording the notification text and timestamp.
- `.env` file: Make sure the
.envfile exists in your home directory.
Create one if it does not exist.
- `OPENALEX_API_KEY` (optional but recommended): The skill works without a
key, but keyless requests share a $0.10/day budget per IP address. A free key has its own $1/day budget and higher rate limits, and is required to download full text from content.openalex.org (download-pdf). Adding mailto (the former "polite pool") no longer raises limits. You can obtain a free key at OpenAlex.org → account settings. Whenever checking for or requesting this key, you MUST use the safe credentials protocol in the credentials skill, without blocking keyless execution if it is unset.
Core Rules
- List Sources. If this skill is used, ensure this is mentioned in the
output AND list the URLs of all papers that were used in producing the output.
- Resolve before filter. NEVER filter by name. Always
resolvea name to
an ID first, then use that ID in --filter.
- Use the CLI only. Never call the API via
curl/urllib. The CLI
handles retries and rate limiting.
- No fabrication. Never invent OpenAlex IDs or DOIs. Use
resolve/get
to look them up. Report empty results accurately.
- API key. If a command returns 401, returns 429 because of a rate limit
or exhausted daily budget, or you need high-volume queries, you MUST use the safe credentials protocol in the credentials skill to check for and request the OPENALEX_API_KEY to help the user add it to their .env file. A free key does not fix a 429 Plan upgrade required error.
- Keep output small. Always use
--selectand--per-page 5–10for
overview queries. Pipe filter output to a file (> results.json), then slim with jq before reading into context.
Rate Limits
- Without key: 10 req/s; $0.10/day budget per IP address, shared by all
keyless requests from that IP.
- With free key: 30 req/s; $1/day budget.
- Annual plan: 50 req/s.
| Operation | Cost |
|---|---|
Singleton get | Free |
filter | $0.0001 |
--search / resolve | $0.001 |
download-pdf | $0.01 |
CLI Reference
uv run scripts/openalex_cli.py [--api-key KEY] <command> [flags]Entity types (shared across commands): works, authors, sources, institutions, topics, domains, fields, subfields, sdgs, countries, continents, languages, keywords, publishers, funders, work-types, source-types, institution-types, licenses
Commands
resolve <entity> <query> — Name → ID candidates. Returns id, display_name, hint. Use --per-page N for more candidates.
get <entity> <id> — Full metadata for one entity. Accepts short ID (W2741809807), full URL, or DOI URL. Use --select to limit fields.
filter <entity> — Search/filter entities. Key flags are:
--search <query>: Full-text search (10× cost of--filter)--filter <expr>: Filter expressions. Use,for AND and|for OR.--sort <field:dir>: Sort results (e.g.,cited_by_count:desc)--select <fields>: Limit the fields returned in the output.--group-by <field>: Aggregate results by a specific field.--per-page <N>: Number of results per page (default 25, max 100).--page <N>: Specify the page number to retrieve.--sample <N>: Get a random sample of up to 10,000 results.--seed <N>: Seed for reproducible sampling.
download-pdf <work-id> <output-path> — Download PDF (content.openalex.org requires OPENALEX_API_KEY; falls back to alternative pdf_url locations from work metadata if unauthenticated or if the primary server fails). Always run download-pdf and verify any downloaded PDF is non-empty and not corrupted; if OPENALEX_API_KEY is missing, also refer to the credentials skill to help the user add it.
rate-limit — Check current rate limit and daily credit status (reports shared per-IP limits when keyless, or key-specific limits when OPENALEX_API_KEY is set; if OPENALEX_API_KEY is not set, also refer to the credentials skill to help the user add it).
Search Tips
- If
resolvereturns no matches, try alternate spellings or abbreviations. - If
--searchreturns 0 results, try broader terms (max 3 retries). - If
resolvereturns multiple candidates, present them to the user with
display_name and hint for manual selection.
Entity References
Consult references/ for valid filter, sort, and group-by fields per entity:
— Taxonomy
For anything not covered here, or if the API behaves differently from what this skill describes, check the official docs index at https://help.openalex.org/llms.txt.
Common Workflows
# Author's works (resolve → filter)
uv run scripts/openalex_cli.py resolve authors "Geoffrey Hinton"
uv run scripts/openalex_cli.py filter works \
--filter "authorships.author.id:A5108093963" \
--sort "cited_by_count:desc" --per-page 10 > papers.json
cat papers.json | jq '[.results[] | {id, title: .display_name, year: .publication_year, citations: .cited_by_count}]'
# DOI lookup
uv run scripts/openalex_cli.py get works "https://doi.org/10.1038/s41586-021-03819-2"
# Bulk DOI lookup (up to 100)
uv run scripts/openalex_cli.py filter works \
--filter "doi:10.1234/a|10.1234/b|10.1234/c" --per-page 100 > results.json
# Institutional impact by year
uv run scripts/openalex_cli.py resolve institutions "MIT"
uv run scripts/openalex_cli.py filter works \
--filter "authorships.institutions.id:I63966007" \
--group-by "publication_year" > mit_by_year.json
# Random sample
uv run scripts/openalex_cli.py filter works \
--filter "publication_year:2023,is_oa:true" \
--sample 100 --seed 42 > results.jsonError Handling
The CLI already retries 429s with backoff, except Plan upgrade required ones, which fail immediately with an explanation. Don't blindly retry either kind; the Server body in the error output tells them apart.
| Code | Meaning | Action |
|---|---|---|
| 401 | Unauthorized | You MUST use safe credentials protocol in credentials skill to help user add API key to .env |
| 404 | Not found | Verify ID; try resolve first |
| 429 | Body says Plan upgrade required | Paid-plan feature (e.g. a plan-gated filter). Do not retry; a free key won't help. Drop the filter or inform user; see https://openalex.org/pricing |
| 429 | Body says rate limit or budget exhausted | No key: you MUST use safe credentials protocol in credentials skill to help user add API key to .env. With key: wait and retry (rate limit) or tell user the daily budget is spent |
Known plan-gated filters: from_created_date, from_updated_date, to_updated_date.
Never fabricate results on empty responses — report accurately and suggest alternate search terms.