| name | bibtex-gen |
| description | Generate BibTeX entries for academic references from arXiv IDs, DOIs, titles, URLs, batch lists, or reference-search JSON. Route HEP papers to InspireHEP, non-HEP papers to Google Scholar when available, and CrossRef DOI BibTeX as a fallback; preserve source-native keys and print or append to a .bib file. Use when the user asks for bibtex, citation entries, bibliography filling, arXiv/DOI/title-to-BibTeX, InspireHEP BibTeX, publisher BibTeX, or converting discovered references into a .bib file.
|
bibtex-gen — BibTeX Generator (InspireHEP / Google Scholar / CrossRef)
Generate bibtex entries by routing each query to the most authoritative
source. The skill is read-only for the user's existing .bib files
unless they pass --output, in which case new entries are appended (never
overwritten or de-duplicated — that is the user's call).
Routing logic
Each input is classified as HEP or non-HEP, then routed:
| Class | Primary source | Fallback |
|---|
| HEP | InspireHEP (format=bibtex) | non-HEP path if InspireHEP returns nothing |
| non-HEP | Google Scholar via scholarly | CrossRef DOI bibtex transform |
Classification rule: a query is HEP iff InspireHEP returns at least one
match for it. arXiv IDs additionally check the arXiv API for hep-* /
nucl-* categories as a strong pre-signal. The user can override with
--hep or --no-hep.
This intentionally aligns with the user's preference:
- HEP citations follow InspireHEP style (
Author:YYYYabc keys, journal
abbreviations, eprint fields, collaboration tagging).
- Non-HEP citations follow Google Scholar style first; if Scholar is
unavailable or returns nothing, fall back to the publisher's bibtex
via CrossRef's DOI→bibtex transform.
Inputs accepted
The orchestrator auto-detects the input type:
- arXiv ID —
2301.00001, arxiv:2301.00001, hep-ex/0511032
- DOI —
10.1103/PhysRevD.98.030001, doi:10.1..., https://doi.org/10.1...
- Title — anything else is treated as a title / free-text query
- URL — DOI URLs are parsed; arXiv URLs are normalized to arXiv IDs
Batch mode reads one query per line from a file (# comments and blank
lines ignored).
For an OpenAlex-driven discovery → citation pipeline, the orchestrator
also accepts --from-search refs.json, where refs.json is the JSON
output of the reference-search skill (openalex_search.py --format json). Each result's DOI is extracted (title fallback if no DOI) and
routed through the normal HEP / Scholar / CrossRef pipeline — so you can
run "find me 10 papers on X" and turn that into a .bib in one extra
command. See references/examples.md for the full pipeline recipe.
Bibtex key style
Each source returns its own key style; the skill preserves them verbatim:
- InspireHEP:
Smith:2024abc
- Google Scholar:
smith2024title
- CrossRef: DOI-suffix style (e.g.
Smith_2024)
Do not silently rewrite keys. If the user asks for a unified style, surface
it as an explicit follow-up step, not a side effect.
Workflow
- Confirm the input set. If the user gave a Korean / English list of
references, treat each line as one query. If they gave a single phrase,
treat it as one query.
- Decide routing override. If the user said "HEP", "high energy", "장
인용", "물리 논문" etc., pass
--hep. If they said "ML 논문", "biology
paper", etc., pass --no-hep. Otherwise let auto-classification run.
- Run the orchestrator:
uv run bibtex-gen/scripts/bibtex_gen.py "<query>" [--hep | --no-hep] \
[--output refs.bib]
For batch mode:
uv run bibtex-gen/scripts/bibtex_gen.py --batch refs.txt --output refs.bib
- Surface the bibtex. Stream to stdout by default. If
--output is set,
confirm append count to the user.
- Report failures. Any query that produced no bibtex from any source is
listed explicitly. Do not invent a bibtex entry — ask the user to refine
the query or supply a DOI.
What this skill does NOT do
- It does not deduplicate entries in the target
.bib file. Run a separate
pass if needed.
- It does not normalize keys across sources. If the user wants
FirstAuthorYear everywhere, ask before doing it.
- It does not fabricate missing fields. If a source returns sparse bibtex
(no DOI, no journal), surface it as-is.
- It does not handle paywalled publisher endpoints directly. CrossRef
bibtex is the publisher proxy and is sufficient for most journals.
Dependencies
The orchestrator carries PEP 723 inline script metadata declaring
scholarly as a dependency. When run with uv run, uv reads that header
and provisions an ephemeral environment that includes scholarly — the
user does not need to uv add or pip install anything ahead of time.
If the orchestrator is run with a bare python3 (no uv), scholarly
may be missing; in that case the Google Scholar path is skipped with a
one-line stderr note and non-HEP queries fall through to CrossRef. HEP
queries continue to work unchanged via the stdlib-only InspireHEP path.
Source notes (quick reference)
| Source | Endpoint | Auth | Stdlib only? |
|---|
| InspireHEP | https://inspirehep.net/api/literature?q={query}&format=bibtex | none | yes |
| arXiv | http://export.arxiv.org/api/query?id_list={id} (for HEP category) | none | yes |
| CrossRef | https://api.crossref.org/works/{DOI}/transform/application/x-bibtex | none | yes |
| Scholar | scholarly.search_pubs(q) → scholarly.bibtex(pub) | none | requires scholarly |
Full source-by-source semantics in references/sources.md. HEP
classification heuristics in references/hep_classification.md.
Resources
scripts/bibtex_gen.py — orchestrator; runnable as uv run scripts/bibtex_gen.py "<query>".references/sources.md — per-source API details, response shape, and gotchas.references/hep_classification.md — when a query is classified HEP vs non-HEP and how to override.references/examples.md — copy-pasteable CLI invocations (single, batch, HEP override, file append, reference-search integration).
Companion skills
reference-search — OpenAlex-based literature discovery. Use it upstream of this skill when the user has a topic / claim / section in mind but no specific paper picked out. Save its output with --format json, then run bibtex-gen --from-search <file>.json to materialize a .bib.
After creating or updating this skill, suggest starting a new session so
the new skill is discoverable from session start.
