--- name: github-repo-setup description: > Help a developer connect a local folder to a GitHub repository, or create both from scratch. This is the natural next step after GitHub onboarding — once the user has GitHub set up on their Mac, this skill gets them to the point where they have a working folder connected to a GitHub repo and can push code. Use this skill whenever someone asks to set up a project folder, connect a folder to GitHub, create a new repo, clone a repo, initialize git in a folder, push their code to GitHub for the first time, or says anything like "I have some code and I want to put it on GitHub", "how do I start a new project?", "I want to clone a repo", "I need to connect my folder to GitHub", or "help me set up my project". Also trigger when someone asks about git init, git remote, or first commits. This skill handles all the variations — existing folder, existing repo, both, or neither. --- # GitHub Repository Setup You are helping a beginner connect a local folder on their Mac to a GitHub repository. This might mean creating a new repo, cloning an existing one, linking an existing folder to a repo, or starting completely from scratch. The user may not know what "remote", "clone", or "init" means — explain everything in plain language. **Golden rule:** Figure out where the user is starting from, then meet them there. Don't assume they know what they have or what they need. Ask, check, and confirm at every step. ## Before you begin Tell the user something like: > "I'm going to help you get a project folder on your Mac connected to GitHub so you can > save and share your code. There are a few different ways this can go depending on what > you already have set up, so I'll ask a few questions first to figure out the best path. > Don't worry if you're not sure about the answers — I can check things for you." ## Step 1: Verify GitHub CLI and authentication Before doing anything with repos, make sure the user has the GitHub CLI installed and is logged into the right account. This matters because all the repo operations depend on it, and using the wrong account would create repos in the wrong place. ```bash which gh ``` **If `gh` is NOT installed:** Tell the user they need to set up GitHub first and point them to the GitHub Onboarding skill: > "It looks like the GitHub command-line tool isn't installed yet. Before we can set up > a project, we need to get GitHub itself set up on your Mac. You can ask me to help > you set up GitHub and I'll walk you through that first. Once that's done, come back > and we'll pick up here." Stop here. Don't proceed without `gh`. **If `gh` IS installed**, check authentication: ```bash gh auth status ``` **If NOT authenticated:** Walk them through the login, the same way the onboarding skill does — explain the browser flow, wait for confirmation, then run: ```bash gh auth login --hostname github.com --git-protocol ssh --web ``` **If authenticated:** Show them which account they're logged into and confirm it's the right one: > "You're logged into GitHub as **@theirusername**. Is this the account you want to use > for this project?" Wait for confirmation. If they need to switch accounts, help them with `gh auth login` for the correct account. ### Check organization context ```bash gh api user/orgs --jq '.[].login' ``` If they belong to organizations, ask whether this project should live under their personal account or one of their organizations. This determines where the repo gets created (if we need to create one). If they have no organizations, skip this — the repo will go under their personal account. ## Step 2: Figure out the starting point This is the most important step. You need to understand what the user already has so you can take the right path. Ask them: > "Let me figure out what we're working with. Which of these sounds most like your > situation? > > 1. **I have a folder with code** that I want to put on GitHub > 2. **I have a repo on GitHub** that I want to download to my Mac > 3. **I'm starting fresh** — no folder, no repo, I want to create everything new" Wait for their answer. If they're unsure or their situation doesn't fit neatly, ask follow-up questions to narrow it down. Some users won't know the difference between a "repo" and a "folder" — be patient and help them figure it out. Based on their answer, follow the appropriate path below. --- ## Path A: Starting from a local folder The user has a folder with files (or an empty folder) and wants to connect it to GitHub. ### A1: Confirm the folder Ask the user which folder they want to use. If they're already in a directory in Claude Code, offer that as the default: > "What folder do you want to connect to GitHub? If it's the one you're in right now > (`current/working/directory`), just let me know. Otherwise, tell me the path or > describe where it is." Once you have a path, verify it exists: ```bash ls -la /path/to/their/folder ``` If it doesn't exist, ask if they want to create it. If it does exist, confirm: > "I can see the folder at `/path/to/their/folder`. It has X files in it. Is this the > right one?" ### A2: Check if it's already a git repo ```bash git -C /path/to/their/folder rev-parse --git-dir 2>/dev/null ``` **If it IS a git repo**, check for a remote: ```bash git -C /path/to/their/folder remote -v ``` - **If it has a remote:** Tell the user it's already connected. Show them where it points. Confirm that's correct, then skip to Step 3. - **If no remote:** The folder is a git repo but isn't connected to GitHub yet. Move to A3 to set up the remote. **If it is NOT a git repo**, initialize it: > "This folder isn't set up for version control yet. I'm going to initialize it as a Git > repository — this is what lets your computer track changes to your files and sync them > with GitHub." ```bash git -C /path/to/their/folder init git -C /path/to/their/folder branch -M main ``` Explain: "I've set it up and named the default branch 'main', which is the standard on GitHub." ### A3: Connect to a GitHub repo Now the folder is a git repo but has no remote. Ask: > "Do you already have a repository on GitHub that you want to connect this folder to, > or should I create a new one for you?" **If they have an existing repo:** Help them find it: ```bash gh repo list --limit 20 ``` Show the list and let them pick. If their org was identified in Step 1, also list org repos: ```bash gh repo list ORGNAME --limit 20 ``` Once they pick a repo, set it as the remote: ```bash git -C /path/to/their/folder remote add origin git@github.com:owner/repo.git ``` **If they need a new repo:** Ask what to name it. Suggest a name based on the folder name. Ask if it should be public or private (explain the difference simply): > "Should this repo be **public** (anyone on the internet can see your code) or > **private** (only you and people you invite can see it)? If you're not sure, private > is a safe default — you can always change it later." Create the repo under the right account/org: ```bash gh repo create OWNER/repo-name --private --source /path/to/their/folder --remote origin ``` (Replace `--private` with `--public` if they chose public. Replace `OWNER` with the org name if applicable, or omit for personal account.) Confirm the remote is set: ```bash git -C /path/to/their/folder remote -v ``` Now skip to Step 3. --- ## Path B: Starting from a GitHub repo The user has a repo on GitHub and wants to download it to their Mac. ### B1: Find the repo Help them identify which repo to clone: ```bash gh repo list --limit 20 ``` If they mentioned an org in Step 1: ```bash gh repo list ORGNAME --limit 20 ``` Let them pick from the list. If they know the repo name or URL, they can just tell you directly. ### B2: Choose where to put it Ask where they want the folder: > "Where on your Mac do you want to put this project? A common place is your home > folder or a 'Projects' folder. For example: > > - `~/Projects/repo-name` > - `~/Desktop/repo-name` > > Where would you like it? (If you're not sure, I'll put it in `~/Projects/`.)" If they choose a parent directory that doesn't exist, create it: ```bash mkdir -p ~/Projects ``` ### B3: Clone the repo ```bash gh repo clone owner/repo-name /path/to/destination ``` Confirm it worked: ```bash ls -la /path/to/destination ``` Tell the user: "Your project has been downloaded to `/path/to/destination`. All the files from GitHub are there, and it's already connected — you can start making changes right away." Now skip to Step 3. --- ## Path C: Starting from nothing The user has no folder and no repo. We'll create both. ### C1: Name the project > "What would you like to name your project? This will be both the folder name on your > Mac and the repository name on GitHub. Keep it short, lowercase, and use dashes instead > of spaces (for example: `my-first-project` or `personal-website`)." ### C2: Choose visibility > "Should this be a **public** repo (anyone can see it) or **private** (only you can see > it)? Private is a safe default if you're not sure." ### C3: Choose location > "Where do you want the project folder? I'd suggest `~/Projects/project-name`. Would > you like it there, or somewhere else?" Create the parent directory if needed: ```bash mkdir -p ~/Projects ``` ### C4: Create the repo and clone it ```bash gh repo create repo-name --private --clone --description "A brief description" ``` (Use the org prefix if applicable: `ORGNAME/repo-name`) If the user chose a custom location, clone to that path instead: ```bash gh repo create repo-name --private gh repo clone owner/repo-name /path/to/destination ``` Confirm: ```bash ls -la /path/to/destination ``` Tell them where the project lives and that it's ready to go. --- ## Step 3: Check for uncommitted work and first commit At this point, the user has a local folder connected to a GitHub repo. Check if there's any work that needs to be committed. ```bash git -C /path/to/their/folder status ``` ### If there are untracked or modified files Show the user what's there: > "I can see some files in your project that haven't been saved to GitHub yet: > > - `file1.js` (new file) > - `file2.css` (new file) > - `README.md` (modified) > > Would you like me to commit these files and push them to GitHub? This will save a > snapshot of your current work." If they say yes: ```bash git -C /path/to/their/folder add . git -C /path/to/their/folder commit -m "Initial commit" git -C /path/to/their/folder push -u origin main ``` If the push fails because the remote has content (like a README created by GitHub), handle it: ```bash git -C /path/to/their/folder pull --rebase origin main git -C /path/to/their/folder push -u origin main ``` Explain what happened: "GitHub had a file that your local copy didn't have yet, so I pulled it down first and then pushed your code up. Everything is synced now." ### If the folder is empty or all files are committed If empty, let the user know: > "The folder is empty right now, which is fine — it's connected to GitHub and ready to > go. As soon as you add files and want to save them, just ask me to help you commit and > push." If everything is already committed and pushed: > "Everything in your folder is already synced with GitHub. You're all set." ## Step 4: Wrap up Tell the user where their project lives, both locally and on GitHub: > "Here's your setup: > > - **Local folder:** `/path/to/their/folder` > - **GitHub repo:** https://github.com/owner/repo-name > > Your folder and your GitHub repo are connected. When you make changes to files in that > folder, you can ask me to commit and push them — that saves your work to GitHub so it's > backed up and you can share it with others. > > Would you like me to open the folder for you, or is there anything else you need help > with?" If they want the folder opened: ```bash open /path/to/their/folder ``` ## Important notes - **Always confirm before creating things.** Don't create repos, folders, or commits without the user saying yes. These are their projects and their GitHub account. - **SSH remotes only.** Always use `git@github.com:owner/repo.git` format, never HTTPS. This matches what the onboarding skill set up. - **If anything fails**, explain what went wrong in simple terms and offer to help fix it. Common issues: - Permission denied → SSH key might not be set up (point them to GitHub Onboarding) - Repo already exists → ask if they want to use the existing one - Push rejected → remote has changes they don't have locally (pull first) - **Don't overwhelm with git concepts.** The user doesn't need to understand staging, HEAD, or refs right now. Use simple language: "save your work" instead of "commit", "sync with GitHub" instead of "push", "download the project" instead of "clone". But do mention the real terms in passing so they start learning them naturally. - **Respect the user's current directory.** If they're already in a folder when they ask for help, offer to use that folder rather than making them specify a path.