Journal If Agent Skill

Journal Impact Factor Lookup

Look up journal impact factors using a two-source cascade: bundled CSV cache (~200 common journals) → OpenAlex API (approximate 2-year IF for any journal).

Critical rule: Always use journal_if.py for lookups. Never guess impact factors — they change yearly and vary by edition.

Quick Reference

| User wants... | Tier | Command |

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

| Look up IF of a journal | read | python3 journal_if.py lookup "Nature Medicine" |

| Search for a journal | read | python3 journal_if.py search "cancer immunology" |

| Process a list of journals | read | python3 journal_if.py batch journals.txt |

| Cache-only (no network) | read | python3 journal_if.py --offline lookup "Cell" |

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

| Refresh upstream CSV | write | python3 journal_if.py cache update |

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

| Schema for one subcommand | read | python3 journal_if.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-readable view when run on a TTY.

To force a format: --format json|table|human|auto. --json is a back-compat

alias for --format json.

Envelope shape:

• Success: { "ok": true, "data": {...}, "meta": { "schema_version", "cli_version", "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 (no journal matched) |

Error codes (inside error.code)

| Code | Retryable | Exit | Meaning |

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

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

| upstream_unavailable | yes | 1 | OpenAlex API failed transiently; retry later or use --offline |

| 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 |

Data Sources

• Bundled CSV — ~200 top journals across life sciences, medicine, chemistry, physics, and engineering. Curated from JCR data, shipped with the skill. Always available, instant.

• OpenAlex API — Free, open API that computes an approximate 2-year impact factor from citation counts. Covers virtually all academic journals. The number differs from the official JCR IF — it's a citation-rate metric computed from the same formula (citations in year Y to items published in Y-1 and Y-2, divided by citable items in those two years) but using OpenAlex's own article classification. Adequate for ranking and comparison; do not cite as "the JCR impact factor" in formal contexts.

When to use which

| Scenario | Source |

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

| Quick check of a major journal | Bundled CSV (instant) |

| Niche or newer journal | OpenAlex fallback (automatic) |

| Formal submission / grant | Note: OpenAlex IF ≠ official JCR IF. Cite only as approximate. |

| Batch processing many journals | CSV for cached ones, OpenAlex for misses |

| Offline / air-gapped | --offline flag (bundled CSV only) |

Workflow

Step 1: Detect Intent

| Intent | Action |

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

| "What's the IF of Nature?" | lookup "Nature" |

| "Compare IF of Cell and Science" | Run lookup twice, compare results |

| "Which immunology journals have IF > 20?" | search "immunology" then filter |

| "Process this list of journals" | batch journals.txt |

| "Is this a high-impact journal?" | lookup then interpret IF in field context |

Step 2: Execute

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

• Local CSV lookup (instant, ~200 curated journals)
• OpenAlex API fallback (automatic, approximate 2-year IF)
• Fuzzy matching — catches minor name variations

Step 3: Present Results

• Show the journal name, impact factor, and data year
• Note the source (CSV cache vs OpenAlex approximate)
• For search results: show a table with IF, year, and category

Understanding Impact Factor

| IF Range | Typical Tier | Example |

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

| > 30 | Elite (top 0.1%) | Nature (64.8), Science (56.9), Cell (64.5) |

| 20–30 | Exceptional (top 1%) | Cancer Cell (50.3), Immunity (32.4) |

| 10–20 | Excellent (top 5%) | Nature Communications (16.6), Sci Adv (13.6) |

| 5–10 | Strong (top 15%) | eLife (7.7), Cell Reports (8.8) |

| 2–5 | Solid | PLOS ONE (3.7), Sci Rep (4.6) |

| < 2 | Niche / new | Many field-specific and new journals |

Caveats:

• IF varies dramatically by field — a top mathematics journal may have IF < 5 while a mid-tier oncology journal has IF > 10.
• Always compare IF within the same field.
• The IF data year matters; values shift annually.
• OpenAlex approximate IF differs from official JCR IF; treat as a ranking metric, not a certified number.

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 journal_if.py batch journals.txt

Troubleshooting

| Issue | Solution |

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

| "No data found" | Try a shorter/alternative name; use search for fuzzy matching |

| OpenAlex returns 0 or None IF | The journal may be too new (needs 2+ years of data); use --offline to check cache only |

| OpenAlex IF differs from JCR | Expected — OpenAlex uses its own article classification. Use for ranking, not formal citation. |

| Cache download fails | Check network; the bundled CSV still works offline |

| Wrong journal matched | Use more specific name; the fuzzy matcher picks the closest substring match |