ads-cite

name	ads-cite
description	Search NASA ADS by author/year/text, pick from results, export bibtex entry to a .bib file
user-invocable	true

ADS Cite

Search NASA ADS, fetch records, export bibtex, look up citations and references. Primary use case: the user wants a bibtex entry for a .bib file — you search, they pick, you fetch (or append directly).

All API access goes through the helper script ads_cite.py next to this file. Run python3 ~/.claude/skills/ads-cite/ads_cite.py --help to see the full CLI.

The script finds the ADS token in this order: macOS Keychain (service nasa-ads-api-token) → ADS_DEV_KEY/ADS_API_TOKEN env var → ~/.ads/dev_key file. This makes the skill portable to linux (NCSA, NERSC, etc.) without keychain access.

Subcommands

Subcommand	Purpose
search "<QUERY>"	Search ADS, print numbered results
show <BIBCODE>	Full record: title, authors, abstract, DOI, keywords
bibtex <BIBCODE>...	Verbatim bibtex from ADS export endpoint
citations <BIBCODE>	Papers citing this one, sorted by citation count
references <BIBCODE>	Papers cited by this one (complement of citations)
arxiv <ID>	Resolve arXiv ID; prefers refereed version if one exists
doi <DOI>	Resolve DOI to ADS bibcode
append <BIBFILE> <BIBCODE>...	Append bibtex to a .bib file, skipping duplicates

Flags: --json (machine-readable output), --rows N, --sort "FIELD DIR", --rekey + --subject WORD / --collab-tag TAG (rewrite citekey as LastName_Subject_Year; low-confidence keys WARN on stderr), --rekey-report (dry-run preview, writes nothing), --include-unrefereed (search/citations/references only).

Parse the user's query

Accept any combination of:

• author — surname or "Surname, F." A leading ^ means first author
• year — single year 2024, range 2020-2024, or open range 2020-
• text — free text matched against title + abstract

Examples:

• /ads-cite Narayan 2024 white dwarf calibration
• /ads-cite ^Coelho 2020
• /ads-cite kilonova r-process 2017

Token assignment: capitalized surname-looking word (or one with leading ^) → author; 4-digit number or YYYY-YYYY/YYYY- → year; everything else → text. If ambiguous, ask once.

Build the query

Join with implicit AND spaces:

• author → author:"SURNAME" (keep any leading ^ inside the quotes for first-author)
• year → year:2024 or year:[2020 TO 2024] or year:[2020 TO *]
• text → free text appended as-is

Workflow

1. Search:

   python3 ~/.claude/skills/ads-cite/ads_cite.py search '<QUERY>'
   

   Default filters: database:astronomy, doctype:(article OR eprint). AAS meeting abstracts, conference proceedings, and PhD theses are excluded. Add --include-unrefereed to drop the doctype filter and include all content types.

   If 0 results: report and suggest broadening (drop a term). If 1 result: auto-select. If >1: ask which number (or all).

2. Append to .bib (preferred when a .bib exists in CWD):

   python3 ~/.claude/skills/ads-cite/ads_cite.py append --rekey --subject <WORD> <BIBFILE> <BIBCODE>
   

   Use --rekey by default. It rewrites the citekey as LastName_Subject_Year (e.g., Narayan_ESSENCE_2016) and prepends % ADS bibcode: <X> as a comment so the original identifier is preserved and dedup still works.

   Picking the subject:

   • If the user's query contained a distinctive capitalized term (project name, survey, object ID) that appears in the chosen paper's title, use it as --subject. Examples: user queries /ads-cite Narayan 2024 ESSENCE and the result's title contains ESSENCE → --subject ESSENCE.
   • Otherwise, omit --subject and let the CLI auto-derive from the title (prefers UPPERCASE acronyms; demotes object/catalog designations).
   • The CLI prints a WARN to stderr when a rekey is low-confidence (generic subject, collaboration author, accent-repaired surname, missing author/year). Watch stderr and propose a --subject (or --collab-tag for a collaboration author) before committing whenever a WARN fires.
   • For a bulk rekey, run --rekey-report first: it prints the proposed bibcode -> citekey [flags] table and writes nothing, so you can review the whole batch (and catch any collision) before the real append.
   • --subject works with multiple bibcodes: the same word applies to all entries. Each entry still gets a unique citekey because LastName and Year differ per paper.
   • For a collaboration/institutional first author (e.g. an LSST DESC or PLAsTiCC paper) the auto tag is a compact acronym (LSSTDESC, PLAsTiCC); pass --collab-tag TAG to override it.

   When to skip --rekey: if the target .bib already has entries keyed by raw bibcode (@ARTICLE{2016ApJS..224....3N,...), match that convention and drop --rekey so the file stays consistent. Grep the file first.

3. Or print bibtex for paste-in (same --rekey / --subject flags apply):

   python3 ~/.claude/skills/ads-cite/ads_cite.py bibtex --rekey <BIBCODE>
   

When both a preprint and a refereed version appear, prefer the refereed one but mention the preprint alternative.

Example end-to-end (skill invocation → CLI calls)

User: /ads-cite Narayan 2024 ESSENCE

Claude:

1. Parses: author=Narayan, year range including 2024, text=ESSENCE
2. Runs: ads_cite.py search 'author:"Narayan" year:2024 ESSENCE'
3. Shows numbered list; user picks #1 → bibcode 2016ApJS..224....3N
4. Greps refs.bib in CWD: no existing entries, or rekeyed entries present
5. Runs: ads_cite.py append --rekey --subject ESSENCE refs.bib 2016ApJS..224....3N
6. Reports: "Appended as Narayan_ESSENCE_2016 to refs.bib"

The --rekey and --subject flags are chosen by Claude from SKILL.md guidance; the user never types them as slash-command args.

Other verbs

• show <BIBCODE> — title, full authors, journal, year, DOI, keywords, ADS URL, abstract (no click-through to ADS needed)
• citations <BIBCODE> — lit review: who cited this paper, sorted by citations
• references <BIBCODE> — lit review: what this paper builds on
• arxiv <ID> / doi <DOI> — resolve external identifiers to ADS bibcodes

Output

Default: if a single .bib file exists in CWD, use append directly. Otherwise bibtex + print in a fenced code block.

Notes

• Do NOT hand-edit or fabricate bibtex — it comes verbatim from the ADS export endpoint.
• Do NOT cache results across invocations; ADS data can change.
• Rate limit: ADS allows ~5000 queries/day per token.
• If the search returns a preprint bibcode (e.g., 2026arXiv...) and a refereed version also exists, prefer the refereed one — mention the alternative to the user.