--- name: github-onboarding description: > Walk a brand-new developer through a complete GitHub setup on macOS — from installing the GitHub CLI, authenticating their account, setting up SSH keys for both commits and authentication, and configuring Git with their identity. Use this skill whenever someone needs to set up GitHub on a Mac for the first time, asks how to get started with GitHub, wants to configure SSH keys for GitHub, needs help with GitHub CLI authentication, or says anything like "I just created a GitHub account, now what?" or "how do I push code to GitHub?" or just "help me set up GitHub". This is a beginner-friendly, hand-holding walkthrough — not a reference doc. Trigger even if the user only mentions part of the setup (e.g., just SSH keys) because the skill will detect what's already done and skip ahead. --- # GitHub New User Onboarding (macOS) You are walking a beginner through their first-ever GitHub setup on a Mac. They may not know what SSH, CLI, or "authentication" means in practice. Be patient, explain what each step does in plain language before doing it, and confirm with the user before taking any action that changes their system. **Golden rule:** Never silently skip a step. If something is already set up, tell the user it's done and what it means, then move on. They're learning — every step is a teaching moment. ## Before you begin Tell the user something like: > "I'm going to walk you through setting up GitHub on your Mac, step by step. This > includes installing some tools, logging into your GitHub account, and setting up a > secure connection so you can push and pull code. I'll explain everything as we go — > just follow along and let me know if anything is confusing." ## Step 1: Check for Homebrew Homebrew is the package manager that lets us install developer tools on macOS. Check whether it's installed: ```bash which brew ``` **If Homebrew is installed:** Tell the user it's already there and briefly explain what it does ("Homebrew is like an app store for developer tools — it lets us install things from the command line"). Move to Step 2. **If Homebrew is NOT installed:** Stop here. Explain clearly: > "Before we can continue, you need to install Homebrew — it's a tool that lets us install > developer software on your Mac. You can install it by visiting https://brew.sh and > following the instructions there. Once that's done, come back and we'll pick up where we > left off." Do not attempt to install Homebrew yourself. The installation requires user interaction (password prompts, shell config changes) that's best done by the user directly. Exit the skill here. ## Step 2: Check for GitHub CLI The GitHub CLI (`gh`) lets you interact with GitHub from your terminal — logging in, creating repos, opening pull requests, and more. ```bash which gh ``` **If `gh` is installed:** Tell the user and move to Step 3. **If `gh` is NOT installed:** Explain what you're about to do, then install it: > "I'm going to install the GitHub CLI — it's a tool that lets you work with GitHub right > from your terminal instead of having to use the website for everything." ```bash brew install gh ``` Confirm the install succeeded with `gh --version`, then move on. ## Step 3: GitHub CLI authentication Authentication needs to happen early because it unlocks everything else — once logged in, we can detect the user's name, email, username, and organizations automatically, so they don't have to know or type any of that themselves. Check whether the user is already logged in: ```bash gh auth status ``` ### If already authenticated Tell the user they're already logged in. Show them which account they're connected to (the username will be visible in the `gh auth status` output). Move to Step 4. ### If NOT authenticated This part requires the user to do something in their web browser, so set expectations clearly: > "Now we need to log you into GitHub from the command line. Here's what's going to > happen: > > 1. I'll start the login process, which will give you a short code > 2. Your web browser will open to a GitHub page > 3. You'll paste that code into the page to confirm it's you > > **Before we start:** Make sure you're already logged into GitHub in your web browser > (go to https://github.com and check that you see your profile in the top-right corner). > If you don't have a GitHub account yet, create one there first. > > Let me know when you're ready and I'll start the login." **Wait for the user to confirm they are ready.** Do not proceed until they say so. Once confirmed, run the authentication. Use the web-based flow with SSH as the preferred protocol: ```bash gh auth login --hostname github.com --git-protocol ssh --web ``` This command will print a one-time code and open the browser. Let the user know to watch for it. After it completes, verify with `gh auth status`. ## Step 4: Detect user identity from GitHub Now that the user is authenticated, pull their profile information from GitHub automatically. The user should not have to know or type their username, name, or email — we detect all of it. ```bash gh api user --jq '{login: .login, name: .name, email: .email}' ``` This returns their GitHub username, display name, and public email. Store these values for use in the remaining steps. **Username:** The `.login` field is their GitHub username. Tell the user what it is: "Your GitHub username is **@theirusername** — this is how people will find you on GitHub." **Name:** If `.name` is set, use it. If it's null or empty, ask the user for their full name: "GitHub doesn't have your name on file yet. What name would you like to appear on your code contributions? (e.g., 'Jane Smith')" **Email:** If `.email` is set, use it. If it's null or empty (common — GitHub defaults to private email), try to get their GitHub-provided noreply email: ```bash gh api user --jq '.id' ``` Then construct the noreply address: `{id}+{username}@users.noreply.github.com` Present the email situation to the user: > "GitHub keeps your email private by default, which is a good thing. I can set up your > account using your private GitHub email address ({noreply address}) — this keeps your > real email hidden from the public while still linking your work to your account. > > Or, if you'd prefer to use your personal email address so people can see it on your > contributions, you can tell me that email instead. > > Which would you prefer?" Wait for their response. Use whichever email they choose. ### Configure Git identity Once you have the name and email (either detected or provided by the user): ```bash git config --global user.name "Their Full Name" git config --global user.email "their.email@example.com" ``` Confirm the values are set: ```bash git config --global user.name git config --global user.email ``` Tell the user: "Now every commit you make will be tagged with your name and email, so people can see who made each change." ### Check organizations ```bash gh api user/orgs --jq '.[].login' ``` If they belong to organizations, list them and ask: "You're a member of these organizations: **OrgA**, **OrgB**. Are these the ones you expected, or were you looking for a different one?" If they have no organizations, that's fine — let them know that's normal for a new account and they can join organizations later when invited. ## Step 5: SSH key setup SSH keys are how your computer proves its identity to GitHub without you typing a password every time. You need to check whether a suitable key already exists and whether it's registered with GitHub. ### Check for existing keys ```bash ls -la ~/.ssh/id_ed25519.pub 2>/dev/null ``` **If the key exists**, read the public key and check if it's already on the user's GitHub account: ```bash cat ~/.ssh/id_ed25519.pub ``` ```bash gh ssh-key list ``` Compare the key fingerprints. If the key is already on GitHub with both `authentication` and `signing` usage, tell the user and skip ahead to Step 6. If the key exists locally but is NOT on GitHub, skip to the "Add key to GitHub" section below. ### Generate a new SSH key If no Ed25519 key exists, explain what you're doing: > "I'm going to create an SSH key — think of it as a digital ID card that lets your > computer talk to GitHub securely. It's a pair of files: a private key (like a password, > stays on your machine and should never be shared) and a public key (like a username, > which we'll give to GitHub)." Generate the key using the email from Step 4: ```bash ssh-keygen -t ed25519 -C "their.email@example.com" -f ~/.ssh/id_ed25519 -N "" ``` The `-N ""` sets an empty passphrase for simplicity. For a brand-new user, the friction of a passphrase on every git operation is a bigger risk than the security benefit. Confirm the key was created: ```bash ls -la ~/.ssh/id_ed25519 ~/.ssh/id_ed25519.pub ``` ### Configure SSH Ensure the SSH config file exists and has the right settings for GitHub: ```bash cat ~/.ssh/config 2>/dev/null ``` If there is no `Host github.com` block, add one. If the file doesn't exist at all, create it. The block should look like this: ``` Host github.com AddKeysToAgent yes UseKeychain yes IdentityFile ~/.ssh/id_ed25519 ``` Make sure the config file has the right permissions: ```bash chmod 600 ~/.ssh/config ``` Start the SSH agent and add the key: ```bash eval "$(ssh-agent -s)" ssh-add --apple-use-keychain ~/.ssh/id_ed25519 ``` Explain to the user: "This stores your key in macOS Keychain so you won't have to deal with it again — your Mac will handle it automatically." ### Add key to GitHub Upload the public key to their GitHub account for **both** authentication and signing: ```bash gh ssh-key add ~/.ssh/id_ed25519.pub --title "Mac (authentication)" --type authentication ``` ```bash gh ssh-key add ~/.ssh/id_ed25519.pub --title "Mac (signing)" --type signing ``` Explain: "I've added your key to GitHub twice — once so your computer can connect to GitHub (authentication), and once so GitHub can verify that your commits actually came from you (signing). It's the same key doing both jobs." ### Configure Git to sign commits with SSH ```bash git config --global gpg.format ssh git config --global user.signingkey ~/.ssh/id_ed25519.pub git config --global commit.gpgsign true git config --global tag.gpgsign true ``` Explain: "From now on, every commit and tag you create will be automatically signed with your SSH key. On GitHub, your commits will show a 'Verified' badge — this proves that you actually made the change and nobody tampered with it." ## Step 6: Verify everything works Run a quick connectivity test: ```bash ssh -T git@github.com ``` This should return a message like "Hi username! You've successfully authenticated." (The exit code will be 1 — that's normal, it doesn't mean anything went wrong.) Tell the user what just happened: "Your computer just said hello to GitHub using your SSH key, and GitHub recognized you. Everything is connected." ## Step 7: Wrap up Give the user a summary of everything that was set up, personalized with their actual username and name: > "You're all set, **{name}** (@{username})! Here's what we did: > > - **GitHub CLI** — installed and logged in as @{username} > - **Git identity** — configured with your name and email > - **SSH key** — created and added to your GitHub account for secure connections > - **Commit signing** — turned on, so your commits show as 'Verified' on GitHub > > You're ready to clone repos, make changes, and push code. If you want to try it out, > I can help you create your first repository." ## Important notes - **Never skip the user confirmation** before starting `gh auth login`. The user needs to have their browser ready. - **If any step fails**, explain the error in plain language, suggest what might have gone wrong, and offer to try again or help troubleshoot. Don't dump raw error output without context. - **Detect, don't ask.** The user is new — they probably don't know their GitHub username or what email they used. After authentication, pull everything possible from the GitHub API and confirm it with the user rather than asking them to recall it. - **Existing SSH keys**: If the user already has keys but they're RSA or another type, still create a new Ed25519 key. Don't modify or replace their existing keys — the SSH config can handle multiple keys. Mention that you're adding a new key alongside their existing one. - **Permissions**: If you see permissions errors on `~/.ssh/`, fix them: ```bash chmod 700 ~/.ssh chmod 600 ~/.ssh/id_ed25519 chmod 644 ~/.ssh/id_ed25519.pub ``` - **Multiple GitHub accounts**: This skill sets up a single account. If the user mentions needing multiple accounts, note that it's possible but requires a more advanced setup and suggest they come back to that later.