Academic jobs

Academic Jobs Skill

Conversational interface over the ajo CLI, which fetches valid postings from two academic job boards and tracks them in a local SQLite store:

• AJO — Academic Jobs Online (academicjobsonline.org), HTML scraping, all fields.
• InspireHEP — the HEP/astro jobs board (inspirehep.net/jobs), via its public JSON API.

By default ajo fetch searches both boards with the same keywords and merges the results, deadline-sorted. Each posting carries a source (ajo or inspire); the two boards use overlapping integer ids, so everything is keyed by (source, id).

Quick Reference

Intent	Command	Reference
Show / edit field presets	ajo config [...]	references/presets.md
Fetch current open postings	ajo fetch [--preset N | --keyword K] [--source ajo|inspire|both] [--preferred TIERS] [--excluded LIST] [--detail-cap N]	references/fetch.md
Show stored postings	ajo list [--valid] [--new] [--source S]	references/schema.md
Inspect one posting (stored-first)	ajo show {id} [--source ajo|inspire] [--refresh]	references/fetch.md
Fetch missing detail bodies	ajo enrich [--source ajo|inspire] [--detail-cap N] [--include-expired]	references/fetch.md
Emit curation skeleton	ajo report [--source S] [--preferred TIERS] [--excluded LIST] [--out PATH]	references/curation.md
Mark postings as seen	ajo mark-seen --all	references/fetch.md
Drop expired postings	ajo prune	references/schema.md

Running the CLI

The CLI lives in this skill directory. Always invoke it through uv:

uv run --project <skill-dir> ajo <command> [...]

where <skill-dir> is the directory containing this file. Add --json to any command when you (Claude) need to post-process the output; the default is a human table.

First run auto-creates the data dir, the SQLite DB, and a default physics-ml preset.

Curation rule (read before writing a report)

Before writing any postings report, you must deep-read every posting via ajo show {id}. After ajo fetch or ajo enrich, full description bodies are stored in the DB, so ajo show reads locally (no extra network calls). Never judge a posting from its title or keyword match alone.

Every posting in a report must fill the mandatory 10-field schema:

1. 직급/seniority
2. 기관, 그룹, 국가
3. 연구주제, PI
4. 자격/eligibility
5. 기간, 급여, 시작일
6. 마감 체계 (hard/rolling/etc.)
7. 지원 서류
8. fit 근거 + 등급
9. 신빙성/주의 플래그
10. 출처 URL

Use ajo report to generate a skeleton with data-backed fields pre-filled and blank placeholders for judgment fields. The full procedure is in references/curation.md. Reports are saved to ~/Dropbox/AJO/AJO_YYYY-MM-DD.md in Korean.

Core behaviour you must understand

Two sources, one merged view

• ajo fetch runs the preset's keywords against every board in the preset's sources (default ["ajo", "inspire"]), merges, dedups within each board, and stores everything keyed by (source, id).
• Override per run with --source ajo (AJO only), --source inspire (InspireHEP only), or --source both. With an ad-hoc --keyword, both boards are searched unless --source says otherwise.
• The same preset filters apply to both boards: position_types is matched against the AJO "Position Type" and against the InspireHEP ranks (e.g. postdoc matches POSTDOC); countries is matched against the institution string (plus InspireHEP regions).

AJO validity (HTML)

Validity is judged from the detail page, not the list. The AJO list page only shows a deadline for some postings, and a missing list deadline does NOT mean "no deadline". So ajo fetch fetches each AJO candidate's detail page by default and judges validity from the effective deadline = firm Appl Deadline if present, else the listed until date. --fast skips AJO detail pages (faster but deadlines are approximate and many valid postings will be missed). Prefer the default detail mode for correctness. --fast does not affect InspireHEP.

InspireHEP validity (API)

The InspireHEP API is queried with status=open (server-side), so closed postings never arrive. The structured deadline_date is used directly, no detail fetch needed.

In both cases:

• valid → effective deadline is in the future
• expired → effective deadline has passed (excluded)
• rolling → no deadline (excluded unless --include-rolling)

Common Rules

Base directory

All state lives under ~/.local/share/academic-jobs/ (override with AJO_DATA_DIR):

• jobs.db — SQLite store of postings
• config.toml — field presets

Typical flow for "show me current openings"

1. ajo fetch --json [--preferred "KR,DE; JP,HK,GB,US"] [--excluded "IN,IL"] [--detail-cap 80] (uses the default preset; fetches details up to --detail-cap; stores + flags new). Pass --preferred/--excluded to override the preset for this run without saving. If AJO has more candidates than --detail-cap, the run is truncated; run ajo enrich in a follow-up pass to capture the remaining detail bodies politely.
2. Render the returned jobs as a table sorted by pref_tier then deadline. Surface postings with "new": true first or in a separate "New since last check" group.
3. After presenting, if the user has reviewed them, run ajo mark-seen --all so the next fetch only flags genuinely new postings.
4. To inspect one posting: ajo show {id} [--source ajo|inspire]. It reads the stored row (including the cached description body) first; it only hits the network when the row is missing, has no stored body, or --refresh is given. A live fetch is written back to the DB.

Output formatting

• Sort by deadline ascending; show source, deadline, position type, title, institution, and the posting URL (AJO https://academicjobsonline.org/ajo/jobs/{id}, InspireHEP https://inspirehep.net/jobs/{id}).
• When the user wants to know "where is this from", surface the source column. When merging, it is fine to interleave both boards by deadline; flag the source on each row.
• When emitting a structured data table back to the user, prefer TOON over JSON (per the user's global preference): declare fields once, stream rows.
• Each output row now carries country (ISO 2-letter code), region, flags, and pref_tier (integer; 0 = top tier, higher = lower preference, null = not in any tier). Results are sorted first by pref_tier ascending, then by deadline ascending within each tier. Surface pref_tier and country when presenting results so the user can see the preference grouping at a glance.
• Per-board stats live under stats.per_source in the JSON. --fast runs and any AJO detail-fetch cap truncation are reported there. Each board entry also includes an excluded count (postings dropped by excluded_countries). The AJO entry additionally reports detail_cap (the cap used for that run). Never present a truncated run as complete; mention how many candidates were judged per board and whether the detail cap was hit.

Presets

A preset bundles keywords (each runs a separate search per board, results deduped) plus optional position_types, countries, sources, preferred_countries, and excluded_countries fields. Edit with ajo config --set-preset NAME --keywords a,b --types postdoc --sources ajo,inspire. See references/presets.md.

• countries (unchanged): hard INCLUDE substring filter matched against the institution string. Only postings whose institution matches are kept.
• preferred_countries: ordered list of tiers; each tier is a list of selectors. Tier 0 is most preferred. This is a soft filter: it only reorders results (never drops). TOML example: preferred_countries = [["KR", "DE"], ["JP", "HK", "GB", "US"]]. Set via CLI: ajo config --set-preset NAME --preferred "KR,DE; JP,HK,GB,US" (; separates tiers, , separates entries within a tier). Displayed in ajo config as [KR, DE] > [JP, HK, GB, US].
• excluded_countries: flat list of selectors. Hard filter: matching postings are dropped at fetch time. TOML example: excluded_countries = ["IN", "IL", "Middle East"]. Set via ajo config --set-preset NAME --excluded "IN,IL,Middle East".
• Selectors for both preferred_countries and excluded_countries accept: an ISO 2-letter code ("KR"), a country name ("Korea"), or a region alias ("Europe", "Asia", "North America", "Middle East", "EU", "APAC", "MENA").
• position_types and sources work as before.

Etiquette

The CLI uses one polite session per board with a real User-Agent and small delays between requests, and caps AJO detail fetches per run (logged when hit). Do not parallelise or hammer either board.