Onboard Skill

Start with a quick recommendation based on recent sessions, then optionally continue to guided learning — so users experience value first, learn second.

Invoke directly with /onboard when the user wants onboarding or protocol discovery.

When to Use

Invoke this skill when:

• A new user wants to discover which epistemic protocols fit their workflow
• A user wants to experience protocols through guided practice
• Re-onboarding after new protocols are added or workflow changes

Skip when:

• User already knows which protocol to use (direct invocation)
• Quick single-protocol question (answer directly)

Workflow Overview

Quick Proof:    ENTRY → QUICKSCAN → PICK → EVIDENCE → TRIAL → INSIGHT → NEXT
Targeted:       ENTRY → QUICKSCAN → MAP → SCENARIO → TRIAL → QUIZ → GUIDE
Targeted + std: ENTRY → SCENARIO → TRIAL → QUIZ → GUIDE

Data Sources

Compact mapping for inline use.

Phase Execution

Paths below written {config_dir}/… take {config_dir} = CLAUDE_CONFIG_DIR when set, else ~/.claude. Resolve it ONCE per invocation with Bash printf '%s\n' "${CLAUDE_CONFIG_DIR-$HOME/.claude}" and substitute the absolute result before any Read/Glob/Grep call.

Phase 0: Entry (Path Selection)

Begin with a concise welcome and path selection, reserving the full catalog for the Browse-all path.

Gate #1:

• Text: Path selection prompt
• Options:
  • Quick recommendation (Recommended)
  • Learn a specific protocol
  • Browse all protocols

If Quick recommendation: set path = quick, proceed to Phase 1.

If Browse all: Present the protocol catalog (check installation status via Glob {config_dir}/plugins/cache/epistemic-protocols/*/, then render all core protocols from Data Sources as a numbered list with name + "When to Use" + installation badge). After catalog, present:

• Text: Post-catalog path selection
• Options:
  • Quick recommendation
  • Learn a specific protocol (type name in Other)

Then proceed based on selection.

If Targeted + Other contains protocol name: proceed directly to session source question.

If Targeted + no protocol specified:

Present a condensed catalog as text output: render the Data Sources table as a numbered list, each protocol as /command — When to Use description.

Then Gate #2:

• Text: Protocol selection (type name or number in Other)
• Options: one per Onboarding Pool protocol (/elicit, /inquire), each as /command — When to Use; any other protocol is chosen by name or number in Other

Gate #3 (Targeted only, session source):

• Text: Session source selection
• Options:
  • Personalize with my recent sessions
  • Use standard examples (no session needed)

State after Phase 0:

• path: quick | targeted
• target_protocol: (targeted only) selected protocol name
• session_source: (targeted only) scan | standard — Quick path always runs Quick Scan

Skip rule: If targeted + standard → skip Phases 1-2, jump to Phase 3 with preset scenarios from references/scenarios.md.

Phase 1: Quick Scan (User Context Profile) — Inline

Build a User Context Profile from the person's own opening turns in their recent Claude Code conversations. Runs inline (no subagent delegation). Both Quick and Targeted paths share this phase.

Step 1: Collect recent opening turns

• Records: Glob {config_dir}/projects/*/*.jsonl — a session record sits directly inside a project partition; anything nested deeper is a subordinate capture and is excluded by depth. Exclude partitions whose name contains -worktrees-, which hold delegated work rather than the person's own sessions. Take the ~10 most recently modified records.
• Bounded head read: read only the first 256 KB of each record (a byte-bounded read such as head -c 262144 <record>), never the whole file. Skip a line that does not parse — the last one may be cut by the bound.
• Person turns only: a line is the person's turn when its type is user, isMeta and isCompactSummary are both absent, and its text (message.content as a string, or the text parts of a content list — tool results are not text parts) neither opens with < nor is a bare control marker such as [Request interrupted by user]. Hook output, command wrappers, and injected envelopes arrive in the same user stream and are excluded by this rule.
• From each record keep its first 2-3 person turns. A record whose head holds none contributes nothing.

Step 2: Infer User Context Profile

From the collected turns, infer:

• Work domains: What areas the user works in (e.g., API development, infrastructure, data pipeline)
• Conversation patterns: Request clarity level, incremental vs. batch requests, question types (how/why/what)
• Task types: Ratio of feature development, debugging, refactoring, documentation

If no person turns were collected — a fresh install, or a host that keeps no such records: Quick path proceeds to Pick with fallback (/elicit); Targeted path falls back to Onboarding Pool (/elicit, /inquire).

Output for Phase 2: User Context Profile (work domains, conversation patterns, task types). Quick Scan infers user context for protocol matching and scenario personalization.

Phase 2a: Pick (Quick Path — Recommendation)

Quick path only. Recommend from the auto-recommend pool.

Onboarding Pool: /elicit (Euporia), /inquire (Aitesis). These two are chosen because users can quickly experience their value. Protocols like /grasp are user-initiated by nature and should not be proactively suggested in the first encounter.

Recommendation rules (applied to Quick Scan Profile):

Decision logic:

1. Score each protocol by signal match count across the collected person turns
2. Ideation route-away: ideation asks ("ideas for", "brainstorm") score no pool protocol — when they are the only matched signals, relay in one sentence that the ask itself maps to /ideate (user-initiated: named as the route for that ask, not presented as the onboarding recommendation), then continue via the Fallback rule; the Phase 2b evidence card follows its fallback form, since the recommendation rests on the default, not on a matched signal
3. Recommend every matched protocol, the strongest match first
4. Tie-break: /elicit > /inquire
5. Fallback: If no signals detected (no records, or too few person turns) — or every detected signal was routed away — recommend /elicit

Output: Present each recommendation as a single sentence stating how that protocol would help right now.

Phase 2b: Evidence (Quick Path — Evidence Card)

Quick path only. Present an evidence card for each recommendation, explaining why it was made.

Evidence generation (per protocol, referencing Data Sources table):

• Line 1: Cite the specific signal pattern from Quick Scan Profile that matched this protocol's "Key Patterns" column in Data Sources
• Line 2: State the expected benefit, derived from the protocol's "When to Use" column in Data Sources

Fallback (no session data, or no matched signal): State that no pattern matched this protocol, then cite the protocol's core value proposition from Data Sources "When to Use."

Rules:

• Evidence is maximum 2 lines — a focused cue.
• Do not show confidence scores or numbers.
• Do not quote session content verbatim.

After presenting evidence, present:

• Text: Trial invitation
• Options:
  • Try /X now (one option per recommendation, naming its protocol)
  • Learn more about a recommendation
  • See a different recommendation (only while the pool holds one not yet shown)
  • Go to full learning path

Branch: Try /X now → Phase 4 (quick trial) with that protocol, Learn more about a recommendation → show the Data Sources row for each recommendation on screen then re-ask, See a different recommendation → pick next from pool and present it alone from Phase 2a's Output, Go to full learning path → set path = targeted and go to Phase 0 targeted flow.

Phase 2: Map (Targeted Path — Protocol Matching)

Targeted path only. Apply User Context Profile to match protocols to the user's context.

1. Match Profile against the compact mapping table (Data Sources section). Select 2-3 protocols most relevant to the user's work domains and conversation patterns, defaulting to Onboarding Pool (/elicit, /inquire).
2. Targeted sub-path: Filter to target protocol, use Profile for scenario personalization. Note related protocols from the compact mapping table.
3. Fallback: If Profile quality is insufficient (no records, or too few person turns) → use Onboarding Pool (/elicit, /inquire). Proceed immediately without blocking the onboarding flow.

Phase 3: Scenario (Targeted Path — Intervention Point)

Targeted path only. Present a concrete scenario showing where the protocol would have helped.

Scenario construction (2-tier fallback):

• Tier 1 (User Context Profile available): Generate a hypothetical scenario grounded in the user's work context (domains, task types, conversation patterns from Quick Scan). Personalize standard scenarios from references/scenarios.md using Profile data.
• Tier 2 (no data / Onboarding Pool fallback): Use preset scenarios directly from references/scenarios.md.

Present scenarios for each of the top 2-3 protocols sequentially.

Scenario format:

Scenario: /X (Protocol Name)

[Situation]: [Concrete situation grounded in user's work context — or preset from scenarios.md]

[Intervention]: If you had called /X at this point:
- [what the protocol would have done — step 1]
- [step 2]
Expected outcome: [e.g., reduced rework, clearer direction]

Clarity rule: Scenarios must present clear-cut protocol fits where the mapping is unambiguous. If a situation could plausibly map to multiple protocols (e.g., "exploration" could be /elicit or /ideate), reserve it for Phase 5 quiz material instead of using it as a scenario. The scenario phase builds confidence through recognition; the quiz phase builds discrimination through ambiguity.

Anti-pattern: Scenarios must be self-contained (situation + intervention) with unambiguous protocol fit. Ambiguous patterns belong in Phase 5 quiz.

Present each scenario as regular text output (Tier 1/2 format above). Then present for navigation only:

Gate (per scenario):

• Text: Scenario navigation
• Options:
  • Try it — practice this protocol
  • Show another example
  • Skip to quiz

Phase 4: Trial (Protocol Execution)

Guide the user through a real, abbreviated protocol experience.

Quick Path Trial

Mini practice prompt: Present a single realistic request (one sentence) that naturally triggers the selected protocol's deficit. When User Context Profile is available, adapt the domain to match the user's work context. Source from references/scenarios.md Trial prompt field, or generate from Data Sources context. Follow with gate interaction:

• Text: Trial scenario confirmation (user can also define their own)
• Options:
  • Start with this scenario — call /X
  • Start with my own scenario (type in Other)

Execution: The user invokes the actual protocol (e.g., type /elicit). The protocol runs in the same session with the mini prompt as context. Trial ends when the invoked protocol reaches its natural termination or the user ends it. After the trial ends, proceed to Quick Post-Trial below.

Quick Post-Trial Insight (2 lines max):

Generate from the protocol just experienced:

• Line 1: Name the epistemic operation performed (source: protocol's deficit → resolution type, or references/scenarios.md Philosophy field)
• Line 2: Connect to a concrete workflow benefit

Quick Post-Trial Navigation:

Present via gate interaction:

• Text: Post-trial navigation
• Options:
  • That's enough for today
  • Try a different protocol
  • Continue to full onboarding

Branch: That's enough for today → end session with brief closing, Try a different protocol → check pool exhaustion: if protocols not yet tried remain in Onboarding Pool, pick the next untried one and present it alone from Phase 2a's Output; if pool exhausted (every pool protocol tried in session), present You've experienced all core recommendations and offer Targeted transition, Continue to full onboarding → set path = targeted and go to Phase 2 MAP with Quick Scan results.

Targeted Path Trial

"Try it" selection from Phase 3 already signals intent — enter trial directly without additional confirmation.

Mini practice prompts (scoped for 2-3 exchanges): Use the Trial prompt field from references/scenarios.md for the target protocol. Present the trial guidance as regular text output.

Execution: Prompt the user to invoke the actual protocol (e.g., type /inquire). The protocol runs in the same session with the mini prompt as context. Trial ends when the invoked protocol reaches its natural termination or the user ends it. After the trial ends, present Post-Trial Insight and LOOP.

Offer trial for the top-recommended protocol first. When that trial ends, optionally offer trial for the second recommendation.

Post-Trial Insight (presented after the trial ends):

After each trial, present a brief insight card sourced from the Philosophy field in references/scenarios.md. Structure:

Protocol Insight: /X (Greek name)

[Core principle — one sentence]
[Workflow position — where this protocol sits and why]
[Game feel — the experiential pattern you just went through]

Post-Trial LOOP:

After the Post-Trial Insight, present:

• Text: Post-trial navigation
• Options:
  • Quiz — test my understanding
  • Another scenario — see more examples
  • Try a different protocol
  • Guide — see my learning summary

Branch: Quiz → Phase 5, Another scenario → Phase 3, Different protocol → Phase 3 with next MAP protocol or Phase 0 with cached MAP, Guide → Phase 6.

Phase 5: Quiz (Socratic Verification)

Test protocol recognition through situation-based questions. Question format differs by path.

Question sourcing (in priority order):

1. Ambiguous scenarios from Phase 3 filtering — situations that were too ambiguous for scenarios are ideal quiz material (e.g., "exploration" that could be /elicit or /ideate)
2. Protocols from TRIAL + MAP results (personalized)
3. Profile-personalized variants of preset scenarios (if User Context Profile available)
4. Preset scenarios from references/scenarios.md

Targeted Path

Type 1 — Binary recognition (2-3 questions):

Present via gate interaction for each:

• Text: Present a situation (2-3 sentences), ask "Is this a /X situation?"
• Options: "Yes" / "No"
• Mix: 1-2 true positives + 1 true negative (situation that fits a neighbor protocol)
• On "No" answer for a true negative: briefly introduce the correct protocol as a natural distinction point

Type 2 — Reverse recognition (1 question):

Present via gate interaction:

• Text: Present 3 short scenarios numbered 1-3, ask "Which of these are /X situations?"
• Options: "1 and 2" / "2 and 3" / "1 and 3" / "All three"

Type 3 — Design thinking (1 question):

Present via gate interaction:

• Text: Present a situation, ask "How would you formulate your request to AI to avoid this problem?"
• Options: "Show me a hint" / "Show me a model answer"
• The user's primary input channel is Other (free text). Evaluate based on whether the response demonstrates protocol awareness.

Multi-Protocol Path

Applies when the targeted flow was entered from the Quick path ("Continue to full onboarding", or the pool-exhausted transition) without a single target protocol, so MAP selected 2-3 protocols.

Type 1 — Situation recognition (3-4 questions):

Present via gate interaction for each:

• Text: Present a situation (2-3 sentences), ask "Which protocol fits?"
• Options: 4 protocol choices (correct answer + 3 plausible distractors)

Type 2 — Design thinking (1 question):

Same format as Targeted Path Type 3.

Feedback (both paths)

Immediate feedback after each question:

• Correct: Reinforce with the core principle + why the distinction matters. "Correct — /inquire collects what the AI can reach on its own and hands back what remains as the user's own unknown (what can I reach, and what is yours?), while /apportion cuts an autonomous goal into coarse units at cited seams, closes each unit before the run begins, and hands the plan the user takes to the run. /inquire exhausts the context the AI can reach and names what only the user holds (context sufficiency), /apportion gives the run a closed unit each — a checkable finish line where one compiles, a recorded acceptance or a recorded reservation where none does (execution structure)."

• Incorrect (reasoning inquiry → targeted correction):

  1. Reasoning inquiry: Present via gate interaction 2-3 reasoning hypotheses inferred from the user's wrong answer (context-specific, not templates). Do not reveal the correct answer. "Other" always available.
  2. Targeted correction: Using the user's stated reasoning, explain the distinction through the design axis that separates the confused pair. Directly address the reasoning — e.g., "You mentioned timing — that's the right axis. The key difference is the object: /inquire works before a result exists, on what the AI lacks — collecting what it can reach and handing back the user's unknowns — while /contextualize works after, on whether the result fits its context."
  3. Resume: Proceed to next question.

  Reasoning inquiry cap: Apply reasoning inquiry for the first 2 incorrect answers per quiz session. Subsequent incorrect answers receive direct targeted correction (step 2 only) without the reasoning inquiry step.

Distinction depth: Quiz feedback should go beyond "A, not B" to explain the design dimension that separates confused pairs. Reference the distractor pairs from Quiz Design section. The goal is that even wrong answers teach — the user leaves understanding why two protocols that sound similar serve different purposes.

Phase 6: Guide (Summary + Next Steps)

Summarize the learning experience, connect it to the rest of the protocol catalog, and provide actionable next steps.

1. Learning summary:

   • Protocols experienced (trial) and tested (quiz)
   • Quiz accuracy + key distinctions learned
   • Personalized strength: "You naturally recognize [pattern] — /X formalizes this"

2. Epistemic Map (connect the dots):

   Present the Data Sources catalog, each protocol as /command — When to Use, highlighting the protocols the user experienced with emphasis (e.g., bold or ★). State that the protocols are not a fixed sequence or grouping: each is reached for when its deficit is the one in play, and they combine as the situation calls for.

3. Next protocol suggestion: Based on quiz results and MAP data, suggest the next protocol to explore — preferring one whose deficit, in the user's own sessions, arises next to the one just practised.

4. Advanced Usage (bonus tips after main guide):

   Present 3-5 tips from references/advanced-usage.md (multi-protocol sessions, invocation techniques, etc.), prioritizing tips related to protocols from TRIAL and QUIZ.

5. Continue exploring (when MAP results contain unexplored protocols):

   Present via gate interaction:

   • Text: "Want to experience another protocol?"
   • Options: "Yes — show me another" / "Done — I have enough"

   If "Yes" → return to Phase 3, using the next recommended protocol from MAP results.

Quiz Design

Difficulty progression: Start with high-contrast pairs (e.g., /elicit vs /apportion), progress to subtle distinctions (e.g., /elicit vs /inquire, /inquire vs /contextualize).

Distractor selection: Choose protocols that share surface similarity with the correct answer:

• /elicit ↔ /inquire: both about "unclear starting point" but different layers — Aitesis collects the facts the AI can reach and hands back what only the user holds (information layer), Euporia surfaces the decisions the user's intent turns on (coordinate-explication layer)
• /inquire ↔ /apportion: both run right before the AI acts, but /inquire collects the context the action rests on as far as the AI can reach and names the rest as the user's unknown, /apportion cuts an autonomous goal into coarse units and closes each one — on a compiled completion predicate, on an acceptance you recorded when none compiles, or on a reservation where a judgment rather than a check settles it — and hands the plan the user takes to the autonomous run
• /inquire ↔ /contextualize: both about "context" but different timing (pre vs. post execution)
• /bound ↔ /inquire: both pre-execution and AI-directed, but different targets (ownership boundaries vs. missing context)

Path-specific question counts:

• Targeted: 2-3 binary + 1 reverse + 1 design = 4-5 questions
• Multi-protocol: 3-4 situation + 1 design = 4-5 questions

Gate Interaction Budget

Quick path targets 3-4 calls. Targeted path targets 6-12 calls.

Rules

1. Value before learning: Quick path proves value in under 3 minutes. Learning (scenarios, quizzes) is available but not the default entry.
2. Onboarding Pool: /elicit, /inquire are the unified recommendation set for both Quick path auto-recommend and Targeted path fallback. User-initiated protocols (/grasp, /apportion) and specialized protocols (/contextualize) are excluded. When pool is exhausted in Quick path, transition to Targeted path.
3. Experience over analysis: This skill teaches through doing; its output is the trial and the terminal summary.
4. Privacy: Never transmit session data externally. All analysis runs locally.
5. No subagent delegation: Both Quick and Targeted paths use inline Quick Scan.
6. Trial authenticity: Trial phase must execute the actual protocol, not simulate it. The user invokes the real slash command.
7. Immediate feedback: Quiz answers get instant feedback. For incorrect answers, reasoning inquiry precedes correction (per Feedback section). Never batch quiz results.
8. No auto-install: Guide installation but never install plugins automatically.
9. Session record access: Read a conversation record only through a byte-bounded head read, never the whole file, and keep only the person's turns as Phase 1 defines them. Assistant turns, tool output, and injected text are not read into the profile.
10. Preset as safety net: references/scenarios.md ensures every user gets a complete experience regardless of session history availability.
11. Single session: The entire onboarding completes in one session. No cross-session state required.

Acknowledgments

• @zzsza — Quiz-based participatory UX design contribution