first-repo

The walkthrough

From downloading this kit to a live website, in eight stages.

Each stage is one Claude Code session. You paste one short line; Claude Code reads this file and does that stage. Then it stops, and you check it worked before moving on.

That is the whole method. One stage, one prompt, one check.

Stage What you have afterwards
0 · Get oriented You know what a repo is; Claude Code knows your goal
1 · Tools git, the GitHub CLI, and Node 22 installed
2 · Link GitHub Your laptop signed in, so Claude Code can push for you
3 · Build your site Real pages with your name on them, open in your browser
4 · Make it a repo Your site has a memory, and a private copy on GitHub
5 · Go live A real URL other people can open
6 · Change something The ask → build → check → approve → deploy loop
7 · House rules Safety rules that travel with your project

Before you start

Three things, none of them a terminal:

  1. Install Claude Code — the desktop app, from claude.com/code.
  2. Get a free GitHub account at github.com — you will connect it in Stage 2.
  3. Download this kit and put the folder in your Downloads.

Then open Claude Code, choose the first-repo folder as your project — the folder a session is allowed to read and work in — and start a session.

If the folder came from a GitHub zip it may be called first-repo-main — either rename it to first-repo, or use whatever name it actually has anywhere these pages mention the folder.

Prefer a terminal? The same thing is: cd ~/Downloads/first-repo, then claude — and if that says command not found: claude, Claude Code is not installed yet; install it first.

That is it. Claude Code now has this kit as its project, and it can read every file here.

How the prompts work. They are deliberately short. You are not writing instructions — you are pointing at a document that already contains them. This is the habit worth learning: keep the instructions in a file, point at the file. Long prompts get retyped, half-remembered, and drift. A file does not.

If a stage goes wrong, do not push on. Say:

Stop. Explain what went wrong before doing anything else.

Stage 0 · Get oriented

Paste: Do Stage 0 of WALKTHROUGH.md.

Goal — Claude Code learns the kit, and you learn what is about to happen.

Agent steps

  1. Read README.md Parts 0 and 6, and starter/AGENTS.md.
  2. Tell the human, in under 150 words: what a repo is, what we are building over the next seven stages, and what will be live at the end.
  3. Ask two questions and note the answers in a new file, MY-SETUP.md, at the kit root:
    • What is this site for? (personal academic page, project page, something else)
    • Do they have a GitHub account already?
  4. Change nothing else.

Done when — MY-SETUP.md exists, and you could explain to someone else what a repo is.

Stop here.

Stage 1 · Tools

Paste: Do Stage 1 of WALKTHROUGH.md.

Goal — git, the GitHub CLI, and Node 22 are installed.

Agent steps

  1. Run git --version; gh --version; node --version and show the real output.
  2. Report what is missing. Install nothing yet — ask first.
  3. On approval, install only what is missing, following README.md Part 1. Node must be 22.
  4. Re-run the checks and show the output again.

🧑 Only you —

Done when — all three commands print a version, and Node says 22.

Stop here.

Stage 2 · Link GitHub

Paste: Do Stage 2 of WALKTHROUGH.md.

Goal — your laptop is signed in to GitHub, so Claude Code can push on your behalf.

Agent steps

  1. Explain in one sentence that there is no “connect” button — we sign the laptop in once, and Claude Code uses that sign-in.
  2. Run gh auth login. Answer: GitHub.com · HTTPS · Yes · Login with a web browser.
  3. ⚠️ Press Enter when prompted — the browser does not open until you do. Then hand the keyboard over.
  4. After sign-in: gh auth setup-git, then gh auth status. Confirm the repo scope is listed.
  5. Set the commit identity — ask for their name and email, then git config --global user.name / user.email.
  6. Prove it: gh api user -q .login.

🧑 Only you — the browser sign-in. Note the one-time code, sign in, type the code, click Authorize. Nobody can do this for you, and nobody should ask you to share the code. And the email in step 5 is your decision: it is stamped on every snapshot, and becomes public if the repo ever does. Pick one you are happy to see published.

Done when — gh api user -q .login prints your GitHub username.

Stop here.

Stage 3 · Build your site

Paste: Do Stage 3 of WALKTHROUGH.md.

Goal — a real website, with your name on it, open in your browser.

Agent steps

  1. Create ~/Downloads/my-site/ and copy everything from this kit’s templates/ into it.
  2. Ask for: name, role, institution, field, three research interests, email.
  3. Fill in every [bracketed placeholder] across all three pages with the real answers. Do not invent anything — if they do not supply a value, leave the placeholder and say which ones are outstanding.
  4. Open my-site/index.html in the browser so they can see it.
  5. Confirm no [ remains except any they deliberately left.

🧑 Only you — decide what it says. Ask for changes in plain English; that is Stage 6.

Done when — the page opens, and it is about you rather than [Your Name].

🧑 Switch projects now

Your site lives in its own folder from here on. End this session, then start a new one with ~/Downloads/my-site as the project folder — the same way you opened the kit, just pointing at the new folder. (Terminal: cd ~/Downloads/my-site, then claude.)

You are now working in your site, not in the kit. For the remaining stages, tell Claude Code to read the walkthrough from where it lives: Do Stage 4 of ~/Downloads/first-repo/WALKTHROUGH.md.

Stop here.

Stage 4 · Make it a repo

Paste: Do Stage 4 of ~/Downloads/first-repo/WALKTHROUGH.md.

Goal — your site folder has a memory, and a private copy on GitHub.

Agent steps

  1. Confirm the working folder is ~/Downloads/my-site. If it is inside Google Drive, iCloud or Dropbox, stop and say so — move it first.
  2. Write a .gitignore and explain each line.
  3. Scan for secrets before the first commit — passwords, keys, tokens, .env files. Report what you find.
  4. git init, git add -A, git commit -m "First snapshot".
  5. Show git log and git status.
  6. Ask whether to create the GitHub repo. On a yes: gh repo create my-site --private --source=. --push.
  7. Print the repo URL.

🧑 Only you — the yes at step 6, and the choice of private. Keep it private for now; you can make it public in Stage 5 once you have seen what is in it.

Done when — the GitHub URL loads and shows your files.

Stop here.

Stage 5 · Go live on Netlify

Paste: Do Stage 5 of ~/Downloads/first-repo/WALKTHROUGH.md.

Goal — a real URL, on the real internet, that other people can open.

Agent steps

  1. Say plainly what is about to become public: every file in this repo. List anything that should not be. Wait for confirmation.
  2. Explain the two routes and recommend one:
    • GitHub Pages — free, no third service, but the repo must be public.
    • Netlify — repo can stay private, more capable later, needs a Netlify account.
  3. Walk the chosen route one step at a time, stopping at each browser step.
  4. For Netlify: no build command is needed — these are plain HTML files. Publish directory: leave blank (or .).
  5. Once live, fetch the URL and confirm it returns HTTP 200 and shows their name. Show the evidence.

🧑 Only you — everything in the browser: creating the Netlify account, authorising it to see your GitHub, picking the repo, clicking Deploy. And on GitHub Pages, the decision to make the repo public — that one is a one-way door.

Done when — you can open the URL on your phone.

Stop here. This was the goal.

Stage 6 · Change something and ship it

Paste: Do Stage 6 of ~/Downloads/first-repo/WALKTHROUGH.md.

Goal — learn the loop you will use forever: ask → build → check → approve → deploy.

Agent steps

  1. Copy EDIT_REQUESTS.md from this kit’s starter/ into the site repo. Explain it in two sentences.
  2. Ask what they want changed. Log it as REQ-001 using the template.
  3. Make the change.
  4. Show them the changed part rendered — not a description of it, the actual result.
  5. Wait for approval. Do not deploy.
  6. On approval: git add -A, commit with a clear message, git push.
  7. Wait about two minutes, fetch the live URL, and confirm the change is actually there.
  8. Mark REQ-001 Done with one line on what changed.

🧑 Only you — step 5. Nothing reaches the internet without you saying yes. Get used to being asked; a tool that deploys without asking is a tool you cannot trust with anything that matters.

Done when — the change is visible on the live URL, and REQ-001 says Done.

Stop here.

Stage 7 · Give the project its own rules

Paste: Do Stage 7 of ~/Downloads/first-repo/WALKTHROUGH.md.

Goal — the safety rules travel with the project, so you never have to remember them.

Agent steps

  1. Copy AGENTS.md and CLAUDE.md from the kit’s starter/ into the site repo.
  2. Fill the two placeholder sections in AGENTS.md:
    • About this project — from what is actually in the folders. Ask if it is not obvious; do not invent a purpose.
    • How to check your work — the real command. There isn’t one here, so write that honestly.
  3. If an AGENTS.md already exists, do not overwrite it — show both and let them choose.
  4. Show the finished file before saving.
  5. Commit and push.

Done when — AGENTS.md is in the repo and you have read it.

You are done

You have a live website, a private backup of it, a way to request changes, and a project that tells every future AI session what it may and may not do.

The loop from here, forever:

git pull → make the change → check it → git push

Or in English, to Claude Code: “pull, make this change, show me, then wait.”

Where to go next

Want Read
Better prompts PROMPTS.md
Fonts, colour, layout templates/README.md
Why any of this works README.md — especially Part 6
A custom domain README.md Part 5c
More pages than you can hand-edit README.md Part 5c — a site generator

For whoever is teaching this

If you are walking someone through in person: your job is to stop them skipping stages, and to make them say out loud what each one did before you move on. The stages are sized so that a failure is always inside the last thing you did — that property disappears the moment two get merged.

The most valuable minute in the whole walkthrough is Stage 6, step 5: the first time somebody is asked for approval before something goes public, and realises they can say no.

This site is open source. Improve this page.