Research Field Onboarding

Language: English | 中文

A skill that makes an AI assistant ask what you already know before it explains an unfamiliar research field, teach one rung at a time, and label every paper it cites as verified or unverified.

Quick start

Paste this into your agent, whichever one you use:

Install the field-onboarding skill from
https://github.com/ljx-chase/research-field-onboarding, following the
installation section of the repo's AGENTS.md.

It works out where its own skills directory is. If you would rather do it by hand, AGENTS.md has the per-agent paths, and on Claude Code there is a one-liner:

npx skills add ljx-chase/research-field-onboarding -g

Claude web and ChatGPT want a zip; there is one in releases.

That is the whole setup. Users never run the bundled state script or edit its JSON; capable agents use it internally, and other agents fall back to the same prompt workflow.

Then try:

I understand nonlinear optics but not topological photonics. Guide me into the field step by step.

A good first response names the prerequisites and asks which ones you already have. It does not open with a paragraph of definitions.

Why this exists

Ask an assistant about a field you do not know, and it will answer at the level of someone who already does. The answer is correct. You cannot use it, and you cannot tell which of its twelve terms you were supposed to already know. Ask again and you get more terms.

Without it

You: Explain attention in transformers.

Assistant: Transformers replace recurrence with self-attention, projecting each token into query, key and value vectors, scoring them by dot product, normalizing with softmax, then concatenating multiple heads through a residual connection into a feed-forward block with layer norm and positional encoding.

You: Which of those am I supposed to already know?

Assistant: Self-attention maps each token to three learned projections, then takes a similarity-weighted sum over the sequence.

With it

You: Explain attention in transformers.

Assistant: Before we start: the shortest bridge from what you already know. Mark each one.

• Matrix multiplication and dot products — attention is a stack of matrix operations
• Forward pass of a neural network — how one layer turns an input into an output
• Softmax and probability normalization — this is where the attention weights come from
• Embeddings and sequence representation — how text becomes vectors the model can work on

used it / learned it / new

Twelve terms. It asks about four of them instead of throwing all twelve at you at once, then teaches from wherever you actually are, one rung per turn.

The problem is not that the model knows too little. It is that nobody asked you what you know before choosing where to start.

This skill is not a knowledge base, and it does not carry a library of field summaries. A field-specific corpus goes stale the moment it is written, and shipping five fields well would silently degrade every other field. What it carries instead is a discipline:

locate the reader first, then teach upward from there, one step at a time.

The model already knows the physics. What it lacks, by default, is the habit of asking where you are standing before it starts pointing.

The rules

Nine rules. Full text in SKILL.md.

1. Name the prerequisites yourself, don't ask "what's your background".
2. Anything marked used it is an anchor and never gets explained again.
3. One rung per turn: motivation, vocabulary, framework, methods, frontier.
4. End each rung with a question the rung itself answers, not "make sense?".
5. Say where the analogy breaks, every time you use one.
6. State which sign, unit or normalization convention you are using.
7. Verified with a DOI, or labelled "from memory, unverified". No third option.
8. Say whether the field is settled before teaching it as if it were.
9. Answer short questions short. Offer the ladder once, then drop it.

What it does differently

1. It names your gaps for you. Not "what's your background?" — you cannot audit a gap you cannot see. The agent works out the three to five upstream frameworks the topic actually rests on, lists them with a one-clause gloss, and asks you to mark each as used it, learned it, or new. Then it uses the marks: anchors are never re-taught, black boxes are declared as black boxes, and a load-bearing gap gets built before anything stands on it.

2. It teaches one rung at a time. Motivation, vocabulary, core framework, methods, frontier. Each rung is one turn and ends with a real diagnostic — a prediction, a restatement, a forced choice — not "does that make sense?", which always gets a yes. Wrong answers get a different explanation, not a louder one.

3. It will not invent a reference. Reading paths are where models fabricate, and a plausible title with a plausible year costs you an afternoon. Every named work is either verified in-session with a DOI or arXiv ID, or explicitly labelled from memory, unverified. There is no third option, and an identifier that was not retrieved is never attached.

4. It knows when to stay out of the way. Ask a narrow factual question and you get a narrow factual answer. The ladder is offered once, in one line, and dropped if you do not take it.

Who this is for

This is built around a specific situation: you are competent somewhere, and you need to get oriented somewhere else.

• Graduate students and postdocs reading outside their specialty, where the hard part is not intelligence but knowing which of the unfamiliar terms you are allowed to skip.
• Researchers evaluating a method from a neighbouring field, who need to decide whether it fits their problem rather than to master it.
• Anyone who has been burned by a fabricated citation, and wants a reading path where every item is labelled.
• Reviewers, examiners, and supervisors who have to parse a manuscript outside their area.

It is deliberately less useful if you are a specialist asking inside your own field, or if you want a one-line factual answer. In both cases it is designed to get out of the way. See Scope.

How to invoke it

Triggering is governed by the description in field-onboarding/SKILL.md, not by a magic word. Anything that signals I do not know this field yet should work. The reliable patterns:

• Name the field and ask to be taken through it. Guide me into <field> step by step. I'm new to <field> — walk me through it.
• State your bridge. I know <what you have> but not <field>. This is the strongest form: it hands the agent an anchor before it has to ask.
• Hand it text. Paste an abstract, a figure caption, a referee comment, and ask what it is saying.
• Ask for a path. Give me a reading path into <field>.
• Say the last answer failed. That was too technical — start further back.
• Say what it is for. I need to build a <setup>, teach me what I need. The stated target changes the shape and length of every rung, so saying it up front is worth a sentence.

Chinese works the same: 一步一步带我入门<领域>、这篇摘要看不懂、给我一条<领域>的阅读路径。

Quick navigation

Scope: when it fires, and when it does not

It should run when you are new to a field, cannot parse a paper or abstract, ask for a step-by-step walkthrough or a reading path, or say an explanation was too technical. It fires even if you only name an unfamiliar field without asking to be taught.

It should not run when the question is narrow and factual, when you are a specialist asking inside your own field, when you asked for it short, when the task is translation, editing, formatting, debugging or a search with a known target, when you are blocked mid-experiment and need the fix, or when you already declined the ladder earlier in the session.

The governing heuristic is the one-turn test: if a single turn answers the question well, the agent answers it and then offers the ladder once. Answer first, offer second.

The ladder

Your target routes the whole ladder, not just its length. Reading a paper weights notation and formalism; judging whether a method fits your work leads with phenomena and worked numbers and expands Rung 4; doing it hands-on turns Rung 4 into a procedure. At the end the agent produces a takeaway you keep: the glossary, the reading path, the field's open questions, and the prerequisites you still have not covered.

For supplied text it switches to Decode mode instead, separating source claim, background, inference, and critique so you can see which is which.

Reference discipline

• Verified — looked up in this session, with DOI, arXiv ID, or journal/volume/page.
• From memory, unverified — believed to exist, not checked, and labelled in those words.

Bare unlabelled citations are not permitted. Where verification is impossible, the skill gives an executable search pointer — venue, group, query — instead of a citation, and prefers three verified items to seven unverified ones.

It also states its conventions. Where a field uses competing sign, phase, unit or normalization conventions, the agent says which one it is using and names the alternative, because a reader who cannot map the equation onto the paper's equation has not been onboarded.

Example prompts

• I am new to exciton-polaritons. Walk me through the field step by step.
• I understand nonlinear optics but not topological photonics. Help me get oriented.
• I cannot parse this abstract. Explain what it is actually saying.
• Give me a reading path into chiral phonons.
• 一步一步带我入门拓扑光子学。

And one it should not take over:

• Quick one: what does MRO stand for in this field? — expect a direct answer plus a one-line offer, not a prerequisite checklist.

Repository structure

research-field-onboarding/
├── README.md
├── README.zh-CN.md
├── AGENTS.md                   # entrypoint for repository-aware agents
├── CONTRIBUTING.md
├── LICENSE
├── .gitignore
├── logo.png
├── docs/
│   ├── before-after.svg        # README graphic (English)
│   ├── before-after-zh.svg     # README graphic (Chinese)
│   ├── logo.svg                # vector source of the banner
│   ├── logo-zh.png             # banner, Chinese
│   └── logo-icon.png           # square mark, for avatars and previews
├── tools/
│   ├── make_demo.py            # regenerates the SVGs, and PNGs on demand
│   └── make_logo.py            # regenerates the logo files
└── field-onboarding/
    ├── SKILL.md                # the canonical instruction document
    ├── agents/
    │   └── openai.yaml
    ├── scripts/
    │   └── knowledge_state.py  # optional invisible session-state helper
    └── references/
        ├── examples.md         # positive and negative behavioral examples
        ├── evals.md            # regression set, run before merging a change
        ├── pacing.md           # per-target word budgets and routing
        ├── unsettled-fields.md # grounded mode, and when to refuse
        ├── citations.md        # the verified / unverified rule
        ├── checkpoints.md      # question types and branching
        ├── decode-mode.md      # handling supplied text
        ├── state-runtime.md    # capability gate and internal state workflow
        ├── anti-patterns.md    # ways this has failed
        └── search-recipes.md   # open-API query templates for verification

SKILL.md is the single source of truth. Everything else is packaging.

Design principles

• Answer first, offer the ladder second. Never put an intake questionnaire in front of a one-line question.
• One conceptual rung per turn by default.
• Define jargon on first use, and state which convention you are using.
• Anchor new concepts to the user's existing expertise, then say where the analogy breaks. An analogy the user over-trusts is worse than no analogy.
• Separate source claims, background knowledge, inference, and critique.
• Never invent a reference. Verified or labelled unverified, with no third option.
• Use diagnostic checkpoints instead of generic comprehension questions.
• Close with something the user keeps.
• Degrade gracefully when an agent lacks browsing, file access, or interactivity.

Changelog

v1.6.0

• Added optional agent-managed state. Capable agents can use the dependency-free scripts/knowledge_state.py helper to track a multi-turn learning ladder without exposing commands, JSON, or storage details to the learner.
• Kept the skill portable. Agents without Python or temporary-file access fall back to the existing prompt-only behavior, and one-turn explanations do not start the runtime.
• Made progress auditable. The state model separates self-report, evidence, and coverage; validates prerequisites and cycles; writes atomically; and supports idempotent operation IDs.
• Added runtime guidance and tests. references/state-runtime.md, positive and negative eval cases, and deterministic unit tests document and verify the new behavior.

v1.5.0

No behavior was added in this release. Both changes exist because the instruction file had grown past the length at which rules are reliably followed.

• SKILL.md is now a control plane. It had reached about 4,000 words, and two rules had already been observed going unfollowed at a shorter length. Unsettled-field handling, decode mode, citation labelling, pacing, checkpoint mechanics, and anti-patterns moved into references/ and are loaded when the moment for them arrives. The entrypoint is down to roughly 2,700 words with no rule removed.
• Added references/evals.md: six negative cases, ten positive ones, and a multilingual pair, each with a binary pass condition. Contributing now requires running the relevant cases in a fresh session and pasting the results. The set includes the two failures that live testing found, so neither can silently return.

v1.4.0

• The skill now checks how settled a field is before teaching it, and says which of three states applies: settled, emerging or contested, or not reliably known. The register the reader gets should tell them whether they are receiving consensus or a reconstruction.
• Grounded mode for unsettled fields. Where no textbook exists, the standard "just be correct" is not available: central claims are attributed to specific work under the usual verification labels, unstable vocabulary is flagged with its competing usages, Rung 5 is built from groups rather than a canonical review, and the agent states how old its picture is. Citations stay out of settled-field teaching, where each citation slot is only a chance to fabricate.
• A stated refusal. When the field is too new for a reliable picture and there is no way to search, the skill says so and hands over a query instead of teaching, rather than filling the gap with plausible structure.
• Target artifacts close the loop. A reader who arrives saying "I want to read this paper" is told at the start which rungs stand between them and it, and at the end whether they can now read it and what is still likely to block them.
• Added references/search-recipes.md: OpenAlex, Crossref, and arXiv query templates for checking whether a review exists, testing how current a picture is, and verifying that a specific paper exists. All open APIs, no key, runnable in a browser.

v1.3.0

Three fixes from a live SHG onboarding session.

• Checkpoints must be scoped to the rung just taught. The session produced a question that needed a scaling law the rung never stated, so a wrong answer tested the explanation rather than the reader. The skill now requires that you be able to point at the sentence containing the answer, and that a user who marked exactly these prerequisites could answer it.
• Anchors no longer widen silently. Marking "lasers in practice" as used it does not license assuming femtosecond pulses. A rung that needs a narrower sub-skill inside an anchor must name it and explain it, or ask.
• Length is now set by the target, with a per-target table. Someone building an apparatus gets Rung 1 in 100-200 words and the session spent on Rungs 3 and 4; someone reading a paper gets the reverse weighting.

v1.2.0

• Conventions rule. The agent must state which sign, phase, unit or normalization convention it is using, and name the competing one. Mismatched conventions are a common silent failure when moving between an explanation and a paper.
• The target now routes the whole ladder, not just which rung gets expanded. Reading a paper, judging a method's fit, hands-on work and following a talk each get a different shape.
• Closing artifact. Sessions end with a takeaway the user keeps: glossary, labelled reading path, the field's open questions, and uncovered prerequisites.
• Word budget raised to roughly 200–500 words per rung and up to 700 for Rung 3, which could not fit a motivated framework plus a worked example plus its limits in the old ceiling.

v1.1.2

• Removed the committed PNG rasters. They were derived artifacts duplicating the SVGs, and as the only binary files in the repository they were the ones that failed on a constrained git clone. tools/make_demo.py --png regenerates them when a raster is needed.

v1.1.1

• Step 0 now requires an interactive checklist wherever the interface has one, with a plain table as the explicit fallback. The previous wording (Use a checklist or multi-select control if the interface offers one) was a conditional clause, and in live testing it was skipped: the prerequisite list was printed as a static table and the user had to type their marks back. Same hardening applied to the checkpoint quiz.
• Added a matching anti-pattern.

v1.1.0

• Added a When not to use this skill section and the one-turn test, plus a matching Do not use for ... clause in the frontmatter description. The skill previously had broad positive triggers and no negative ones, so it over-fired on narrow questions.
• Added a Naming literature section making the verified / from memory, unverified label mandatory for every named work, and forbidding unretrieved identifiers.
• Restored the imperative register of the instruction text throughout. Normative prose was replaced with direct rules, which agents follow more reliably.
• Added handling for the two most common real-session behaviors: the user ignoring the prerequisite checklist, and the user skipping the checkpoint with "continue".
• Added references/examples.md cases for a negative trigger and for a labelled reading path.

v1.0.0

• Initial public release.

Contributing

Contributions are welcome, particularly behavioral examples from disciplines other than the physical sciences, and negative cases where the skill fires when it should not. See CONTRIBUTING.md.

Feedback

If you try this and it gets something wrong, please open an issue. Every entry in the changelog above came from someone using it and telling me where it broke, and that is worth more to me than a star. Prerequisites that were wrong for your field, a checkpoint question you couldn't answer from the rung, a citation that turned out not to exist: all of it is useful, and the eval set exists so a fix doesn't quietly break something else.

If it was useful, a star helps other people find it. Watching the repo will tell you when the rules change, which a star won't.

Citation

If this skill helps your reading or your teaching, you can cite the repository:

@misc{field_onboarding_2026,
  title        = {Field Onboarding: a cross-agent skill for step-by-step onboarding
                  into unfamiliar research fields},
  author       = {Li, Junxiang and Zhou, Ziyan},
  year         = {2026},
  howpublished = {\url{https://github.com/ljx-chase/research-field-onboarding}},
  note         = {GitHub repository}
}

Acknowledgments

The SKILL.md format follows Anthropic's Agent Skills convention, which is what makes the same file run under Claude Code, ChatGPT Skills, and Codex without modification.

Several changes in the changelog came from people using it and telling me where it broke. That is worth more than a feature request, and it is the contribution I most want.

License

MIT License. Copyright (c) 2026 LI Junxiang and Ziyan Zhou (Anna).