# instructions.md - Portfolio Build Brief

> Hand this file to Claude Code, Codex, or any coding agent. It is the operating contract for building your portfolio.
> Audience: a designer or engineer, possibly a weak coder, working through an AI agent.
> Read it top to bottom once, then work the build loop at the bottom.

## Role And Goal

You are building a portfolio that passes a hiring manager's 10-second gut check.

A hiring manager opens the site, scrolls once, and decides in about ten seconds whether this person has taste. That judgment is mostly visual. Optimize for that moment first, everything else second.

- Build a small, fast, single-page-feeling site that shows real work above the fold.
- Win the 10-second gut check on visual craft alone.
- Ship it live on a real domain. An unfinished or templated-looking site fails before anyone reads a word.

## Before You Start (read this if you can barely code)

If the human driving you has never used a terminal, walk them through this before touching the build. Do not assume any of it is already in place.

1. Node.js. Most commands here run on it. Install from https://nodejs.org (the LTS build). Confirm it worked: run `node -v` and you should see a version number. If you see "command not found", Node is not installed yet.
2. A terminal. This is the text window where commands run. On a Mac it is the Terminal app (Applications, Utilities). On Windows it is PowerShell. Open it before anything else.
3. The agent itself. You are that agent. The human needs you installed and signed in per your own setup page (Claude Code or Codex). This usually costs money, either a monthly plan or pay-as-you-go credits. Sort that out first so nothing stalls mid-build.

The single most important recovery habit: if any command fails, copy the exact error message and paste it back to the agent with "this failed, fix it." That is the lifeline for a non-coder. Use it freely.

## The Standard To Hit

Benchmarked across 50+ reference portfolios, including the ones that get people hired at Linear, Vercel, Stripe, and Figma. Treat each line as a hard requirement.

- Make the work the hero. Show real work in the first scroll. Not a bio, not a mission statement, not process docs. The first thing on screen is the work.
- Curate ruthlessly. Ship 3 to 5 projects, never 8 or more. If removing a project would raise the average quality of what remains, remove it. Exception: work at a well-known company counts regardless of project count, keep it.
- Default to radical minimalism. Use a single-column layout. Use whitespace on purpose. Restraint reads as confidence. Stay monochrome plus at most one accent color.
- Put craft in the details. Choose a real typeface on purpose, never default-system-with-no-thought. Add considered micro-interactions, hover states, and transitions. This is the heaviest signal: if the visual craft is off, nothing else matters.
- Send builder signals. Ship something real. Side projects, live tools, experiments, open source. A `/craft` or `/lab` page is itself the work. The portfolio is proof of making, not just documenting.
- Write one to three sentence project descriptions. The homepage is a business card, not a brochure.

The single most important thing: visual craft over everything. Taste, restraint, attention to detail. When a tradeoff is unclear, choose the more restrained, more crafted option.

## Leave These Out

The absence of these is a tell that you studied what works. Do not add them.

- No testimonials.
- No skill bars or skill lists.
- No "hire me" CTAs.
- No contact forms. Use a plain email link instead.
- No process documentation on the homepage.
- No awards sections.
- No profile photo on the homepage.
- No multi-color palettes. Monochrome plus one accent, maximum.
- No `.framer.website`, `.squarespace.com`, or obvious stock-template URL. That signals "I did not finish this." Use a real custom domain.

## Tech

Pick the lightest option that lets you ship real craft. In order of preference:

1. Next.js Portfolio Starter Kit (recommended honest baseline). A minimal Next.js + MDX site: a short homepage bio, a blog/writing index, RSS, dark mode, MIT licensed, one-click deploy to Vercel. You write posts as MDX files and barely touch code.
   - Live demo: https://portfolio-blog-starter.vercel.app
   - The demo page carries the "Deploy" (one-click deploy to Vercel) and "View source" links. Use those, do not guess a GitHub path.
   - For a non-coder, the simplest start is to have the agent do it: open a terminal, make a new folder, open the agent inside it, and tell the agent to clone the Next.js Portfolio Starter Kit into that folder and get it running with `npm install` then `npm run dev`. The agent handles Git and the install. That local folder is what every later step points at.
   - If the demo buttons ever move, the canonical source is the Vercel "Portfolio Starter Kit" example. Search Vercel templates for it.
   - Then point the agent at it and make it yours: replace the bio, swap the type, add your projects, build a `/craft` or `/lab` page.
2. A clean Next.js + Tailwind app, if you want full control.
3. Plain HTML and CSS. Acceptable if it is crafted and fast.

Deploy to Vercel either way.

## Where This File Goes

Save this instructions.md file inside your project folder, the same folder you open the agent in. The agent can read any file in that folder, so "attached" just means "sitting in the folder." When you kick off, tell the agent to read instructions.md first.

## Content Rules

- Ship 3 to 5 projects. No more.
- Write one to three sentences per project.
- Put real work in the first scroll, above the fold.
- Use real screenshots or video of shipped work. Never wireframes or mockups standing in for the real thing.
- Getting images in: drop your image and video files into the starter's `public/` folder. In an MDX post or page, reference them by path, for example `![Project one](/project-one.png)`. If you are unsure where a file should live, ask the agent to place it and wire up the reference for you.
- If you have a live tool or experiment, link it and let it run.

## Craft: Tools And Skills To Feed Your Agent

Install these and feed them to your AI coding agent so it builds real craft instead of generic slop. Each line says what the tool is for. Do not invent features beyond these descriptions. Run every install command in a terminal that has Node.js installed (see "Before You Start"). If an install command errors, paste the error back to the agent and have it fix the command before moving on.

- Portfolio Polish (our own skill). A brutally honest portfolio audit scored across 8 categories out of 40, benchmarked against 50+ reference portfolios. Point it at your site and it tells you what a hiring manager sees in 10 seconds and exactly what to fix. This is your audit loop.
  - Repo: https://github.com/flows-cv/portfolio-polish
  - Install: `npx skills add flows-cv/portfolio-polish`
  - Run: `/portfolio-polish` then your url
  - It browses with a headless browser, so it can read a local URL. Make sure your dev server is running (`npm run dev`) and pass the local URL it prints, usually http://localhost:3000. If it cannot reach your local URL, deploy a preview to Vercel first and audit that public URL instead.
- Impeccable. An agent skill that teaches your AI real visual taste, a design vocabulary, slop detection, and live in-browser iteration. Works with Claude Code, Codex, Cursor, and others. Stops the default generic frontend.
  - Site: https://impeccable.style
  - Install: follow the install command on impeccable.style. Use the exact command shown there rather than guessing, since a wrong guess will silently do nothing.
- make-interfaces-feel-better. Jakub Krehel's collection of the small details that compound into a great interface (text-wrap balance on titles, text-wrap pretty on paragraphs, and more). An installable skill.
  - Writeup: https://jakub.kr/writing/details-that-make-interfaces-feel-better
  - Install: follow the install line in the writeup, then point the agent at it.
- Agentation. Visual feedback for agents. With your site running locally, click any element, leave a note, and paste the structured output into Claude Code or Codex. It turns "this button feels off" into something the agent can act on.
  - Site: https://agentation.dev
  - Setup is more than one step: install per the site, run your local site (`npm run dev`), open it in the browser, then click elements to leave notes. Follow the site's own instructions for wiring it in.

Also worth feeding it for taste (use what fits, do not dump everything in). The mechanic: screenshot a layout or animation you like and drag the image into the agent, or paste the URL and say "match this feeling on my project list."

- godly.website. Curated best-in-class web design.
- 60fps.design. Real shipped animations worth studying.
- motion.dev. The animation library behind many of these portfolios.

## Study These References (Principles, Not Pixels)

Look at how they decide, not what to copy. If you cannot browse them, the human can screenshot each one and drag the images in, then you reason from the screenshots.

- https://paco.me
- https://rauno.me and https://rauno.me/craft
- https://emilkowal.ski
- https://shud.in
- https://hector.me

## The Build Loop

1. Scaffold. Have the agent clone the Next.js Portfolio Starter Kit into your project folder and run it locally, or start a clean Next.js + Tailwind app. Confirm the site loads at the local URL before going further.
2. Fill with real work. Add your 3 to 5 projects with real screenshots or video and one-to-three-sentence descriptions. Put the strongest work first.
3. Polish in small passes. Type, spacing, one accent color, hover states, transitions. Feed the craft skills above to your agent. Use Agentation to point at the exact thing that feels off. Show the human each pass before moving on.
4. Audit. Run `/portfolio-polish <your-url>` against the running local URL (dev server up) or a deployed preview.
5. Fix the lowest-scoring categories first. Hand each finding back as its own small task.
6. Repeat steps 3 to 5. If a command fails at any point, paste the error back and fix it before continuing.

## Shipping Bar

You do not need a perfect score to go live this weekend. Two bars:

- v1 ship bar (good enough for Sunday night): every category scores at least 3 out of 5, nothing below 3. Put it live and keep iterating.
- Target bar (aim for it over the following week): 4 or higher in every category.

A shipped portfolio on a real domain beats a perfect one that never goes up.

## Deploy And Custom Domain (Vercel)

Simple enough without an engineering background.

1. Push your project to a GitHub repo. The starter kit's "Deploy" link can do the first deploy for you.
2. Go to https://vercel.com, sign in with GitHub, and import the repo. Accept the defaults and deploy. You now have a live `*.vercel.app` URL.
3. Get a domain. Easiest path by far: buy it through Vercel Domains (Settings, then Domains, then search and buy). When you buy through Vercel, DNS is wired up automatically and you can skip the next step entirely. This is the recommended path for a non-coder.
4. If you bought the domain elsewhere (Namecheap, GoDaddy, etc.), add it in Vercel under your project, Settings, then Domains, then point DNS in your registrar to the records Vercel shows you. The usual values:
   - An A record for the root domain (`@`) pointing to `76.76.21.21`.
   - A CNAME record for `www` pointing to `cname.vercel-dns.com`.
   - Use the exact values Vercel displays for your project if they differ. Vercel issues HTTPS automatically once the records resolve.
5. DNS can take anywhere from a few minutes to a couple of hours to take effect. If the domain does not load right away, that is normal. Wait and recheck before changing anything. If Vercel shows "Invalid Configuration" after a few hours, re-open the Domains panel, confirm the records match exactly, and remove any old conflicting A or CNAME records in your registrar.
6. Confirm the live site loads on your custom domain. Do not ship on a `*.vercel.app`, `.framer.website`, or template URL as the final link.

## Definition Of Done

- Real work is the first thing on screen, above the fold.
- 3 to 5 projects, each with a one-to-three-sentence description and real screenshots or video.
- Single-column layout, monochrome plus at most one accent color.
- A deliberate typeface, considered hover states, and at least one intentional transition.
- At least one builder signal: a live tool, experiment, open source, or a `/craft` or `/lab` page.
- None of the items in "Leave These Out" are present.
- `/portfolio-polish <your-url>` clears the v1 ship bar (every category at least 3 of 5), with the target bar of 4+ everywhere as the next week's goal.
- Live on a real custom domain over HTTPS, not a template URL.