ads-cite

Скилл для Claude Code и самостоятельный CLI для поиска в NASA ADS, получения записей и экспорта verbatim bibtex в файл .bib.

Зачем это нужно

При написании статей и заявок по астрономии/астрофизике приходится цитировать множество работ, индексированных в ADS. Этот скилл оборачивает ADS API, позволяя из Claude Code или командной строки:

• Искать по автору / году / заголовку / тексту / журналу / ORCID / гранту / коллекции
• Выбирать из пронумерованного списка результатов
• Получать verbatim запись bibtex из ADS (без ручных или галлюцинированных записей)
• Добавлять в файл .bib с определением дубликатов — или выводить для вставки вручную
• Искать записи по arXiv ID или DOI (предпочитает рецензируемую версию, если она существует)
• Выводить список статей, цитирующих или цитируемых по заданному bibcode

ads_cite.py также является самостоятельным CLI, используемым без Claude Code (устанавливается через pip как ads-cite).

Установка

Требуется Python 3.9+. Только стандартная библиотека; дополнительные зависимости не нужны.

Как скилл для Claude Code:

Claude Code автоматически подхватывает скилл при следующем запуске сессии. Проверьте через /skills или вызовите /ads-cite help.

Как самостоятельный CLI (устанавливает ads-cite в PATH, Claude Code не требуется):

pip install git+https://github.com/gnarayan/ads-cite.git
# или после публикации на PyPI: pip install ads-cite
ads-cite --help

Оба варианта используют одну и ту же конфигурацию токена (следующий раздел). При установке как скилл также выдайте разрешение, описанное ниже.

Настройка токена ADS API

Получите токен на https://ui.adsabs.harvard.edu → Account Settings → API Token. ADS допускает 5000 вызовов API в день на токен; поиск + экспорт bibtex — это 2 вызова. Скрипт ищет токен в следующем порядке (используется первое совпадение):

1. macOS Keychain (рекомендуется на Mac):
   bashКопировать

   security add-generic-password -a "$USER" -s "nasa-ads-api-token" -w "<TOKEN>" -U

2. Переменная окружения (рекомендуется на Linux):
   bashКопировать

   export ADS_DEV_KEY="<TOKEN>"
   # или ADS_API_TOKEN

3. Файл (универсальный запасной вариант): mkdir -p ~/.ads && echo "<TOKEN>" > ~/.ads/dev_key && chmod 600 ~/.ads/dev_key

Выдача разрешения скиллу (однократно)

Добавьте эту строку в ~/.claude/settings.local.json в раздел permissions.allow, чтобы Claude Code не запрашивал подтверждение при каждом запуске скрипта:

Настройка поведения Claude при работе с библиографией

Одной установки скилла недостаточно. По умолчанию Claude пишет bibtex по памяти при запросе цитаты и будет галлюцинировать названия журналов, тома, номера страниц и списки авторов. Добавьте правило в глобальный файл ~/.claude/CLAUDE.md, которое перенаправит все запросы bibtex через ads-cite.

Вставьте это в ваш ~/.claude/CLAUDE.md (создайте файл, если он не существует):

## Правила библиографии (СТРОГИЕ)

- **НИКОГДА не писать и не генерировать записи bibtex вручную.** Каждая запись `.bib`
  должна поступать verbatim из endpoint экспорта NASA ADS.
- Всегда использовать файлы `.bib` с `natbib` или `biblatex` — никогда не
  вставлять цитаты жёстко в `.tex`.
- **Рабочий процесс:** использовать скилл `/ads-cite` (или CLI `ads-cite` напрямую) для
  поиска в ADS, выбора результата, затем:
  - `ads-cite append --rekey <BIBFILE> <BIBCODE>` — добавляет verbatim bibtex
    с запоминаемым citekey `LastName_Subject_Year` и сохраняет исходный bibcode
    как комментарий `% ADS bibcode:`; пропускает дубликаты
  - `ads-cite bibtex --rekey <BIBCODE>` — выводит bibtex для вставки вручную
- С `--rekey` цитировать как `\citep{Narayan_ESSENCE_2016}`. Без него
  citekey — это сырой bibcode (`\citep{2016ApJS..224....3N}`). Следовать
  соглашению, уже используемому в существующем файле `.bib`. Комментарий с URL
  не нужен — URL ADS находится в поле `adsurl` bibtex.

С этой настройкой, когда вы просите Claude добавить цитату или ссылки в черновик, он будет запускать ads-cite вместо того, чтобы придумывать запись bibtex.

Использование — из Claude Code

/ads-cite Narayan 2024 white dwarf calibration
/ads-cite ^Coelho 2020               # первый автор Coelho, год 2020
/ads-cite kilonova r-process 2017
/ads-cite help                        # вывести полную справку

Claude автоматически разбирает аргументы автора/года/текста, выполняет поиск, показывает пронумерованный список, спрашивает, какой результат нужен, и либо добавляет в файл .bib в текущей директории, либо выводит bibtex для вставки вручную.

Также работает синтаксис полей ADS напрямую:

/ads-cite author:"Scolnic" bibstem:ApJ year:2022-2024
/ads-cite bibgroup:DESC first_author:"Malz" keyword:"photo-z"

Использование — CLI напрямую

ads-cite search "author:^Narayan year:2024"
ads-cite show 2016ApJS..224....3N
ads-cite bibtex 2016ApJS..224....3N
ads-cite citations 2016ApJS..224....3N
ads-cite references 2016ApJS..224....3N
ads-cite arxiv 2510.07637
ads-cite doi 10.3847/0067-0049/224/1/3
ads-cite append refs.bib 2016ApJS..224....3N 2025PASP..137b4101S
ads-cite --help

Флаги

Запоминаемые citekey с --rekey

Bibcode ADS (2016ApJS..224....3N) однозначны, но их сложно набирать или запоминать при цитировании статьи по имени. --rekey преобразует каждую запись в читаемый citekey вида LastName_Subject_Year.