research-field-onboarding

<div align="center"> <img src="logo.png" alt="Field Onboarding" width="88%"/> <p> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=flat-square" alt="License"/></a> <img src="https://img.shields.io/badge/version-v1.7.0-blue?style=flat-square" alt="Version"/> <a href="https://github.com/ljx-chase/research-field-onboarding/stargazers"><img src="https://img.shields.io/github/stars/ljx-chase/research-field-onboarding?style=flat-square&color=yellow" alt="Stars"/></a> <img src="https://img.shields.io/github/last-commit/ljx-chase/research-field-onboarding/main?style=flat-square" alt="Last Commit"/> </p>

<strong>Language</strong>: <a href="README.md">English</a> | <a href="README.zh-CN.md">中文</a>

</div>

Ask an assistant about a field you don't know and it answers at the level of someone who does. This one asks which prerequisites you already have, teaches one rung per turn in whichever explanation style you pick, and never names a paper it hasn't checked.

🆕 New in v1.7.0 — you can now pick how it explains. Physical picture first, balanced, or derivation first. Same depth in all three, different order, and you can switch mid-session. Jump to the three styles.

If it helps you, a ⭐ makes it easier for other people to find. Watch the repo if you want to hear when the rules change; the changelog has moved most weeks, mostly because I keep using it on my own reading and finding places where it breaks.

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

Teaching style: 1 physical picture first (default) / 2 balanced / 3 derivation first. If no buttons appear, reply with the number.

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.

<p align="center"> <img src="demo.gif" width="900" alt="Asking about second harmonic generation: the skill lists four prerequisites and asks which ones you have used, then teaches one rung and ends with a check question."/> </p>

Pick how it explains

Same content, different order. Chosen once at the start, changeable at any time.

• Physical picture first (default) — intuition, geometry, limiting cases and concrete phenomena first, then the equations with every term interpreted.
• Balanced — intuition and formalism advance together.
• Derivation first — definitions, assumptions and the mathematical steps first, physical interpretation after.

These are teaching priorities, not difficulty levels. Nothing is dumbed down in any of them: jargon gets explained, but equations, assumptions, scales and limitations stay.

The rules

Ten 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. Separate style from level; plain language must keep the real science.
4. One rung per turn: motivation, vocabulary, framework, methods, frontier.
5. End each rung with a question the rung itself answers, not "make sense?".
6. Say where the analogy breaks, every time you use one.
7. State which sign, unit or normalization convention you are using.
8. Verified with a DOI, or labelled "from memory, unverified". No third option.
9. Say whether the field is settled before teaching it as if it were.
10. 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 separates teaching style from technical level. Choose physical-picture first, balanced, or derivation-first. The default treats you as a capable researcher entering a new field: jargon is unpacked, while mechanisms, assumptions, and equations stay. If the host exposes a structured choice tool, the agent must call it; otherwise you can reply with a single number.

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

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

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

| Section | What it helps with | |---|---| | Why this exists | The failure it was built to prevent, and what it deliberately does not do. | | Who this is for | Whether your situation matches what it was designed around. | | Quick start | Install it on Claude Code, the Claude apps, ChatGPT Skills, or Codex. | | How to invoke it | The phrasings that reliably trigger it, in English and Chinese. | | What it does differently | The rules, and why each one exists. | | Scope | When it should stay out of the way, and the one-turn test. | | The ladder | The five rungs, and how your stated target reshapes them. | | Reference discipline | Why it will not hand you a citation it has not checked. | | Example prompts | Copy-paste starting points, including one it should decline. | | Changelog | What changed, and which live session forced each change. | | Citation | Cite it in a paper, report, or project doc. |

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