jove525/portfolio-builder

Portfolio Builder

Turns a person's work into a one-page portfolio. Claude plans the content in chat, locks it in a BRIEF.md, then hands over Claude Code prompts. Claude Code builds locally, pushes to GitHub, Netlify deploys. Claude then audits the repo and the live site.

Writing rules for everything this skill produces: casual, direct voice, short sentences, no em-dashes (regular hyphens only).

Phase 1: Gather before asking

• Pull what's already known: memory, past chats, live sites (fetch them for real feature lists and copy).
• Draft a content inventory first. Never start with a blank questionnaire.

Phase 2: Draft brief v1, then ask at most 4 decisions

Draft sections with real copy, then ask only what changes the build:

1. Primary audience (clients, hiring managers, or both, and which leads).
2. Visibility constraints (current employer named or generic; anything to keep private).
3. Which projects go in.
4. Where it lives (Netlify subdomain to start is fine).

Guardrails:

• No invented metrics, testimonials or clients.
• No claims the person hasn't made (e.g. AI work at a day job they didn't do).
• Team wins credited as team wins.
• If the employer stays generic, also drop details that identify it anyway (country lists, exact titles plus industry). Say "five markets", not the list.
• Watch region wording (e.g. "Asian markets" when one country spans continents) and vague pronouns in hero copy.

Project inclusion rule: a project earns a spot when it's live and shows a skill the audience would pay for. Too many ventures signals "no time for you." Parked or past work goes in a small "From the lab" row, labeled honestly. Unnamed or unlaunched projects wait.

Tools: list only tools used hands-on. Tools they're merely familiar with go in a one-line footnote ("Also comfortable in X and Y").

Phase 3: Fill the gaps

Ask for: display name, headshot, one screenshot per build, live URLs, GitHub URL, contact email, socials. Rewrite any supplied site copy to be portfolio-appropriate (what it is, who it's for, what they built). Every card link must point to a live page that actually describes that item. If the page isn't ready, no link and tag it (e.g. "Launching"). Defer anything not ready (booking link, "work with me", testimonials) to a "Later" list instead of blocking v1.

Phase 4: Lock BRIEF.md

Write BRIEF.md with these sections, in order:

• Goal (10-second test: what they build, proof, how to reach them)
• Audience
• Rules for copy (voice, no em-dashes, visibility and accuracy guardrails, use copy as written)
• Tech (plain HTML/CSS/vanilla JS, no build step; index.html, styles.css, main.js, /assets; GitHub + Netlify; Lighthouse 95+; mobile first)
• Design direction (default Apple-like: Inter or system font, generous whitespace, ~1080px max width, ~680px text blocks, tight large headlines, neutral palette, 20-24px card radius, hairline borders, one accent used sparingly, light/dark with toggle, subtle fade-up respecting reduced motion, screenshots in a minimal browser-frame card, sticky blurred nav)
• Layout rules (bake these in from the start):
  • Nav and every section share one container, so all left edges line up.
  • One section-spacing token (about 96px desktop, 56px mobile) for every gap; no stacked paddings.
  • Hero fits above the fold on 1366x768 and 375x812 including browser toolbars (about 650px and 635px visible).
  • Headline: text-wrap pretty on mobile, balance on desktop; no forced line breaks.
  • Every section has a visible heading or eyebrow label, so nothing floats.
• Assets (exact file paths; screenshots converted to WebP with smaller mobile sizes, lazy-loaded below the fold; placeholder if missing, never a broken image)
• Page content, top to bottom, with final copy: Hero, What I do (3 cards), Builds (featured card + grid + lab row), How I build, Tools (grouped pills), Background strip, Principles (in the person's own words, not borrowed quotes), Contact, Footer
• SEO and meta (title, description, OG image, favicon, semantic HTML, alt text, focus states, AA contrast)
• Prefilled details: repo URL, preferred subdomain plus fallback, social handles, email, so Claude Code doesn't have to ask
• Later (not in v1)

Accent color: pick one that separates from the colors in the build screenshots. Give exact hex values for light and dark mode, and check AA contrast for links AND button text on the accent in both modes (dark mode buttons usually need dark text on a light accent).

Deliver BRIEF.md as a file.

Phase 5: Setup steps + 4 prompts

Setup (once):

1. Create an empty GitHub repo, then git clone <repo-url> into a local folder so git is already wired.
2. Put BRIEF.md in the root; add /assets and /assets/shots with the named files.
3. Open Claude Code in that folder.

Prompt 1, Plan:

Read BRIEF.md fully. Don't write code yet.
Give me a short build plan: file structure, section-by-section layout, the color tokens and type scale you'll use, and any questions or conflicts you see in the brief. Keep it under one screen.
Accent color: <LIGHT_HEX> in light mode, <DARK_HEX> in dark mode. Use it sparingly and confirm both pass AA contrast, including button text.

Help the person answer its questions in one pasteable reply.

Prompt 2, Build:

Build the site exactly per BRIEF.md and the plan we agreed.
- Use the copy word for word. No em-dashes anywhere.
- Plain HTML, CSS, vanilla JS. No frameworks, no build step.
- Accent: <LIGHT_HEX> light, <DARK_HEX> dark. Everything else neutral.
- Follow the layout rules in BRIEF.md (shared container, one spacing token, hero above the fold).
- Use the images in /assets as WebP. Show a clean placeholder if one is missing.
- Light and dark mode, sticky blurred nav, fade-up on scroll with reduced-motion support.
When done, start a local server and tell me the URL so I can review it.

Prompt 3, Polish:

Review the site like a senior designer at Apple would, then fix what you find:
1. Check at 375px, 768px, 1366px and 1440px. No horizontal scroll, nothing cramped.
2. All left edges line up; every section gap uses the one spacing token.
3. Hero fits above the fold with browser toolbars at 1366 and 375.
4. Dark mode looks intentional, not inverted. Accent reads well in both modes.
5. Accessibility: alt text, focus states, AA contrast, semantic headings.
6. Search all files for em-dashes and replace them.
7. Run Lighthouse and get all four scores to 95+.
Give me a short list of what you changed.

Then the person gives plain-language feedback until happy.

Prompt 4, Push and deploy:

This folder is already cloned from <REPO_URL>.
1. Add a .gitignore and a netlify.toml (publish dir = root, sensible cache headers, and 404 for BRIEF.md and source PNGs so they aren't public).
2. Commit everything with a clear message and push to main.
3. Connect the repo to Netlify. Try <SUBDOMAIN> first, fallback <FALLBACK>. If Netlify's GitHub app can't see the repo, tell me how to grant it access.

Note: Claude Code often runs ahead and does build, polish and deploy in one go. That's fine; skip to the audit.

Phase 6: Audit after push

When the repo or live URL is shared:

1. Clone the repo and check: copy matches BRIEF.md, nothing invented, no em-dashes, no restricted names, all links correct, images WebP with alt text and sizes, meta/OG/favicon present, internal files blocked from the live site.
2. Visual pass on the live site in the browser at 1440 and 1366 (light) and 375 (dark): edge alignment, gap consistency, hero above the fold, headline wrap, nothing overlapping.
3. Give fixes as one pasteable Claude Code prompt, then recheck after the push. If the repo is empty, say so plainly and ask them to push first.

Known gotchas:

• Netlify adds a "Powered by Netlify" badge on Free-plan projects created after Aug 19, 2026. It's not in the code: turn it off under Project configuration > General > Powered by Netlify badge, per project.
• Live Lighthouse scores from slow connections vary; judge with pagespeed.web.dev, not local runs alone.

Phase 7: Sync the rest of their presence

Offer to align the GitHub profile README (and other bios) with the portfolio: same positioning line, same contact email, links to the live builds and the portfolio, and remove projects the portfolio intentionally left out.