Creating my portfolio website using GitHub's Spec-kit

For a long time I have wanted to create my own website portfolio. After many failed attempts of trying to write something that looked vaguely good, I read a couple of articles on GitHub's spec-kit and decided to give it a go, the full result can be found at repository, with the site hosted on github pages at portfolio

Spec-kit offers a framework and guideline for your AI tool of choice (many are supported) to build an application.

Prerequisites

Spec-kit is a command line interface tool built in python, and the following should be installed prior to installing the cli tool.

• Python




• Python package uv

Install

I chose to install the cli tool persistently using the command uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

Creating the project

I did not make the project folder prior, so I navigated to the path were I wanted to create my project folder and used the command specify init

I then got the option to select your AI assistant

I then got the option to define what terminal type to use

The initialisation will run, and hopefully all stages will be green. I have never had this fail before, but hopefully any error message would be easy to resolve

Following that some guidance on what next steps you may want to take is given, note that the project with be initialised with git too.

Developing the application

The first thing I did was to create the constitution.md, this creates the principles and guidance that all future development steps will follow. Mine is pretty simple I stated that this must be a static website only, and must not capture any user data. This can be created using the command /speckit.constitution

I then did four cycles of the specify workflow, the first two I did in December 2025 using Gemini, the second two I did using Claude in February 2026. Specify workflows can be created using /speckit.specify and will be numbered in your repository like

, then the flow is

1. 
   /speckit.plan to supply your plan for what you want for this feature, you can mention tech and any architecture choices


2. 
   /speckit.tasks to create a list tasks the AI will action


3. 
   /speckit.implement to action those tasks, these will then be checked against and create a checklists/requirements.md of what was checked inside each folder.

In between these four feature additions using Spec-kit I edited the content and removed some things I did not like manually. Then at the end I asked the AI to assess the final result against the specs, it detailed four attributes of the website that didn't fit into the specs, rather than change these we documented them in decision record files within the repository.

Conclusion

Using Spec-kit I was able to get a good looking (I think) responsive static website far quicker than I would have been able to without it.

It created detailed markdown files detailing the thought process, how it was going to build the site, what content it would generate, and what technology would be used. I am excited to see what can be built on larger projects.