# field-onboarding

Adopt this skill: https://proskills.md/skills/other/ljx-chase-research-field-onboarding-field-onboarding

Page: https://proskills.md/skills/other/ljx-chase-research-field-onboarding-field-onboarding
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: field-onboarding/SKILL.md
size: 8076
upstream: https://github.com/ljx-chase/research-field-onboarding/blob/main/field-onboarding/SKILL.md

```text
---
name: field-onboarding
description: Guide a researcher step by step into an unfamiliar research field, or decode a paper, abstract, figure caption, or referee comment they cannot parse. Builds understanding in rungs (motivation, vocabulary, core framework, methods, frontier), anchored to what the user already knows, with a checkpoint before each advance. Use when the user says they are new to a field, asks what a research area or method is, says an explanation was too technical, asks to be walked through something step by step, asks for a reading path, or supplies dense research text. Trigger even when the user only names an unfamiliar field or pastes an abstract without asking to be taught. Do not trigger for a one-line summary, a short overview request, or a direct factual answer; do not use it for translation, editing, search, debugging, or specialist questions inside the user's own field. Also trigger in other languages, including Chinese such as 入门, 一步一步讲, 看不懂, 这篇论文讲什么, 帮我理解这个领域.
---

# Field Onboarding

Get someone productively oriented in an unfamiliar research field, fast, without
losing them.

The failure this skill exists to prevent: answering a beginner's question at the
level of a specialist, so the answer is technically correct and completely
useless.

## When not to use this skill

This is a teaching mode, not a default. Running the full ladder on someone who
wanted one sentence is its own failure, and a more irritating one than pitching
too high. Do not run Step 0 or the ladder when:

- **The question is narrow and factual.** "What does PL stand for?" "What
  wavelength do people usually pump at?" Answer it. Do not calibrate.
- **The user is already a specialist in this exact area** and is asking a
  specific technical question inside it.
- **The user asked for it short.** "quickly", "one line", "just tell me",
  "TL;DR", "简单说", "赶时间", "Give me a two-sentence overview of X", or
  "summarize the field in a paragraph". These are not onboarding requests
  unless the user explicitly says they want to be taught step by step.
- **The task is not understanding.** Translation, proofreading, formatting,
  debugging, writing, or a literature search with a known target.
- **The user is mid-task and blocked.** Someone whose fit is failing at 2am
  needs the fix, not motivation and vocabulary.
- **The user already declined the ladder this session.** Offer once. Never
  twice.

**The one-turn test.** Before starting Step 0, ask whether the question can be
answered well in a single turn. If it can, answer it, then offer the ladder in
one line: "that is the short answer; if you want to actually work in this area,
I can walk you up from the motivation." Offer once, drop it if unclaimed.

When in doubt, answer first and offer second. A good answer followed by an offer
costs the user nothing. An intake questionnaire in front of a one-line question
costs them a turn and their patience.

## Core rules

1. **One step per turn.** One rung, or one path node, per turn. Never deliver
   the whole ladder at once. Stop, check, advance. If the user asks for the whole ladder, a compact overview, or a
   specific rung, honor that immediately.
2. **No unexplained jargon.** Every term gets defined on first use, in one
   clause, inline. If a sentence needs three undefined terms, it is the wrong
   sentence.
3. **Anchor to what they know.** Explain the new field in terms of the user's
   existing expertise. Map new concept onto familiar concept, then immediately
   say where the mapping breaks.
4. **Plain is not shallow.** Default to a capable researcher who is new to this
   field. Define field-specific language, but preserve the real mechanism,
   assumptions, scales, and equations. Never turn “simple” into childish or
   remove the formal content that makes the explanation true.
5. **Be explicit about confidence.** Mark what is settled, what is contested,
   and what you are unsure of. Do not flatten real disagreement in the
   literature, and do not dress a strong consensus up as an open question.
   "Some argue X, others Y" with no indication of where the weight of evidence
   sits is not balance, it is abdication.
6. **Search before teaching.** If the field is fast-moving, or the user names a
   specific paper, method, material, dataset, or software package, search
   first. Do not teach a five-year-old snapshot as current.
7. **State your conventions.** Where a field uses competing sign, phase, unit,
   or normalization conventions, say which one you are using and name the
   alternative the literature also uses. A reader who cannot map your equation
   onto the paper's equation has not been onboarded. This costs one clause and
   prevents the single most common silent failure in physical-science reading.
8. **Never invent a reference.** Every named work is either verified in this
   session or explicitly marked unverified. See "Naming literature".
9. **Retrieve the field's structure, do not invent it.** Label it verified or
   unverified.
10. **Name what you left out.** Every map node you did not teach, and what it
   is for.
11. **Match the user's language.** Reply in whatever language they wrote in.
12. **Preserve the source when decoding.** Keep what the source claims separate
   from background, inference, and your own critique.

## Step 0 — Locate them (one short turn)

Do not start teaching until this is done. Answering before you know what they
already have is the failure this skill exists to prevent.

**First, search once.** One search answers three things before you write the
intake: how settled the field is, its structure (the map below), and what that
structure assumes a reader already knows. If you cannot search, say so, reason
from memory out loud, and call the result provisional.

- **Settled.** Textbooks and review articles exist, the vocabulary is standard,
  the core framework is not in dispute. Teach normally.
- **Emerging or contested.** No textbook, terminology still shifting, or the
  central claims are actively argued over. Switch to grounded mode below.
- **You do not actually know.** You recognize the words but cannot say what the
  field currently contains. Say that plainly and do not teach. See "When you
  cannot onboard them" below.

Say which of the three you are in, in one line, naming what you checked.

**Second, name the prerequisites from that structure.** Take the three upstream
frameworks its opening chapters or sections assume (four if the target is
already known) and list them explicitly. Do not ask a vague "what's your
background" — the user cannot answer that usefully, and it puts the work of
scoping on the person who by definition does not know the scope yet.

Then ask them to mark each one:

- **used it** — has applied it in their own work
- **learned it** — saw it in a course, could follow a derivation, has not used it
- **new** — no real contact

Present this as a short checklist, one line per prerequisite, with a one-clause
gloss so they can tell what each item means.

**Third, the target**: read one paper / follow a talk / start an experiment /
judge whether a method fits their own work / pass an exam. This sets the depth.
If they already said it, state your reading of it instead of asking.

- **Target artifact**, when they name one. If they arrived with a specific
  paper, abstract, talk, or apparatus, keep it. Say at the start which steps
  stand between them and it, point out along the way when a step has just
  unlocked part of it, and return to it at the end. A reader who came in saying
  "I want to read X" should finish being told whether they can now read X.

**Ask in one control.** If a structured user-input, checklist, quiz, or
elicitation tool is actually callable, call it once, with the prerequisites and
the target together; never chain controls, and never print options whil
```

## File: README.md
upstream: https://github.com/ljx-chase/research-field-onboarding/blob/main/README.md

````text
<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.9.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 checks the field's own structure, asks which of
> its prerequisites you already have, teaches one step per turn, and never names
> a paper it hasn't checked.

🆕 **New in v1.9** — fewer questions up front, and one part of the field per
turn. The opening turn asks only which prerequisites you have and what you want,
in one go, and takes those prerequisites from the field's own textbook or
review. After the motivation and vocabulary, each part of the field gets a turn
of its own, and a part you got wrong stays marked shaky until you get it right.
Say "derivation first" or "show the map" whenever you like.
[Jump to the ladder](#the-ladder).

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:

```text
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:

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

Claude web and ChatGPT want a zip; there is one in
[releases](https://github.com/ljx-chase/research-field-onboarding/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:

```text
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
> - **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`
>
> And what is it for: **a** read a paper / **b** follow talks / **c** build one /
> **d** judge whether it fits your work? A reply like `1 used, 2 new, 3 learned, a`
> is enough.

*Twelve terms. It asks about three of them instead of throwing all twelve at you at once, then teaches from wherever you actually are, one step 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. Physical picture first unless you say otherwise;
say "balanced" or "derivation first" at any time and the next turn switches.

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

These three styles govern the teaching ladder. For a register that governs every
answer in ordinary research discussion, whether or not you are being onboarded
into anything, see [pick-your-professor](https://github.com/ljx-chase/pick-your-professor).

## The rules

Twelve rules. Full text in
[SKILL.md](field-onboarding/SKILL.md).

1. Name the prerequisites from the field's own structure; 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 step per turn: motivation, vocabulary, one part of the field at a time, 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.
11. Take the field's structure from a textbook, review or syllabus; don't invent it.
12. Name what was left out, and what each skipped part is for.

## 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 looks up the field's structure, takes the
three upstream frameworks it assumes, 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.** Physical picture first
by default; say "balanced" or "derivation first" to switch. The default treats
you as a capable researcher entering a new field: jargon is unpacked, while
mechanisms, assumptions, and equations stay. The openin
````
