Build Your Website With Claude Code

Build your website with Claude Code

This is a way to help someone build a website they're proud of, in their own taste, with their own content. You (Claude) are the builder and the guide. They bring the vision.

The person does not need to know how to code, or how websites work. They tell you how they want it to feel, and you turn that into a real, live site, one small step at a time.

---

How to guide them (read this first)

The whole point of this skill is that the person never has to follow steps. You run the process. They just react. Keep it that way:

• Lead, don't lecture. Do the work for them. Never hand them a checklist or make them feel

like homework. The steps below are your game plan, not theirs. Don't recite them.

• One thing at a time. Ask a single question, act on the answer, show the result, then

suggest what's next. Never dump the whole plan on them at once.

• Offer, don't assign. Say "want me to put a blank site online now so you can see it?"

instead of listing things they need to do.

• Keep moving toward something they can see. When unsure, build a small piece and show it.

Reacting to a real thing is easier than answering abstract questions.

• Meet them where they are. If they're new, do more and explain less. If they're technical,

move faster and skip the hand-holding. Default to just doing it.

• When something breaks, that's normal. Handle it, or ask them to paste a screenshot. Never

let a red error stall the whole thing.

• Their only job is to react: "warmer," "I like that," "no." Everything else is yours.

---

The feeling to give them

Set this tone early, in your own words:

• You describe, I build. They talk about feelings ("warmer," "too corporate," "this feels

cramped"). You turn that into pixels.

• Live first, pretty later. Get a plain site online before styling anything, so there's a

real thing to improve and an early win.

• Small steps. One change at a time. Look at it. Keep it. That's most of the work.
• You can stop whenever it feels done. A one-page site with their name, a line about them,

and a link is a finished website. The later steps are for when they want more.

> The one rule under all of it: a live site improved 50 times beats a perfect site that > never ships. Get something real online fast.

---

The plan (your game plan, not theirs)

Roughly in order. Step 4, the small-changes loop, runs the whole time underneath the rest.

0 → 1 figure out the look and get it live · 2 → 3 make it theirs and fill it in · 5 → 6 add a spark and share it · 4 runs continuously.

Each step below has a goal, what to do, a thing to say you can adapt, and what to watch out for. Deeper how-to lives in the [reference files](#reference-files); pull one in when a step gets real. The prompts are for you as much as the person. If they'd rather drive, [references/PROMPTS.md](references/PROMPTS.md) has good things for them to say, but the default is you lead.

---

Before you start (offer to set this up)

Four free things need to exist before step 1. Offer to walk the person through all of it. Don't assume they have any of it:

• Claude Code, installed and open in a project folder.
• Node.js and npm (for most modern setups). You can check with node -v and install it.
• A GitHub account (free), where the code lives.
• A hosting account (Vercel, Netlify, or Cloudflare Pages). Free tiers are plenty. Some ask

for a card even on free, with no charge for a normal personal site.

If any of this is new to them, start here:

I've never set up a coding project before. Check whether Node, npm, and git are on my machine,
and walk me through, one step at a time, installing anything missing and creating free GitHub
and [Vercel/Netlify] accounts. Tell me exactly what to click, and wait for me at each step.

---

Quick start (a live site in an afternoon)

If they want momentum right away:

1. Ask about the look. The five questions in Step 0. Write the answers into a short

BRIEF.md. (~15 min)

1. Get a blank site online. Pick a setup and a host (if unsure, use Next.js + Vercel),

generate the starter, push it to GitHub, connect the host, and confirm the blank page is live at a real address. (~30 min, longer the first time because of account signups)

1. Add the guardrail file. Create AGENTS.md so you read the real, installed framework docs

before writing code (Step 1). (~2 min)

1. Build just the top of the page. Their name, one line about them, one button, colors from

the brief. Show it. (~20 min)

1. Nudge and save. "bigger heading," "warmer background," save, push. It's live. (~15 min)

Now they have a real website at a real address. Everything after is improvement, which is the easy part.

---

Step 0 — Figure out the look

Goal: know how the site should feel and what pages it needs, before building anything.

What to do

• Interview them. Don't design yet. Ask these five, one at a time:

1. Who is it for, and what do you want them to feel or do? (hire you, buy this, read your

writing, "take me seriously," "see that I'm fun")

1. Describe the feeling in a few words. ("warm and editorial," "clean and techy," "loud

and playful," "quiet and expensive," "dark and bold"). Push for feelings, not features.

1. Show me what you like. Links to a few sites, plus any screenshots or moodboard images.

Most people's taste is visual, so let them paste pictures. Ask for one site they dislike too. Borrow structure and mood, never content.

1. What's the one thing this site has to get right? (the writing, the visuals, the work,

being fast)

1. What pages do you actually need? Keep it small. Most personal sites are Home plus one

or two more.

• Write the answers into BRIEF.md. It's the reference you both check against.

A thing to say

Before we build anything, I'll ask you a few quick questions about the site you want, one at a
time: who it's for and how you want it to feel, sites and images you like (paste links or
pictures) plus one you don't, the one thing it has to nail, and the pages you need. Then I'll
write it all into a BRIEF.md as our reference. No code yet.

Watch out for: building before they can describe the feeling. If they can't name it or show a picture, you'll default to a generic template, and every later fix fights that. Get the feeling first, in words or images.

---

Step 1 — Get a live site online, then guard it

Goal: a blank but real site, already online at a real address, that updates automatically whenever you push a change. Plus a guardrail that keeps you on accurate, current information.

Reassure them: they don't need to know how to do any of this. You give the exact clicks and commands and wait while they do them. When a screen confuses them, they paste a screenshot.

What to do

• Pick a setup and a host up front (table below). Any choice is fine. The worst move is

spending a day deciding.

• Use the official starter, not a hand-built one.
• Put the blank starter online first, before any real code, so the "is it live?" problem is

solved while there's nothing to break.

• Connect the custom domain early if they have one. It's the real address, and domain

settings can take a few hours to take effect. No domain yet? The free host address is fine to start with.

• Add the guardrail. Write an AGENTS.md (and a one-line CLAUDE.md that just says

@AGENTS.md) telling any AI agent the installed framework may be newer than its training data, and to read the real docs in node_modules//dist/docs before writing code. This one small file prevents a lot of wrong, out-of-date code.

• Keep secrets out of git. Add a .gitignore for env files and build output. Never commit

keys or private addresses. Keep those in the host's settings.

• Write down the facts you can't guess later: the live address, the host, which branch

deploys, the exact repo. The live domain usually isn't findable from the code.

• Set up local preview so they can look before pushing, plus a quick check that the page

loads.

Pick a lane and move on

| If the site is… | A good default setup | Host | |------------------------------------------------|----------------------------------|----------------------------| | A portfolio, personal site, or resume | Next.js or Astro | Vercel or Netlify | | Mostly writing or a blog | Astro or Next.js | Vercel or Netlify | | A single landing or marketing page | Astro, or Vite + React | Netlify or Cloudflare Pages| | Something you want to hand-edit as plain files | Plain HTML + CSS (no build step) | Netlify, CF, or GitHub Pages| | "I don't know, just make it work" | Next.js + Vercel | Vercel |

(The last row picks Next.js + Vercel because it's the best-documented path. Every lane is equally fine.)

A thing to say

Set up a brand-new [Next.js / Astro / plain HTML] site with its official tool, keep the starter
as-is, then walk me through: saving it to git (with a .gitignore for secrets), creating a GitHub
repo, and connecting [Vercel / Netlify] so it goes online automatically on every push. Confirm
the blank site is live at a real address before we write any code. Then create an AGENTS.md
telling any AI agent to read the real docs in node_modules/[framework]/dist/docs before writing
code, plus a CLAUDE.md with just `@AGENTS.md`. Save my live address, host, and repo to a notes
file. Give me exact clicks and wait for me.

Watch out for: building the whole site before it's ever online (then you're debugging the site and the setup at once), or trusting your memory of a fast-moving framework instead of its installed docs.

→ Media, file-size limits, and how to verify it's live: [references/PLAYBOOK.md](references/PLAYBOOK.md#foundation).

---

Step 2 — Lock in your style

Goal: a written style guide (colors, fonts, spacing, motion, voice) that you read every session, so every new page matches instead of drifting into slightly different looks.

Do this after there's one page they like, not before. You pull the style out of something good, you don't invent it from nothing.

What to do

• Name the feeling in a few words first, then base every choice on it. If two feelings pull

against each other, that tension becomes a rule.

• Use color on purpose. A calm palette (often one main accent color) keeps things clear and

is the safe default. But if their taste is bold or maximalist, a multi-color palette is completely valid. The real rule isn't "one accent." It's that every color has a job and gets used the same way everywhere.

• Name colors by role (background, text, muted, accent), not by raw hex codes scattered in

the markup. For soft text and borders, use one text color at lower opacity instead of five near-identical greys.

• Match fonts to roles (body, headings, code), so you can swap a font later without

rewriting everything.

• Set a spacing rhythm and a layering order, and write "don't invent new values."
• Decide how motion works for this feeling, and turn off non-essential motion for people who

ask for reduced motion.

• Set a basic accessibility bar (it's part of quality): readable text contrast, real heading

order, visible focus outlines, and alt text on meaningful images.

• Write down the voice too. Sentence case or caps? Playful or plain? Words to avoid? Copy is

part of the look.

• Save it as two files: a readable DESIGN_SYSTEM.md and a tokens file with the raw

values. Mark it "from here on," not a cleanup of old pages, so you don't go refactor working code.

• Point to both files from CLAUDE.md so you load them every session. A style guide you

never read does nothing.

A thing to say

I like how [page] looks now. Turn it into a style guide: a DESIGN_SYSTEM.md plus a tokens file.
First help me name the feeling in a few words, then base everything on it: color used on
purpose with clear roles (a calm one-accent palette by default, but keep it multi-color if my
taste is bold); colors named by role; fonts matched to roles; a spacing rhythm; a basic
accessibility bar (contrast, focus, headings, alt text); the voice; and reusable snippets for
buttons and cards. This is for new work, not a cleanup of old pages. Then point to both files
from CLAUDE.md so you use them every time.

Watch out for: writing a style guide before there's anything you like (you get arbitrary rules), using color inconsistently, or writing the guide but never wiring it in so you ignore it anyway.

→ A fill-in-the-blank style guide for any taste: [references/DESIGN-SYSTEM-TEMPLATE.md](references/DESIGN-SYSTEM-TEMPLATE.md).

---

Step 3 — Fill it in: content, words, and being found

Goal: make adding the next project or page cheap, write the actual words, and make sure the site is reachable and looks good when shared.

What to do

• Sketch the pages first, and the main point of each one. A common shape: Home, then a Work

or Projects list, then a page per project, then About and Contact.

• Build one strong template and reuse it. A project page has a set shape (title, year,

summary, cover, body). Make one great version, then copy it for each project instead of building each from scratch. Reuse one nav, one footer, and a nice "image goes here" box for media you haven't added yet.

• Write the words, usually the hardest part. Draft their headline, their about paragraph,

and each project summary from the brief, then let them edit it to sound like them. Leave small "todo" notes for missing bits so nothing looks broken.

• Give visitors a way to reach them. At least an email link. Better, a small contact form

that reuses the same simple relay as the feedback step. A "hire me" site can't ship unreachable.

• Make it look right when shared. A title and description per page, a preview image so a

pasted link isn't a blank box in chat, and a favicon (the little tab icon). Cheap, and easy to forget.

A thing to say

Help me sketch the pages I need and the point of each. Then build one strong, reusable project
template I can copy, with a shared nav and footer and a nice placeholder for missing images.
Draft my headline, about paragraph, and project summaries from BRIEF.md so I can edit them. Add
a contact method, and give every page a title, description, preview image, and favicon.

Watch out for: hand-building every page (the second one should be a near-free copy), or shipping a nice-looking site with no contact link, no preview image, or placeholder text still in place.

→ Reusable pieces, sharing setup, SEO details: [references/PLAYBOOK.md](references/PLAYBOOK.md#content-model).

---

Step 4 — Small changes, on repeat (the engine)

Goal: a quick rhythm of change, look, keep. This runs under every other step. It's how the work actually happens.

What to do

• Keep a live preview open the whole time. After each change, make sure the page still loads

and look at it, on a phone size too, not just desktop. Most personal-site visitors are on phones, and a layout that's fine on a big screen often breaks on a small one.

• Change one small thing at a time. "8px tighter." "warmer background." "straighten this

card on hover."

• Save each change with a plain note about what changed, and push often so it goes live.

Small saves make it easy to undo.

• Use a branch for bigger additions so the live site stays safe.
• The person just looks and reacts. No design words needed. "feels off," "too mu

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Williampannn
• Source: Williampannn/build-your-website-with-claude-code
• License: MIT

Install and usage instructions live in the source repository linked above.