Under the hood: how we build our website with Astro, Claude and skills

In an earlier post we explained why we let go of the CMS behind our website. The short version: an AI agent turned out to be a better content manager than we ever were ourselves. That story was about the why. This one is about the how.

Because an agent that “just” edits your website sounds like magic. In practice it is mostly a matter of the right foundation, the right context, and a few clever repeatable recipes. Time for a look under the hood.

The foundation: Astro and flat files

Our website runs on Astro, a modern framework that flattens everything into static HTML at build time. No database, no query layer, no running server assembling pages per visitor. Visitors get ready-made pages served to them — blazing fast and almost impossible to break.

The beauty is in where the content lives. Our blog posts, cases and job openings are simply Markdown files that sit next to the code. A blog post is a text file with a bit of frontmatter at the top; no hidden fields in an admin panel.

As a result, an AI agent sees exactly what we see: the text and the code that turns it into a page. There is no invisible layer the agent has to work around. That is precisely what makes collaborating with an agent so smooth.

The context: our instructions file

An agent that sees the codebase still does not know how we work. Where do blog posts belong? How do we handle Dutch and English? Which colours belong to the brand? Without that knowledge a model invents something plausible — and that is exactly what you do not want.

That is why we keep an instructions file in the repository. In practice this is known as the CLAUDE.md or AGENTS.md: a readable document the agent receives first. It describes the folder structure, our conventions, and the pitfalls we have run into ourselves.

In it we note, for example, that content belongs in Markdown and not in loose text fields in the code. That Dutch lives on the main URL and English under /en/. And that images must be imported so Astro can optimise them.

It is essentially an onboarding document, but for an AI colleague. Every time we hit a new pitfall, we add a line. So with each iteration the agent gets a little better trained in exactly our way of working.

The recipe: a skill for blog posts

The final layer is the most fun: skills. A skill is a reusable recipe we hand the agent for a recurring task. Instead of explaining every time what a blog post should look like, we describe it properly once.

This post is proof of that itself. We have a write-blog-post skill that knows exactly which steps are needed: it first reads the two most recent posts to capture the tone, determines the right slugs and metadata, and then writes both the Dutch and the English version.

After that the skill creates the directory for the images and generates two carefully crafted prompts for our illustrations — the watercolour penguins you see with every post. Finally it runs through a checklist so we know for sure that all files are correct.

The result is consistency without the hassle. No forgotten English translation, no skewed frontmatter, no post without an illustration. The boring but important details are captured, so we can focus on the story.

Why these three work together

Astro, the instructions file and the skills reinforce one another. Astro keeps content and code in the same world. The instructions file gives the agent an awareness of how that world fits together. And the skills make recurring work repeatable and reliable.

Together they turn the job from clicking around in a CMS into describing what we want. The agent prepares a Pull Request, we review the preview and the code, and once approved it goes live.

We are expanding this recipe step by step — to cases, job openings and pages. Curious how this would work for your organisation? We would love to tell you more.

(Disclaimer: we used AI to write this article and make it an engaging read. But the core concepts and experiences come straight from the minds of our own Spinguins.)