navigating-github

Navigating GitHub

First-time GitHub setup and interactive git learning. Get set up, then learn by doing.

Table of Contents

1. Overview — 2. Prerequisites — 3. Instructions — 4. Modes — 5. Examples — 6. Output — 7. Resources

Overview

Problem: Getting started with GitHub is the #1 barrier for people building with AI. Beginners stall at setup, don't understand commits vs pushes vs PRs, and have nobody to walk them through it hands-on. AI coding tools can run git commands, but they don't teach you what those commands mean or guide you through setup from scratch.

Solution: Walk users through GitHub setup step by step, then teach git and GitHub through 9 progressive hands-on lessons on their actual project. Every lesson uses do-then-explain: run the command, see the result, then understand why. Adapts language and depth to skill level automatically.

Prerequisites

• Terminal access with git installed
• gh CLI installed (Setup handles installation if missing)
• GitHub account (Setup handles creation if missing)

Instructions

Step 1 — Route

Determine mode from the user's request. Act immediately — no preamble.

1. No .git/ directory OR gh auth status fails → Setup (check with test -d .git and gh auth status)
2. Keywords "teach", "learn", "what are", "how do", "explain", "lesson" → Learn
3. Keywords "set up", "new repo", "init", "get started" → Setup
4. Generic ("help me with github") → check environment, route to Setup if no repo, otherwise offer lesson menu

Step 2 — Infer Skill Level

Each mode runs git status as part of its normal operation. Infer level from those signals — no extra commands:

• Only main branch + short/vague commit messages → Beginner
• A few branches + descriptive commits → Intermediate
• Branch naming conventions + conventional commits → Advanced
• Complex history, multiple remotes, CI configured → Expert

Only ask via AskUserQuestion when signals are genuinely ambiguous. Read ${CLAUDE_SKILL_DIR}/references/skill-assessment-guide.md for the full adaptive behavior matrix. Apply:

Level	Language	Depth	Autonomy
Beginner	Analogies, zero jargon	Explain everything	Execute and teach along the way
Intermediate	Light jargon, define terms	Explain the why	Execute, ask to confirm
Advanced	Standard vocabulary	Brief rationale only	Suggest, let user decide
Expert	Terse, technical	None unless asked	Assist only

Modes

Setup — Guided Onboarding

The core experience for first-time users. Walk through each step interactively, skipping anything already done. Run each check, explain what it means, fix what's missing.

Sequence: Check gh auth status → install gh if missing (detect OS, give command) → run gh auth login (walk through browser OAuth) → check git config user.name and user.email (set if missing) → check for .git/ (run git init if missing) → generate .gitignore by detected project type → create first commit → run gh repo create (let user choose public/private) → push → show the repo URL.

Skip completed steps. Explain each step at the inferred level. After completion, offer the lesson menu: "Repo is set up. Say 'teach me github' or run /github-learn to start learning."

Learn — Interactive Curriculum

Hands-on lessons using real commands on the user's actual project. Every lesson follows do-then-explain: run a real command, observe the result, THEN explain what happened. Verify understanding after each step before proceeding.

Read ${CLAUDE_SKILL_DIR}/references/learning-curriculum.md for the full curriculum. Route by trigger:

Beginner track:

• "teach me github" / "learn github" → GitHub 101 — commits, push, the basics
• "what are branches" / "teach me branches" → Branching Basics — create, switch, see the difference
• "teach me PRs" → Your First PR — branch, push, create PR, merge

Intermediate track:

• "teach me branching strategies" → Branch Workflows — naming, feature branches, staying current
• "teach me code review" → PR Review Flow — review, comment, approve
• "how do I collaborate" → Team Git — forks, upstream sync, co-authoring

Advanced track:

• "teach me rebase" → Rebase vs Merge — interactive rebase, squash, clean history
• "teach me CI/CD" / "github actions" → GitHub Actions — write a workflow, watch it run
• "how do code review apps work" → Review Ecosystem — CodeRabbit, Copilot Review, and the ecosystem (read ${CLAUDE_SKILL_DIR}/references/github-review-apps.md)

After each lesson: summarize what was learned (2-3 bullets), give a small challenge to try solo, suggest the next lesson.

Teaching rules:

• Run commands one at a time, explain after each result
• If the user makes a mistake, fix it together — mistakes are learning moments
• If the user already knows something, skip ahead
• If the user seems confused, slow down and simplify
• Create a safe practice branch before exercises that modify the repo
• Never push to main/master during lessons — always branch first
• Never commit secrets — check for .env, API keys before staging

Examples

Setup (no .git, no auth):

User: "help me with github"
Agent: [checks — no .git, gh not authenticated]
Agent: "Starting from scratch. First, connect to GitHub..."
Agent: [walks through gh auth login, git config, git init, gh repo create]
Agent: "Repo is live at github.com/user/project. Run /github-learn to
       start learning commits and branches."

Learn (beginner, GitHub 101):

User: "teach me github"
Agent: "Make a small change to any file — add a comment, fix a typo."
User: [edits a file]
Agent: "Now save that change: git add README.md"
Agent: "That moved the change to the staging area — like putting a letter
       in an envelope. Now seal it: git commit -m 'Update README'"
Agent: [verifies understanding before moving to next step]

Learn (advanced, rebase):

User: "/github-learn rebase"
Agent: "Create a branch with 3 small commits, then we'll squash them."
Agent: [guides through git rebase -i, explains pick/squash/fixup]

Output

Calibrate all output to the inferred skill level. Beginner: plain English with analogies, explain every command. Intermediate: concise summaries, explain rationale. Advanced: minimal commentary. Expert: raw output only. Read ${CLAUDE_SKILL_DIR}/references/git-concepts-glossary.md when a term definition is needed.

Resources

• ${CLAUDE_SKILL_DIR}/references/learning-curriculum.md — 9 progressive lesson plans from beginner through advanced
• ${CLAUDE_SKILL_DIR}/references/git-concepts-glossary.md — term definitions at beginner and technical levels
• ${CLAUDE_SKILL_DIR}/references/skill-assessment-guide.md — adaptive behavior matrix with level-up and level-down signals
• ${CLAUDE_SKILL_DIR}/references/safety-rules.md — branch protection, secret detection, destructive operation guards
• ${CLAUDE_SKILL_DIR}/references/error-recovery-playbook.md — conflict resolution, auth repair, detached HEAD, rebase recovery
• ${CLAUDE_SKILL_DIR}/references/github-review-apps.md — CodeRabbit, Copilot Review, Greptile, CodeQL, Qodo
• ${CLAUDE_SKILL_DIR}/references/claude-github-platforms.md — platform capabilities across Claude Code, Cursor, Windsurf, and others