/nav-onboard

name: nav-onboard
description: Interactive onboarding for Navigator - learn by doing. Auto-invoke when user says "onboard me", "teach me Navigator", "how do I use Navigator", "Navigator tutorial", "learn Navigator", "new to Navigator", or "what skills should I use".
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
version: 1.1.0

Navigator Onboarding Skill

Interactive, hands-on learning experience for Navigator. Users complete actual tasks to learn workflows, not just read documentation.

When to Invoke

Invoke this skill when the user:

• Says "onboard me", "teach me Navigator"
• Says "how do I use Navigator", "Navigator tutorial"
• Says "learn Navigator", "new to Navigator"
• Asks "what skills should I use"
• Says "help me get started with Navigator"
• First time using Navigator after init

**DO NOT invoke** if:

• User is asking about a specific skill (invoke that skill instead)
• User already completed onboarding (`.completed` exists in their personal onboarding

dir — see Step 1; state is per person, never in the repo, since v7.8.0 / GH-31)

• User explicitly asks to skip onboarding

Two Learning Flows

Quick Start (~15 min)

For users who want to be productive fast:

• 4 essential skills with hands-on practice
• Generates personalized workflow guide
• Minimal philosophy, maximum doing

Full Education (~45 min)

For users who want comprehensive understanding:

• Philosophy primer (context efficiency principles)
• All 5 essential skills with practice
• Project-specific development skills
• Complete workflow mastery

Execution Steps

Step 1: Resolve the Personal Onboarding Dir and Check Previous Onboarding

Onboarding state (progress, workflow guide, completion marker) is **per person and per repo**, stored under `~/.config/navigator/onboarding/<repo-id>/` (or `$NAVIGATOR_ONBOARDING_HOME/<repo-id>/`), never inside the repository. Two contributors on the same repo each get their own run; nothing lands in tracked paths (GH-31).

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
NAV_ONBOARD_DIR=$(python3 "$PLUGIN_DIR/skills/nav-onboard/functions/onboarding_paths.py" .)
if [ -f "$NAV_ONBOARD_DIR/.completed" ]; then
  echo "COMPLETED"
else
  echo "NOT_COMPLETED"
fi

**If completed**: Ask if user wants to re-do onboarding or just view their workflow guide (`$NAV_ONBOARD_DIR/MY-WORKFLOW.md`).

**If the project has its own setup skill** (e.g. `.claude/skills/onboard/` or a `SKILL.md` whose name contains "onboard"/"setup"), mention it and suggest running it first; Navigator onboarding teaches the workflow, not the project.

**Legacy state**: a pre-v7.8.0 `.agent/onboarding/` in the repo is ignored (nav-init gitignores it now). Do not read `.completed` from there.

**If the project ships its own tutorial text** (`.agent/ONBOARDING.md`, reported by the recommender as `project_tutorial`), present it after the Navigator curriculum (Step 6.6). That is how a team repo extends the tutorial instead of replacing it.

Practice Mode (GH-35)

Every exercise in Steps 6.1–6.4 is a rehearsal. When the user types an exercise command ("Create checkpoint learning-test", "Create task doc for learning-feature", "Create SOP for debugging test-failures", "Clear context and preserve markers"), do **not** invoke the real skill. Run the practice sandbox instead:

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
python3 "$PLUGIN_DIR/skills/nav-onboard/functions/practice.py" run [skill_name]

It renders the artifact the real skill would create under `$NAV_ONBOARD_DIR/practice/.agent/` (mirrors the repo's `.agent/`, outside the repo), prints a `preview` and the `real_command`, and never runs `gh`. With `task_id_source: github` the nav-task result carries `would_create_issue` (title, labels, body): show it, say that practice does not create it. `git status` in the repo stays unchanged throughout onboarding; `practice.py clean` removes the sandbox at the end (Step 8). The real skills run as usual once onboarding is over.

Step 2: Analyze Project

Run project analyzer to detect tech stack:

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
python3 "$PLUGIN_DIR/skills/nav-onboard/functions/project_analyzer.py"

**Output structure**:

{
  "project_name": "my-app",
  "project_type": "fullstack",
  "frontend_framework": "Next.js",
  "backend_framework": "Express",
  "database": "PostgreSQL",
  "testing_framework": "Jest",
  "has_navigator": true
}

Step 3: Generate Skill Recommendations

Run the skill recommender. With no arguments it analyzes the current directory itself (no stdin needed); `--analysis FILE` or `project_analyzer.py | skill_recommender.py --analysis -` reuses the Step 2 output:

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
python3 "$PLUGIN_DIR/skills/nav-onboard/functions/skill_recommender.py"

**Output structure**:

{
  "essential_skills": ["nav-start", "nav-marker", "nav-task", "nav-sop", "nav-compact"],
  "recommended_skills": ["frontend-component", "backend-endpoint"],
  "optional_skills": ["visual-regression", "product-design"],
  "workflow_order": ["nav-start", "nav-task", "frontend-component", "nav-sop", "nav-marker", "nav-compact"],