academic-jobs
Skill4 starsChanged 20 days agoMITView on GitHub
Find and curate academic opportunities through AJO/InspireHEP and official institution/group-direct recruitment. Broad personal postdoc searches include both tracks by default, with one deduplicated result separating current vacancies, standing application routes, research-fit leads and conflicting/expired evidence. Respect explicit board-only requests; support named labs, changes since a previous search, field presets, stored postings and individual posting inspection. Triggers: academic jobs, AJO, InspireHEP, postdoc openings, Physics and AI jobs, research-group recruitment, 포닥 공고, 채용 공고, 연구실 채용, 잡 마켓.
In this repository38 other files it gives its agents.
- academic-cvSkill
- academic-proseSkill
- adversarial-reviewSkill
- bibtex-genSkill
- chrome-sessionSkill
- clickup-cliSkill
- clickup-todaySkill
- commit-triageSkill
- concept-explainerSkill
- contact-emailSkill
- cover-letterSkill
- dropboxSkill
- handdrawn-schematicSkill
- hep-rumor-millSkill
- journal-club-reviewSkill
- magi-researchSkill
- md2pdf-typoraSkill
- morgenSkill
- overleaf-section-workflowSkill
- overleapSkill
- peer-agent-reviewSkill
- proton-mailSkill
- reference-searchSkill
- remarkable-syncSkill
- research-backupSkill
- research-boardSkill
- research-logSkill
- research-portalSkill
- research-proposalSkill
- research-reportSkill
- research-statementSkill
- scienceplot-pySkill
- vastaiSkill
- wide-slide-illustratorSkill
- workshop-paper-reviewSkill
- xkcd-pySkill
- zai-web-searchSkill
- zoom-summarySkill
The file
We split this skill into the rules it gives an agent
11 rules. About 0 are common, 5 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 44
Read official research, recruitment policy and linked calls.
- Very specific: line 51
Follow the full-body extraction instructions in references/curation.md when display truncation hides conditions.
- Distinctive: line 65
Research-fit leads: no verified hiring, ranked by fit.
- Distinctive: line 68
Use the ten-field curation contract below.
- Distinctive: line 128
Every posting in a report must fill the mandatory 10-field schema:
- Very specific: line 141
Use ajo report only for the board skeleton, then add verified direct records and the integrated result sections.
- Very specific: line 188
If AJO has more candidates than --detail-cap, the run is truncated.
- Very specific: line 192
After presenting, if the user has reviewed them, run ajo mark-seen --all so the next fetch only flags genuinely new postings.
- Very specific: line 205
When the user wants to know "where is this from", surface the source column.
- Distinctive: line 207
When emitting a structured data table back to the user, prefer TOON over JSON (per the user's global preference): declare fields once, …
- Distinctive: line 228
Only postings whose institution matches are kept.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Academic Jobs Skill
The user-facing entry point for academic opportunity discovery. Broad postdoc
curation runs both board searches and official institution/group-direct discovery.
The user does not need another skill. The ajo CLI remains the board collector;
this integration changes the assistant workflow, not CLI source options.
Request routing
| Request | Execution |
| Broad personal postdoc search, e.g. Physics×AI 포닥을 추려줘 | Both boards plus bounded official institution/group discovery; one integrated result |
| Explicit AJO-only / Inspire-only / board postings only | Only the requested board(s); no direct expansion |
| Named lab/institution, e.g. Tübingen AI postdocs | Official research and recruitment pages first; board identity checks for duplicates, no global fetch |
| Changes since previous search | Refresh the previous scope in both tracks and compare snapshots; preserve any explicit board-only restriction |
| Maintenance: config/list/show/enrich/mark-seen/prune, including “검색 preset 설정을 보여줘” | Maintenance only: execute the requested CLI operation, no board search, direct discovery or snapshot comparison |
| Faculty or PhD opportunities | Rank-appropriate board and employer sources; do not use the postdoc-only direct ledger for other ranks |
Integrated curation workflow
- Ground rank, research/method axes, target start and region policy in the current profile, saved preset and user decisions. Use the same policy in both tracks.
- For broad postdoc searches, execute the board flow below AND references/direct-discovery.md. Start with 2–3 relevant institutional ecosystems in preferred regions and declare the scope; expand for promising leads or requested breadth. This is not a global census or a quota of recommendations. Do not ask whether to add this track. When Europe is in scope, also read recent academics.de and AcademicPositions alert mails from Proton Mail as leads (never scrape either site; see the alert-mail section of the direct reference).
- Read official research, recruitment policy and linked calls. The direct reference
owns the evidence/status schema and uses the bundled
scripts/direct_ledger.pyvalidator/diff. No managed or externally installed companion skill is required. Reuse board results for identity checks rather than recursively restarting this workflow. - Deep-read both sources. Board candidates require
ajo showand the complete stored body; direct candidates require the official page and linked call. Follow the full-body extraction instructions inreferences/curation.mdwhen display truncation hides conditions. Targeted untyped searches can recover blank/mixed-rank fellowships; verify the postdoc branch in the body. - Deduplicate verified identical appointments by employer, group/PI, project,
reference number, dates and application URL. Preserve all source links and
(source,id)matches in one row. Different projects remain separate; a general application route is not an extra vacancy. A local DB miss does not prove absence from either live board. - Deliver ONE result with four sections:
- Current applicant-facing vacancies: verified board and direct vacancies together, preference tier then actual application urgency; no invented dates for undated rolling calls.
- Standing application routes: ongoing applications, current funded capacity not established.
- Research-fit leads: no verified hiring, ranked by fit.
- Conflicting/expired/closed or host-funding-only findings: reasons and evidence, excluded from open-vacancy totals. Host support is not employment.
- Use the ten-field curation contract below. Separate method fit, scientific-domain fit, transition cost and start compatibility. Fit is not selection probability. Missing facts remain 명시 없음/null. An open banner against an expired linked PDF is a conflict, not permission to ignore the deadline.
- Report board candidates/details/truncation, direct institutions/groups/calls actually read, and deduplicated counts by status. Do not sum overlapping fetches as unique jobs. Distinguish newly discovered records from newly posted calls.
- Store direct evidence separately under
~/.local/share/academic-direct-opportunities/, never as fabricated valid rows in AJO jobs.db. Validate dated snapshots and compare them with the bundled helper. Refresh sources before claiming a change; unobserved records and failed URLs are not automatically closed.
Mail, applications, calendar tasks, scheduled watchers, pruning and mark-seen are not implicit in discovery. Respect the user's authorization for each.
Board collector
The ajo CLI fetches valid postings from two boards into 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 |
| Integrated postdoc curation | Board CLI + official-source research | references/direct-discovery.md, references/curation.md |
| Validate / compare direct snapshots | python3 scripts/direct_ledger.py validate FILE / diff BEFORE AFTER | references/direct-discovery.md |
| 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)
Deep-read every reported board posting with ajo show {id} --source S and its
complete stored body. For direct opportunities, read the official recruitment page
and linked call. Never judge either source from titles or keyword matches alone.
Every posting in a report must fill the mandatory 10-field schema:
- 직급/seniority
- 기관, 그룹, 국가
- 연구주제, PI
- 자격/eligibility
- 기간, 급여, 시작일
- 마감 체계 (hard/rolling/etc.)
- 지원 서류
- fit 근거 + 등급
- 신빙성/주의 플래그
- 출처 URL
Use ajo report only for the board skeleton, then add verified direct records and
the integrated result sections. The complete curation 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 board sources, one CLI view
ajo fetchruns the preset's keywords against every board in the preset'ssources(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--sourcesays otherwise. - The same preset filters apply to both boards:
position_typesis matched against the AJO "Position Type" and against the InspireHEPranks(e.g.postdocmatchesPOSTDOC);countriesis matched against the institution string (plus InspireHEPregions).
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
Board CLI state lives under ~/.local/share/academic-jobs/ (override with AJO_DATA_DIR):
jobs.db— SQLite store of postingsconfig.toml— field presets
Board-track execution (not the whole integrated search)
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/--excludedto override the preset for this run without saving. If AJO has more candidates than--detail-cap, the run is truncated; runajo enrichin a follow-up pass to capture the remaining detail bodies politely.- Render the returned
jobsas a table sorted bypref_tierthen deadline. Surface postings with"new": truefirst or in a separate "New since last check" group. - After presenting, if the user has reviewed them, run
ajo mark-seen --allso the next fetch only flags genuinely new postings. - 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--refreshis given. A live fetch is written back to the DB.
Output formatting
- For broad searches, use the integrated sections above. CLI fields below describe board records; label direct sources and annotate country/preference tier using the same active policy.
- Sort by deadline ascending; show source, deadline, position type, title, institution, and
the posting URL (AJO
https://academicjobsonline.org/ajo/jobs/{id}, InspireHEPhttps://inspirehep.net/jobs/{id}). - When the user wants to know "where is this from", surface the
sourcecolumn. 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, andpref_tier(integer; 0 = top tier, higher = lower preference, null = not in any tier). Results are sorted first bypref_tierascending, then by deadline ascending within each tier. Surfacepref_tierandcountrywhen presenting results so the user can see the preference grouping at a glance. - Per-board stats live under
stats.per_sourcein the JSON.--fastruns and any AJO detail-fetch cap truncation are reported there. Each board entry also includes anexcludedcount (postings dropped byexcluded_countries). The AJO entry additionally reportsdetail_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 inajo configas[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 viaajo config --set-preset NAME --excluded "IN,IL,Middle East".- Selectors for both
preferred_countriesandexcluded_countriesaccept: an ISO 2-letter code ("KR"), a country name ("Korea"), or a region alias ("Europe","Asia","North America","Middle East","EU","APAC","MENA"). position_typesandsourceswork 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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

