Onder de motorkap: zo bouwen we onze website met Astro, Claude en skills

In een eerdere post vertelden we waarom we het CMS achter onze website hebben losgelaten. De korte versie: een AI-agent bleek een betere content manager dan wijzelf ooit waren. Dat verhaal ging over het waarom. Deze gaat over het hoe.

Want een agent die “gewoon” je website aanpast klinkt als magie. In de praktijk is het vooral een kwestie van de juiste fundering, de juiste context en een paar slimme herhaalbare recepten. Tijd voor een kijkje onder de motorkap.

De fundering: Astro en platte bestanden

Onze website draait op Astro, een modern framework dat tijdens het bouwen alles platslaat tot statische HTML. Geen database, geen query-laag, geen draaiende server die per bezoeker pagina’s in elkaar zet. De bezoeker krijgt kant-en-klare pagina’s geserveerd — razendsnel en nauwelijks stuk te krijgen.

Het mooie zit hem in waar de content leeft. Onze blogposts, cases en vacatures zijn gewoon Markdown-bestanden die naast de code staan. Een blogpost is een tekstbestand met wat frontmatter bovenaan; geen verborgen velden in een admin-omgeving.

Daardoor ziet een AI-agent precies hetzelfde als wij: de teksten én de code die ze tot een pagina maakt. Er is geen onzichtbare laag waar de agent omheen moet werken. Dat is precies wat het samenwerken met een agent zo soepel maakt.

De context: ons instructiebestand

Een agent die de codebase ziet, weet daarmee nog niet hoe wíj werken. Waar horen blogposts? Hoe regelen we Nederlands en Engels? Welke kleuren zijn van het merk? Zonder die kennis verzint een model iets plausibels — en dat is precies wat je niet wilt.

Daarom houden we een instructiebestand bij in de repository. In de praktijk staat dit bekend als de CLAUDE.md of AGENTS.md: een leesbaar document dat de agent als eerste meekrijgt. Het beschrijft de mappenstructuur, onze conventies en de valkuilen die we eerder zelf zijn tegengekomen.

Daarin leggen we bijvoorbeeld vast dat content in Markdown hoort en niet in losse tekstvelden in de code. Dat Nederlands op de hoofd-URL staat en Engels onder /en/. En dat afbeeldingen geïmporteerd moeten worden zodat Astro ze kan optimaliseren.

Het is in feite een onboarding-document, maar dan voor een AI-collega. Elke keer dat we tegen een nieuwe valkuil aanlopen, voegen we een regel toe. Zo wordt de agent met elke iteratie een stukje beter ingewerkt op precies ónze manier van werken.

Het recept: een skill voor blogposts

De laatste laag is de leukste: skills. Een skill is een herbruikbaar recept dat we de agent meegeven voor een terugkerende taak. In plaats van elke keer opnieuw uit te leggen hoe een blogpost eruit moet zien, beschrijven we dat één keer goed.

Deze post is daar zelf het bewijs van. We hebben een write-blog-post-skill die precies weet welke stappen nodig zijn: hij leest eerst de twee meest recente posts om de toon te pakken te krijgen, bepaalt de juiste slugs en metadata, en schrijft daarna zowel de Nederlandse als de Engelse versie.

Daarna maakt de skill de map voor de afbeeldingen aan en genereert hij twee zorgvuldige prompts voor onze illustraties — de aquarel-pinguïns die je bij elke post ziet. Tot slot loopt hij een checklist af zodat we zeker weten dat alle bestanden kloppen.

Het resultaat is consistentie zonder gedoe. Geen vergeten Engelse vertaling, geen scheve frontmatter, geen post zonder illustratie. De saaie maar belangrijke details zijn vastgelegd, zodat wij ons op het verhaal kunnen richten.

Waarom deze drie samen werken

Astro, het instructiebestand en de skills versterken elkaar. Astro zorgt dat content en code in dezelfde wereld leven. Het instructiebestand geeft de agent het besef van hoe die wereld in elkaar zit. En de skills maken het terugkerende werk herhaalbaar en betrouwbaar.

Samen veranderen ze het werk van klikken in een CMS naar beschrijven wat we willen. De agent zet een Pull Request klaar, wij lezen de preview en de code na, en bij akkoord gaat het live.

We breiden dit recept stap voor stap uit — naar cases, vacatures en pagina’s. Wil je weten hoe dit voor jouw organisatie zou werken? We vertellen er graag meer over.

(Disclaimer: we gebruikten AI om dit artikel te schrijven en lekker leesbaar te maken. Maar de inhoud en de ervaringen komen voort uit de hersens van onze eigen Spinguins.)