NASA ADS Skill
SukiYume/nasa-ads-skill
Acesso ao NASA ADS para buscas e citações científicas via assistentes IA
Ver no GitHubSkill/plugin que integra o NASA Astrophysics Data System (ADS) ao Claude, Codex e Gemini, permitindo buscas de papers científicos, gerenciamento de bibliotecas e cálculo de métricas de citação diretamente via assistentes IA. Executa chamadas à API REST do ADS através de shell commands, sem servidor backend dedicado.
Instalação
npx convez-ai SukiYume/nasa-ads-skill1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Pesquisa bibliográfica automatizada em astrofísica e ciências correlatas
- Exportação de citações em múltiplos formatos (BibTeX, AASTeX, RIS, etc)
- Gestão de bibliotecas de papers e cálculo de índices de impacto (h-index, g-index)
Veredito

Ferramenta bem estruturada e documentada para pesquisadores que usam Claude/Codex. Requer token API e acesso shell, mas simplifica workflows de literatura científica. Escopo bem delimitado em pesquisa prática sem pretensões de cobertura universal da API.
README
A tradução para o português deste README ainda está na fila.
NASA ADS Skill
A packaged NASA ADS skill/plugin bundle for Claude Code and Codex.
This repository is intentionally documentation-first: it does not ship a standalone API client or background service. Instead, it packages prompt/skill assets that instruct the host assistant to call the NASA Astrophysics Data System (ADS) REST API from the local shell using your token.
Conceptually, this repo is a skill/plugin wrapper around the public adsabs-dev-api: it repackages the ADS API surface from that project into assistant-friendly skills, slash commands, and plugin manifests for Claude Code, Codex, Gemini, and similar tools.
What It Covers
| Feature | Description |
|---|---|
| Paper Search | Search by author, title, abstract, bibcode, DOI, arXiv ID, object, ORCID, or full text |
| Metadata | Return title, authors, abstract, year, journal, DOI, citation count, and identifiers |
| Citation Export | Export BibTeX, AASTeX, MNRAS, RIS, EndNote, IEEE, and more |
| Libraries | List, view, create, update, share, combine, and delete ADS libraries |
| Metrics | h-index, g-index, i10-index, citation stats, read stats, and indicators |
| Citation Helper | Suggest related or missing citations |
| Resolver | Return ADS, publisher, arXiv, and data-archive links |
Scope
This package is intentionally scoped to practical literature research and citation workflows. It does not try to wrap every ADS API endpoint; if you need uncommon endpoints such as journal metadata, object lookup, visualizations, or reference parsing, use the official ADS API documentation directly.
Requirements
You need all of the following:
- An ADS API token from ADS token settings
- Outbound HTTPS access to
https://api.adsabs.harvard.edu - A host environment that allows the assistant to run shell commands (
curlor equivalent)
Supported environment variables:
ADS_API_TOKENADS_DEV_KEY
Examples:
export ADS_API_TOKEN="your-token-here"
[System.Environment]::SetEnvironmentVariable("ADS_API_TOKEN", "your-token-here", "User")
Post-Install: Create and Set Your ADS API Token
After installing the skill or plugin, create a personal ADS API token before your first ADS request. The token is required for search, export, library, metrics, citation-helper, and resolver calls.
- Open ADS token settings.
- Register for an ADS account or sign in with your existing account.
- If ADS does not open the token page directly, go to your account settings and choose API Token.
- Click Generate a new key.
- Copy the token once and keep it private. Do not commit it to this repository or paste it into shared logs.
- Save it as an environment variable named
ADS_API_TOKEN:
export ADS_API_TOKEN="paste-your-token-here"
[System.Environment]::SetEnvironmentVariable("ADS_API_TOKEN", "paste-your-token-here", "User")
- Restart your terminal or host assistant session so it can read the new environment variable.
Installation for Humans
Step-by-step instructions for researchers and developers who want to install this skill manually.
One-Line Agent Prompts
If your host assistant can edit files and run shell commands, you can often install this repo by pasting one short request instead of following the manual steps.
Codex
Copy this into Codex:
Install the NASA ADS skill from https://github.com/SukiYume/nasa-ads-skill into this repository by copying `plugins/nasa-ads` into `./plugins/nasa-ads`, then merge the `nasa-ads` entry from `.agents/plugins/marketplace.json` into `./.agents/plugins/marketplace.json` without overwriting existing plugins.
For skill-only install:
Install only the NASA ADS skill from https://github.com/SukiYume/nasa-ads-skill by copying `plugins/nasa-ads/skills/nasa-ads/SKILL.md` to `$CODEX_HOME/skills/nasa-ads/SKILL.md` (default `~/.codex/skills/nasa-ads/SKILL.md`).
Claude Code
Copy this into Claude Code:
Add `SukiYume/nasa-ads-skill` as a Claude plugin marketplace and install `nasa-ads@nasa-ads-community`, then confirm the NASA ADS slash commands are available.
Gemini CLI
Copy this into Gemini:
Install the NASA ADS skill from https://github.com/SukiYume/nasa-ads-skill by placing `plugins/nasa-ads/skills/nasa-ads/SKILL.md` in this project and adding `@./plugins/nasa-ads/skills/nasa-ads/SKILL.md` to `GEMINI.md`.
Generic AI Assistant
Copy this into any agent that supports Markdown skills or prompt files:
Download `https://raw.githubusercontent.com/SukiYume/nasa-ads-skill/master/plugins/nasa-ads/skills/nasa-ads/SKILL.md` and load it as a reusable Markdown skill for NASA ADS search, metadata, BibTeX, libraries, metrics, and resolver workflows.
Claude Code (CLI / Desktop / VS Code / JetBrains)
Add this repository as a plugin marketplace, then install the plugin:
# Step 1: Add the marketplace
claude plugin marketplace add SukiYume/nasa-ads-skill
# Step 2: Install the plugin
claude plugin install nasa-ads@nasa-ads-community
Or from inside a Claude Code session:
/plugin marketplace add SukiYume/nasa-ads-skill
/plugin install nasa-ads@nasa-ads-community
After installation, you get five slash commands:
/nasa-ads:ads-search author:Einstein gravitational waves
/nasa-ads:ads-bibtex 2016PhRvL.116f1102A
/nasa-ads:ads-library list
/nasa-ads:ads-metrics 2016PhRvL.116f1102A
/nasa-ads:ads-cite similar 2016PhRvL.116f1102A
/nasa-ads:ads-library supports list/view/create/add/remove plus metadata updates, query-based edits, sharing, set operations, and library deletion.
The skill also activates automatically from plain-language requests about papers, citations, ADS, BibTeX, arXiv, libraries, or metrics.
Before running the first command, complete Post-Install: Create and Set Your ADS API Token. The commands will fail with 401 Unauthorized or ask for a token if ADS_API_TOKEN or ADS_DEV_KEY is missing.
Codex
Option A: Repo-local plugin install
- Copy the
plugins/nasa-adsdirectory into your project - Merge the
nasa-adsplugin entry into.agents/plugins/marketplace.json
git clone https://github.com/SukiYume/nasa-ads-skill.git /tmp/nasa-ads-skill
cp -r /tmp/nasa-ads-skill/plugins/nasa-ads ./plugins/nasa-ads
python - <<'PY'
import json
from pathlib import Path
path = Path(".agents/plugins/marketplace.json")
path.parent.mkdir(parents=True, exist_ok=True)
entry = {
"name": "nasa-ads",
"source": {"source": "local", "path": "./plugins/nasa-ads"},
"policy": {"installation": "AVAILABLE", "authentication": "ON_INSTALL"},
"category": "Research",
}
if path.exists():
data = json.loads(path.read_text())
else:
data = {"name": "local", "interface": {"displayName": "Local Plugins"}, "plugins": []}
data.setdefault("name", "local")
data.setdefault("interface", {}).setdefault("displayName", "Local Plugins")
data["plugins"] = [p for p in data.get("plugins", []) if p.get("name") != "nasa-ads"] + [entry]
path.write_text(json.dumps(data, indent=2) + "\n")
PY
Option B: Personal install (available in all repos)
cp -r plugins/nasa-ads ~/plugins/nasa-ads
mkdir -p ~/.agents/plugins
# Merge the nasa-ads entry into ~/.agents/plugins/marketplace.json; do not overwrite existing plugins.
Option C: Skill-only (no plugin metadata)
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills/nasa-ads"
cp plugins/nasa-ads/skills/nasa-ads/SKILL.md "${CODEX_HOME:-$HOME/.codex}/skills/nasa-ads/SKILL.md"
Gemini CLI
Add this line to your project's GEMINI.md:
@./plugins/nasa-ads/skills/nasa-ads/SKILL.md
Or copy the skill file into your Gemini skill directory.
Other AI Assistants
The core file is plugins/nasa-ads/skills/nasa-ads/SKILL.md — a self-contained ADS API reference in Markdown. Copy it into any assistant's skill/prompt directory.
Installation for AI Agents
Instructions for AI agents (Claude, Codex, etc.) that need to install this skill programmatically on behalf of a user.
After any install path below, explicitly remind the user to create an ADS API token:
- Open https://ui.adsabs.harvard.edu/#user/settings/token.
- Register or sign in to ADS.
- Go to account settings, then API Token, if the direct link does not land there.
- Click Generate a new key and copy the token.
- Store it as
ADS_API_TOKENorADS_DEV_KEYin the user's shell environment. - Restart the terminal or assistant session before making ADS API calls.
Claude Code Agent
Run these two shell commands:
claude plugin marketplace add SukiYume/nasa-ads-skill
claude plugin install nasa-ads@nasa-ads-community
No additional plugin setup is needed. The skill and commands will be available immediately, but ADS API calls still require the user to create an ADS API token and expose it as ADS_API_TOKEN or ADS_DEV_KEY.
For local development or testing:
git clone https://github.com/SukiYume/nasa-ads-skill.git /tmp/nasa-ads-skill
cd /tmp/nasa-ads-skill
claude plugin marketplace add .
claude plugin install nasa-ads@nasa-ads-community
Codex Agent
Clone the repo and wire up the marketplace:
git clone https://github.com/SukiYume/nasa-ads-skill.git /tmp/nasa-ads-skill
cp -r /tmp/nasa-ads-skill/plugins/nasa-ads ./plugins/nasa-ads
python - <<'PY'
import json
from pathlib import Path
path = Path(".agents/plugins/marketplace.json")
path.parent.mkdir(parents=True, exist_ok=True)
entry = {
"name": "nasa-ads",
"source": {"source": "local", "path": "./plugins/nasa-ads"},
"policy": {"installation": "AVAILABLE", "authentication": "ON_INSTALL"},
"category": "Research",
}
if path.exists():
data = json.loads(path.read_text())
else:
data = {"name": "local", "interface": {"displayName": "Local Plugins"}, "plugins": []}
data.setdefault("name", "local")
data.setdefault("interface", {}).setdefault("displayName", "Local Plugins")
data["plugins"] = [p for p in data.get("plugins", []) if p.get("name") != "nasa-ads"] + [entry]
path.write_text(json.dumps(data, indent=2) + "\n")
PY
Or for skill-only (no plugin scaffold):
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills/nasa-ads"
curl -sL https://raw.githubusercontent.com/SukiYume/nasa-ads-skill/master/plugins/nasa-ads/skills/nasa-ads/SKILL.md \
-o "${CODEX_HOME:-$HOME/.codex}/skills/nasa-ads/SKILL.md"
For the best Codex UI metadata in a skill-only install, also copy plugins/nasa-ads/skills/nasa-ads/agents/openai.yaml to the same relative agents/openai.yaml path.
Gemini Agent
Append the skill reference to GEMINI.md:
echo '@./plugins/nasa-ads/skills/nasa-ads/SKILL.md' >> GEMINI.md
Or fetch the skill file directly:
mkdir -p plugins/nasa-ads/skills/nasa-ads
curl -sL https://raw.githubusercontent.com/SukiYume/nasa-ads-skill/master/plugins/nasa-ads/skills/nasa-ads/SKILL.md \
-o plugins/nasa-ads/skills/nasa-ads/SKILL.md
echo '@./plugins/nasa-ads/skills/nasa-ads/SKILL.md' >> GEMINI.md
Generic Agent
For any agent that supports Markdown-based skills, fetch the single reference file:
curl -sL https://raw.githubusercontent.com/SukiYume/nasa-ads-skill/master/plugins/nasa-ads/skills/nasa-ads/SKILL.md \
-o nasa-ads-skill.md
Then load nasa-ads-skill.md into the agent's system prompt or skill directory. The file is self-contained — no other files are required for basic functionality.
Usage
Plain-language prompts:
- "Search ADS for recent papers on exoplanet atmospheres"
- "Get the BibTeX for this paper: 2016PhRvL.116f1102A"
- "Show me my ADS libraries"
- "What are the citation metrics for these bibcodes?"
- "Find papers similar to 2016PhRvL.116f1102A"
Claude command examples:
/nasa-ads:ads-search dark matter year:2020-2024
/nasa-ads:ads-bibtex 2016PhRvL.116f1102A 2017ApJ...848L..12A --format aastex
/nasa-ads:ads-library create "My Reading List"
/nasa-ads:ads-cite links 2016PhRvL.116f1102A
Repository Layout
nasa-ads-skill/
├── .claude-plugin/
│ └── marketplace.json
├── .agents/
│ └── plugins/
│ └── marketplace.json
├── plugins/
│ └── nasa-ads/
│ ├── .claude-plugin/
│ │ └── plugin.json
│ ├── .codex-plugin/
│ │ └── plugin.json
│ ├── commands/
│ │ ├── ads-search.md
│ │ ├── ads-bibtex.md
│ │ ├── ads-library.md
│ │ ├── ads-metrics.md
│ │ └── ads-cite.md
│ └── skills/
│ └── nasa-ads/
│ ├── agents/
│ │ └── openai.yaml
│ └── SKILL.md
├── AGENTS.md
├── CLAUDE.md
├── GEMINI.md
├── README.zh-CN.md
└── README.md
The detailed ADS API reference lives in plugins/nasa-ads/skills/nasa-ads/SKILL.md, and the Claude command files are task-specific wrappers that should stay aligned with it.
API Endpoints Covered
| Endpoint | Method | Purpose |
|---|---|---|
/search/query | GET | Search for papers |
/search/bigquery | POST | Batch bibcode lookup |
/export/<format> | GET/POST | Export citations |
/biblib/libraries | GET/POST | List or create libraries |
/biblib/libraries/<id> | GET | View library contents |
/biblib/documents/<id> | POST/PUT/DELETE | POST adds/removes documents, PUT updates library metadata, DELETE removes the library |
/biblib/query/<id> | GET/POST | Add or remove papers by query |
/biblib/libraries/operations/<id> | POST | Library set operations |
/biblib/permissions/<id> | GET/POST | Library permissions |
/metrics | POST | Citation metrics and indicators |
/citation_helper | POST | Suggested citations |
/resolver/<bibcode> | GET | Full-text and data links |
Notes
- The packaged commands assume the assistant can run shell commands.
- The bundled examples now fall back from
ADS_API_TOKENtoADS_DEV_KEY. - No token is stored in this repository.
- If you add or change ADS workflows, update
SKILL.mdfirst and then any Claude command files that expose the same workflow.
License
MIT