Journal Abbrev Agent Skill

Journal Abbreviation Lookup

Look up journal/magazine name abbreviations using a multi-source cascade: JabRef database (~25K journals) → AbbrevISO API (ISO 4) → NLM Catalog (MEDLINE).

Critical rule: Always use jabbrv.py for lookups. Never guess abbreviations — even common journals have non-obvious abbreviations.

Quick Reference

| User wants... | Tier | Command |

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

| Abbreviate a journal name | read | python3 jabbrv.py abbrev "Nature Medicine" |

| Expand an abbreviation | read | python3 jabbrv.py expand "Nat. Med." |

| Auto-detect direction | read | python3 jabbrv.py lookup "J. Am. Chem. Soc." |

| Fuzzy search (paginated) | read | python3 jabbrv.py search "biolog chem" --limit 10 --offset 0 |

| Process a .bib file | write | python3 jabbrv.py bib refs.bib |

| Preview .bib changes (no write) | read | python3 jabbrv.py bib refs.bib --dry-run |

| Explicit .bib output path | write | python3 jabbrv.py bib refs.bib --output out.bib |

| Expand .bib abbreviations | write | python3 jabbrv.py bib refs.bib --expand |

| Replay-safe .bib (retry returns cached envelope) | write | python3 jabbrv.py bib refs.bib --idempotency-key run-001 |

| Batch text list | read | python3 jabbrv.py batch journals.txt |

| Batch as NDJSON stream | read | python3 jabbrv.py batch journals.txt --stream |

| Inspect cache state | read | python3 jabbrv.py cache status |

| Download missing cache files | write | python3 jabbrv.py cache update |

| Preview what update would fetch | read | python3 jabbrv.py cache update --dry-run |

| Atomic rebuild | ⚠️ destructive | python3 jabbrv.py cache rebuild --yes |

| Preview rebuild (no delete) | read | python3 jabbrv.py cache rebuild --dry-run |

| Suppress stderr progress | read | python3 jabbrv.py --quiet cache update |

| Machine-readable CLI contract | read | python3 jabbrv.py schema |

| Schema for one subcommand | read | python3 jabbrv.py schema lookup |

Output format

Stdout is a stable JSON envelope when the CLI is not attached to a terminal

(piped or captured by an agent), and a human table/indented view when run on a

TTY. To force a format: --format json|table|human|auto. --json remains as a

back-compat alias for --format json. Flags may appear before or after the

subcommand.

Envelope shape (always the same fields for every subcommand):

• Success: { "ok": true, "data": ..., "meta": { "schema_version", "cli_version", "cache", "latency_ms" } }
• Partial success (batch): { "ok": "partial", "data": { "succeeded": [...], "failed": [...] }, "meta": {...} }
• Error: { "ok": false, "error": { "code", "message", "retryable", ... }, "meta": {...} }

Exit codes

| Code | Meaning |

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

| 0 | success (including partial success) |

| 1 | runtime / upstream error |

| 2 | validation / bad input (missing file, bad flag) |

| 3 | not found (the looked-up journal does not exist) |

Error codes (inside error.code)

| Code | Retryable | Exit | Meaning |

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

| not_found | no | 3 | Lookup completed but no source matched |

| upstream_unavailable | yes | 1 | One or more upstream APIs failed transiently; the lookup could not be concluded. Carries error.sources[] listing each failure. Retry later. |

| file_not_found | no | 2 | Input file path does not exist |

| validation_error | no | 2 | Bad argument or flag combination |

| runtime_error | yes | 1 | Unexpected internal error |

Branch on error.code + error.retryable rather than exit code alone — exit

1 covers both upstream_unavailable and runtime_error. Full machine-readable

listing: python3 jabbrv.py schema → data.error_codes.

Environment variables (set by host, not by agent argv)

| Variable | Effect |

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

| JABBRV_CACHE_DIR | Override the cache directory (default: <install>/cache). Useful in sandboxes where the install tree is read-only. |

| JABBRV_OFFLINE | Truthy (1/true/yes/on) skips AbbrevISO and NLM; only the local JabRef cache is consulted. Misses become definitive not_found (not retryable) since the host has declared upstream off-limits. meta.offline: true appears in every envelope so callers can see the policy. |

| NO_COLOR | <https://no-color.org> convention. Any non-empty value disables color. No ANSI is emitted today; meta.no_color: true appears when set so callers can see the policy. |

Trust boundary: these are read from the process environment, not from

arguments. The host or sandbox sets them; the agent cannot override them via

argv. Schema introspection: python3 jabbrv.py schema → data.global_env.

Retries, idempotency, and destructive intent

• Branch on error.code + error.retryable, not exit code alone. Exit 1

covers both upstream_unavailable (retry) and runtime_error (retry once,

then escalate).

• bib --idempotency-key <token> persists the success envelope next to

the output file as <output>.<token>.envelope.json. A retry with the same

key returns that envelope with meta.idempotent_replay: true instead of

rerunning the rewrite. Token must match [A-Za-z0-9._-]{1,64}.

• cache rebuild is atomic — downloads stage into a sibling directory

and the swap only happens if every file succeeded. If any fails, the

existing cache is preserved and the response is upstream_unavailable

(retryable). Add --yes to record meta.confirmed: true for audit

policies; the CLI itself never prompts, so --yes is not a gate.

Workflow

Step 1: Detect Intent

| Intent | Action |

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

| Single journal name/abbreviation | Use lookup (auto-detect) or abbrev/expand (explicit direction) |

| "What's the abbreviation for X?" | Use abbrev |

| "What journal is X?" | Use expand |

| Partial or uncertain name | Use search for fuzzy matching |

| Fix journal names in .bib file | Use bib |

| List of journals to process | Use batch |

Step 2: Execute

Run the appropriate jabbrv.py command. The script handles:

• Local cache lookup (instant, ~25K journals from JabRef)
• AbbrevISO API fallback (algorithmic ISO 4 abbreviation, forward only)
• NLM Catalog fallback (biomedical journals, bidirectional)

First run downloads JabRef CSV cache files automatically (~2-5 MB).

Step 3: Present Results

• Show the full name, abbreviation, and source
• Note the standard (ISO 4 vs MEDLINE) when relevant
• For .bib processing: show the change summary before confirming

ISO 4 vs MEDLINE

Two common abbreviation standards exist:

| Standard | Periods | Example | Used by |

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

| ISO 4 | Yes | Nat. Med. | Most publishers, BibTeX |

| MEDLINE | No | Nat Med | PubMed, NLM databases |

JabRef provides ISO 4 style. NLM Catalog provides MEDLINE style. AbbrevISO computes ISO 4 algorithmically from LTWA (List of Title Word Abbreviations).

Common Abbreviation Patterns

| Word | Abbreviation | Word | Abbreviation |

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

| Journal | J. | International | Int. |

| American | Am. | European | Eur. |

| Science/Sciences | Sci. | Medicine/Medical | Med. |

| Biology/Biological | Biol. | Chemistry/Chemical | Chem. |

| Physics/Physical | Phys. | Engineering | Eng. |

| Research | Res. | Review/Reviews | Rev. |

| Society | Soc. | National | Natl. |

| Proceedings | Proc. | Transactions | Trans. |

| Letters | Lett. | Communications | Commun. |

| Applied | Appl. | Computational | Comput. |

Note: Single-word titles (e.g., "Nature", "Science", "Cell") are NOT abbreviated per ISO 4 rules.

Integration Examples

With Zotero

# Export BibTeX from Zotero, then standardize journal names
zot export COLLECTION_KEY --format bibtex > refs.bib
python3 jabbrv.py bib refs.bib

With LaTeX

# Before compiling, ensure all journal names are abbreviated
python3 jabbrv.py bib references.bib
# Use the output file (references_abbrev.bib) in your LaTeX document

Batch Processing

Create a text file with one journal name per line:

Nature Medicine
Journal of Biological Chemistry
Proceedings of the National Academy of Sciences

Then run:

python3 jabbrv.py batch journals.txt

Troubleshooting

| Issue | Solution |

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

| "No result found" | Try search with partial name for fuzzy matching |

| Cache download fails | Check network connection, retry with cache update (or cache rebuild to force) |

| Wrong abbreviation style | JabRef = ISO 4 (with dots), NLM = MEDLINE (no dots) |

| BibTeX field not detected | Ensure format is journal = {Name} (curly braces) |