A portfolio is the one website where quality is the whole point. It has to load fast, look considered on a phone and show your best work in a way a client understands in seconds. The good news is that you no longer need to code it from scratch or pay for a custom build. With a template and an AI agent, you can have a real portfolio live in a weekend.

This guide walks through the full process. It uses the free Michael template, a designer portfolio built with Astro, as the example, but the steps work with any portfolio template.

Before you open any tool: prepare your content

The most common reason a portfolio feels weak is not the design. It is the content. AI can write sentences, but it cannot know which of your projects matter. Spend an hour on this first, and everything after goes faster.

Gather:

  • A short bio. Two to four sentences: what you do, who you do it for and one thing that sets you apart. Write it in your own words, even if it is rough.
  • Three to six projects. Fewer, better projects beat a long list. Choose the ones you would be proud to be hired for again.
  • For each project: the client or context, your role, the problem, what you did and the result. A number or a short quote helps if it is real.
  • Images. Good, large images for every project. Export them at the size they are shown, not the original file from your camera or design tool.
  • A real photo of you. It makes a portfolio personal, and it is the easiest part to replace.
  • Your contact details and links, such as email and the social profiles you actually use.

If you are missing something, write a note and keep going. You can fill the gaps later.

Step 1: Set up the template

You need two things on your computer: a recent version of Node.js and an AI agent that can work in a project folder, such as Claude Code, Codex or Cursor. Our guides cover the setup for Claude Code and Cursor.

  1. Download the template and unzip it.
  2. Open the folder in your AI tool.
  3. Ask the agent to install the dependencies and start the local site. The Michael template runs at http://127.0.0.1:4321 and requires Node.js 22.12 or newer.

Keep the page open in your browser. You will judge every change by looking at it.

Step 2: Let the AI learn the project

The template includes an AGENTS.md file that explains the project to AI tools: the pages, the folder structure and where to change things. Start with a read-only request:

Read AGENTS.md and the project structure. Explain which pages the portfolio has, where the text lives and where the images are. Do not change anything yet.

If the answer matches what you see in the browser, you are ready. If it does not, point the agent to the right file before you go on.

Step 3: Replace the personal details

Start with the parts that make the site yours, and work from the top of the page down.

Replace the hero headline and description with the text below. Keep the same length so the layout does not move.

Headline: [your headline]
Description: [your two-sentence bio]

Then do the About page, then the contact details. Check each change in the browser before the next. Keep your requests small: one section at a time.

Replace the photos. In the Michael template, the portraits are PNG files with fixed names, such as public/images/header/portrait.png for the home hero. If you replace a file and keep the same file name, the layout and crop stay the same, and no code needs to change. Ask the agent to list the files and sizes first.

List every image in the Home, About and Contact sections with its file path and display size. I will replace the portraits myself, using the same file names.

Step 4: Add your projects

In this template, each project’s detail page is generated from a Markdown file in src/content/works/. That is a useful structure: the text of a project lives in its own file with named fields, so you edit one project without touching the rest of the site.

Replace the content of work-01 with my project below. Keep the same sections and frontmatter fields. Use these image files, which I have placed in public/images/work-01/.

Client: [name]
My role: [role]
Problem: [one or two sentences]
What I did: [three or four sentences]
Result: [one sentence, with a number if it is true]

If you have fewer projects than the template has demo entries, ask the agent to remove the extra ones and update the Works page so it does not show empty cards. Run the build afterward to catch broken links.

How to write a case study that works

Clients skim. They want to know four things quickly, so structure every case study the same way:

  1. The problem. What did the client need?
  2. Your role. What exactly did you do, and what did others do?
  3. The process. Two or three decisions you made and why.
  4. The result. What changed? Use real numbers only. If you do not have numbers, describe the outcome plainly, such as “launched in six weeks and replaced their old site”.

Let the AI help with wording and keep your facts. A useful instruction is: “Tighten this to 120 words. Do not add any claims, numbers or names that are not in my text.”

Do not let the AI invent things

This is the mistake that costs the most trust. AI tools are happy to fill empty space with plausible details: invented clients, praise from people who never said it and results that never happened. On a portfolio, that is dangerous.

Add this to the instruction file or to your first message:

Never invent testimonials, client names, statistics, awards or social links. If information is missing, leave a clear TODO and ask me.

Remove any demo testimonials and reviews that came with the template, unless you replace them with real ones.

Step 5: Make it look right on every screen

Open the site at three widths: a large desktop, a tablet and a phone. Check that:

  • Text is easy to read and nothing overlaps
  • Images are sharp but not slow to load
  • Buttons are easy to tap
  • Your name and what you do are clear without scrolling

Many people first look at a portfolio on a phone, so this check matters more than it seems. If something is off, describe it exactly: “on a phone, the project cards touch the edge of the screen” gives the agent more to work with than “fix mobile”.

Step 6: Handle the SEO basics

A portfolio should be easy to find by your name and by what you do. You do not need to be an expert. Do these:

  • A unique title and description for every page, for example “Maria Costa | Brand designer in Porto”
  • Descriptive alt text on project images
  • A sitemap, and no leftover noindex tag
  • Your name in the main heading of the home page

We list everything in the SEO checklist for AI-built websites. Then connect Google Search Console and Bing Webmaster Tools and submit your sitemap, so the pages are indexed.

Step 7: Check the details before you publish

Run through this list. Every item should be true:

  • Every placeholder is replaced: names, emails, links and demo text.
  • Every link goes where you expect, and no link is still #.
  • The contact method works: send yourself a test message or check the email address.
  • All images are your own or licensed for your use.
  • The build runs without errors.
  • The site is clear and fast on your phone.

Also read the template’s license and the list of third-party assets so you know what you are allowed to use and what you need to credit.

Step 8: Publish it

A portfolio is a static site, so it is cheap and simple to host. Run the build command, then upload the generated site to a static host. Common options are Cloudflare, Netlify and Vercel, and each has a guide for Astro. After it is live, connect your own domain. A name like yourname.com looks more professional than a free subdomain, and it is easier to remember.

Test the live site, not only the local one. Check the pages, the images and the contact link once more.

Mistakes to avoid

  • Too many projects. Show your strongest work, not all of it.
  • Generic copy. “Passionate designer who loves creating beautiful experiences” says nothing. Say what you do and for whom.
  • Heavy images. Large, uncompressed files make the site slow and hurt both visitors and search.
  • No way to contact you. Put your email and one next step on every page.
  • Never updating it. Add your latest project every few months. An old portfolio suggests you are not working.

Add sections without redoing the design

Once the base is done, you may want a section the template does not have, such as a pricing table, a process timeline or a stronger call to action. The component prompts are made for that: you paste a prompt into your AI, say where the section goes and ask it to match the site’s fonts and colors. For help writing that request, read How to write AI prompts that build better websites.

Ready to start? Download the free Michael template, or browse the other Astro templates if you need a different style.