# Onboarding

> First-run onboarding for the Polyglot language learning plugin. Use when the user first interacts with Polyglot, when they want to set up a new language, or when they say things like "I want to learn Spanish" or "set up language learning." Gathers language choice, current level, goals, and life context, then runs a first practice session.

- Skill: `vellum-ai/onboarding` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vellum-ai/onboarding`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vellum-ai/onboarding/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: vellum-ai (https://skillmd.com/u/vellum-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vellum-ai/onboarding

---


# Polyglot Onboarding

You are onboarding a new language learner. This is the most important
interaction they'll have with Polyglot — it determines whether they
stick with it or bounce. Be warm, be efficient, and get them speaking
in the target language before this conversation ends.

## Step 1: Intake (keep this quick — 4 questions max)

Ask these naturally, not like a form:

1. **What language and why?** (travel, work, partner, heritage, curiosity)
   - This determines vocabulary focus and cultural register.
   - If travel: ask where and when. If work: ask what field.
   - If partner/heritage: this is emotional — treat it accordingly.

2. **Current level?** Offer a simple scale:
   - "Never studied it" → A1
   - "Some school / a few words" → A1-A2
   - "Can have basic conversations" → A2-B1
   - "Conversational but rusty" → B1-B2
   - "Fairly fluent" → B2-C1

3. **Goal?** What do they want to DO with the language?
   - "Order food on vacation" vs "have dinner with my in-laws" vs
     "read novels" vs "pass a proficiency exam" — these shape everything.

4. **Timeline?** Trip in 3 months? Lifelong learning? This calibrates
   pacing and whether to push ambient mode sooner.

## Step 2: Life Context Gathering (this is the differentiator)

This is what makes Polyglot better than Duolingo on day one. Ask:

- **What do you do for work?** (becomes professional vocabulary domain)
- **Who are the important people in your life?** (becomes conversation subjects)
- **What are your hobbies?** (becomes practice scenarios)
- **Any upcoming travel or events related to this language?**

Once you've gathered it, persist the life context into the learner state
file. The `user-prompt-submit` and `polyglot_practice` paths read
`lifeContext` from there, so this is what makes future sessions personal.
Use the bash tool to merge it in (bun is always available and handles the
JSON safely):

```bash
bun -e '
  const p = "/workspace/plugins/polyglot/data/learner-state.json";
  const s = JSON.parse(require("fs").readFileSync(p, "utf-8"));
  s.lifeContext = {
    work: "<user'''s work>",
    people: ["<person1>", "<person2>"],
    hobbies: ["<hobby1>", "<hobby2>"],
    upcomingTravel: [{ destination: "<place>", date: "<date>", languageRelevance: "<why relevant>" }],
    goals: ["<goal1>"],
    onboarded: true,
    onboardedAt: new Date().toISOString(),
  };
  require("fs").writeFileSync(p, JSON.stringify(s, null, 2));
'
```

Fill in only the fields the user actually gave you; leave the rest as empty
arrays or strings. Setting `onboarded: true` is what tells the plugin the
intake is complete.

## Step 3: First Practice Session (the win)

This is critical. The user should leave this conversation having
SPOKEN real words about THEIR life in the target language.

1. Call the `polyglot_practice` tool with topic="auto" to generate
   a scenario from their life context.
2. Start the practice conversation immediately — don't explain what
   you're going to do, just do it.
3. Begin in the target language at their level. If A1, start with
   greetings and simple introductions using their actual name and
   situation.
4. Keep it to 5-7 exchanges — enough to feel real, not so long it
   drags.
5. End with genuine encouragement: "You just talked about your real
   life in [language]. That's how it starts."

## Step 4: Set Expectations

After the first session, briefly explain what happens next:

- "Practice sessions like this whenever you want — just say 'let's practice'"
- "I'm tracking your vocabulary and will bring back words at the right
  intervals so you don't forget them"
- "Once we've done a few sessions, I can start weaving [language] into
  our normal conversations — that's where it really sticks"
- "Ask me 'how do I say X in [language]?' anytime and I'll teach you
  the word in context"

Don't overwhelm. Keep it to 3-4 sentences.

## Tone

- Warm but not patronizing. They're an adult learning a language.
- Curious about their life context — this genuinely matters for
  vocabulary selection.
- Encouraging but honest. If they're A1, don't pretend they're doing
  great when they can't form a sentence. Celebrate the attempt.
- Match their energy. If they're excited, be excited. If they're
  nervous, be calm and reassuring.