Journal Meta Agent Skill

Paper Metadata Lookup

Resolve one paper identifier into a full metadata record. Primary source is

OpenAlex (free, no API key); Crossref is a fallback for DOIs OpenAlex

hasn't indexed. The journal name is enriched by delegating to two sibling

skills when installed:

• journal-abbrev → ISO-4 / MEDLINE journal abbreviation (JabRef cache, ~25K journals)
• journal-if → curated JCR impact factor

If those skills aren't found, it falls back to AbbrevISO (abbreviation) and

OpenAlex 2yr_mean_citedness (approximate IF) automatically.

Critical rule: Always use journal_meta.py. Never fabricate authors,

corresponding authors, dates, or impact factors — resolve them.

Quick Reference

| User wants... | Command |

| --------------- | --------- |

| Metadata from a DOI | python3 journal_meta.py "10.1038/s41586-020-2649-2" |

| Metadata from a PMID | python3 journal_meta.py 32939066 |

| Metadata from an arXiv id | python3 journal_meta.py 1706.03762 |

| Metadata from a title | python3 journal_meta.py "Attention is all you need" |

| Process a list | python3 journal_meta.py batch papers.txt |

| Skip impact-factor lookup | python3 journal_meta.py <id> --no-if |

| Skip abbreviation lookup | python3 journal_meta.py <id> --no-abbrev |

| Machine-readable contract | python3 journal_meta.py schema |

The subcommand lookup is optional — a bare identifier works. Identifier type

(DOI / PMID / arXiv / OpenAlex id / title) is auto-detected.

Output format

Stdout is a stable JSON envelope when piped/captured, and a human key-value

view on a TTY. Force it with --format json|human|auto (--json = --format json).

Envelope: { "ok": true, "data": {...}, "meta": { "schema_version", "cli_version", "sources", "latency_ms" } }.

meta.sources records where each field came from (e.g. journal-abbrev (JabRef),

journal-if (local cache), or a fallback), so you can tell curated data from approximations.

Data fields (data)

title, authors (list), author_count, first_author, corresponding_authors

(list; empty if OpenAlex has no corresponding flag for the record),

publication_date, year, journal, journal_abbrev, impact_factor,

impact_factor_source, impact_factor_year, volume, issue, pages,

doi, pmid, openalex, issn, type, is_oa, cited_by_count, abstract.

Exit codes

| Code | Meaning |

|------|---------|

| 0 | success |

| 1 | runtime / upstream error (retryable) |

| 2 | validation / bad input (missing file, empty query) |

| 3 | not found (no paper matched) |

Workflow

• Identify the input. A DOI (10.x/...), PMID (digits), arXiv id

(NNNN.NNNNN), OpenAlex id (W...), or a title string — all auto-detected.

Prefer a DOI or PMID: title search returns OpenAlex's single top match,

which for very common titles can be a preprint or re-indexed copy rather than

the version of record. Confirm the returned DOI/year if the user gave a title.

• Run python3 journal_meta.py <id>.
• Present the fields the user asked for. For a full citation, use

first_author, journal_abbrev, year, volume, issue, pages, doi.

State the impact_factor_source when reporting IF — a curated JCR number and

an OpenAlex approximation are not the same thing.

Notes & caveats

• Corresponding author comes from OpenAlex's is_corresponding flag, which

is only populated when the publisher supplied it. An empty list means "not

marked in the metadata," not "there is none" — say so rather than guessing.

• Impact factor from journal-if is curated JCR; the fallback is OpenAlex's

2-year mean citedness, which differs from the official JCR IF. Cite formally

only the curated value, and flag approximations.

• arXiv ids resolve via the arXiv DataCite DOI (10.48550/arXiv.<id>); if a

preprint isn't indexed there, it falls back to a title search.

Environment variables

| Variable | Effect |

| ---------- | -------- |

| JOURNAL_META_MAILTO / OPENALEX_MAILTO | Email for OpenAlex's polite pool (faster, recommended). |

| JOURNAL_ABBREV_CLI | Explicit path to journal-abbrev's jabbrv.py (skips auto-discovery). |

| JOURNAL_IF_CLI | Explicit path to journal-if's journal_if.py. |

If the sibling skills live in a non-standard location, set these so enrichment

uses their curated data instead of the built-in fallbacks.

Troubleshooting

| Issue | Solution |

| ------- | ---------- |

| IF shows "OpenAlex ... (approx)" not JCR | journal-if not found — install it or set JOURNAL_IF_CLI. |

| Abbreviation looks wrong / same as full name | Single-word titles (Nature, Cell, Science) are not abbreviated per ISO 4. For others, journal-abbrev gives the ISO-4 form. |

| Title search returned the wrong paper | Use the DOI or PMID instead — title search takes OpenAlex's top hit only. |

| not_found on a brand-new DOI | OpenAlex indexing lags; the Crossref fallback covers most, but the newest DOIs may need a day. |

| corresponding_authors is empty | The publisher didn't mark it in the metadata; don't infer one. |