The four building blocks #
Every AI Website Template consists of four parts. One of them becomes visible in the browser later, the other three work in the background and turn your AI into someone who knows this project.
The finished website
All pages, texts, images, fonts and the complete design, light and dark. This is the part visitors see. It is complete: you swap content instead of building a website.
The guideline CLAUDE.md
A single text file in the main folder. It explains to your AI how this project is built, which rules apply and what it must never do. Your AI reads it on its own as soon as you open the folder.
The knowledge folder Wissen
Four reference texts about the industry of your template: audience, tone of voice, the blueprint of the building blocks and the search strategy. In English-language templates the folder is called Knowledge.
Seven skills under .claude/skills/
Seven playbooks for the tasks that always come back: set up, rebuild, write, design, prepare for search, look things up and check. They kick in on their own when your sentence matches the task.
.claude Folders whose name starts with a dot are hidden by default on Windows and macOS. So the folder is not missing. In Windows Explorer you switch them on under View and Hidden items, in Finder with the key combination of Command, Shift and dot. In your AI editor it is visible anyway.
The folder tree, annotated #
Most templates are built with Astro. You recognise them by a folder called src and a file called package.json in the main folder. This is what such a template looks like, with half a sentence on every entry.
- src/ · everything the website is built from
- src/pages/ · one file per page, the file name becomes the address
- src/components/ · recurring blocks such as header, footer and cards
- src/layouts/ · the shell that wraps every page
- src/data/ · your texts: contact, navigation, services, numbers, FAQ
- src/styles/global.css · colours, fonts and spacing as tokens
- public/ · images, fonts and icons, they go onto the server 1:1
- astro.config.mjs · your domain and the basic settings
- package.json · the list of parts that npm install fetches
- styleguide.html · the design system to look at in your browser
- START-HIER.md · the short guide for your first day
- CLAUDE.md · the guideline for your AI
- Wissen/ · audience, tone, blueprint and search strategy
- .claude/skills/ · the seven playbooks
You will need three of these entries often, the rest you rarely see. Your content lives in src/data/, under src/pages/ there is one file per page, and src/styles/global.css holds every colour and font in one block at the top. For everything else: your AI finds the place faster than you can look for it.
Two folders appear only later and are in no tree, because they are generated. node_modules appears with npm install and holds the parts that were fetched. dist appears with npm run build and holds the finished pages for the server. You may delete both at any time, the next command creates them again.
src/pages/kontakt.astro becomes the address /kontakt/, src/pages/blog/mein-beitrag.astro becomes /blog/mein-beitrag/. Renaming a page changes its address, and the links pointing to it have to follow. Your AI does that in one go if you say so.
The template without a build step #
Some templates come without a build step. You recognise them by an index.html right in the main folder and by the fact that there is no src. They are plain HTML, CSS and JavaScript. What you see in the files is 1:1 what will later sit on the server.
- index.html · the home page, sits at the very top
- ueber-mich/index.html · one folder per page, the folder name becomes the address
- blog/name-of-the-post/index.html · one folder per post
- assets/css/ · the stylesheet, with the token block at the top
- assets/js/ · navigation, reveals, consent dialogue
- assets/img/ · all images
- api/ · sending the forms, works only on the server
- .htaccess · addresses without file endings, redirects, caching
- sitemap.xml · the overview of all pages for search engines
- CLAUDE.md · Wissen/ · .claude/skills/ · styleguide.html · the same role as above
The upside is obvious: no npm install, no build, no waiting. The files go onto the server exactly as they are. For the preview you still need a small local server, because the addresses work without file endings. Double clicking the file is not enough for that.
Without a build step there is no shared shell: navigation, footer and consent dialogue sit as a copy in every single HTML file. If you change one menu item, the change has to go into all files. So always tell your AI to carry the change across all pages. This is exactly the task where doing it by hand gets expensive and one sentence in chat is cheap.
The iron rule: one place per thing #
Your template follows two rules that hold everything together. They sound technical and are in truth the reason why a change takes you five minutes instead of five hours.
Texts live in src/data/, not in the building blocks
Everything that shows up in several places is stored exactly once: name, phone, address, opening hours, navigation, services, prices, numbers, testimonials and FAQ live in src/data/site.ts. The pages pull these values from there. You change the phone number in that one place and it changes in the header, in the footer, on the contact page and in the machine readable data for Google as well.
Anything that appears on one single page only, such as the career story on the about page, lives at the top of that page's file. So the order in which you look is always the same: src/data/ first, then the page. In the template without a build step that central file does not exist, there the text sits in the respective index.html.
Colours live in the token block, not in single pages
Every colour, every font and every corner radius is stored as a named value in one place. In the Astro template that is the block at the top of src/styles/global.css, in the static template the :root block in assets/css/style.css. No single page contains a colour value. Dark mode is built from the same values as well, only with different assignments.
That means: you change your brand colour in one place and the whole website follows, buttons, links, icons, borders and dark mode included. How to do that cleanly is in the chapter Adjusting the design.
Writing a colour straight into a page looks right at first and then breaks in dark mode or on the next page. The same goes for texts that end up in a page instead of in src/data/: later they no longer change along with the rest. If your AI suggests solving something in a single spot, tell it to take the route through the tokens or the data source.
CLAUDE.md, the memory of the project #
The file CLAUDE.md in the main folder is the most important file of your template, even though no visitor ever gets to see it. It is a letter to your AI. Every AI that opens this folder reads it first and knows afterwards where it is.
Without this file your AI would guess at every task. With it, it knows. Here is what is written in it:
- What the project is. Which industry, which fictional person is in place on delivery and that all numbers and testimonials are placeholders.
- The design rule. Which surfaces, which single accent, which typeface. And that there is no second accent.
- Where content lives. Which file feeds which section, so the AI does not search in the wrong corner.
- How the website speaks. Formal or informal address, sentence length, forbidden words, attitude.
- What must never be done. No made up legal texts, no invented proof, no external font services, never fix dark mode in single spots.
- Which commands exist. Start the preview, build, and what has to run without errors after a change.
The guideline has to grow with you
This is the point where most projects slowly get worse. You rebuild the website: new pages, new colour, new services, a connected form. Afterwards the guideline describes a state that no longer exists. In the next session your AI reads that old state and works against your new website. It looks for texts in files you have moved and suggests a colour you replaced long ago.
So every larger change comes with a second step: bring the guideline along. That takes one sentence and saves you whole sessions later. Typical occasions are a new page, a changed brand colour, the replaced persona, a connected form or a section you removed.
We have rebuilt the website. Bring CLAUDE.md up to today's state: identity, colours, fonts, all pages, where which content lives and which rules apply now. Remove what is no longer true and show me the changes before you save.
Get into the habit of ending every round of work with one question: is CLAUDE.md still correct? Your AI then compares the text with what you have just changed and adds the differences. A maintained guideline is the difference between an AI that knows your project and one that starts from scratch every time.
The knowledge folder #
Next to the guideline sits the folder Wissen. The difference is simple: the guideline is the rule, the knowledge folder is the background. Rules are always read, background is read when a task gets bigger. Four files are in every template.
zielgruppe.md
Who this website has to convince. Who is searching, for what reason, with which worry, and what that person wants to see before getting in touch. This is the basis of every good headline. If you move into a different niche, this is the first file to have rewritten.
tone-of-voice.md
How the website speaks. Form of address, sentence length, vocabulary, what is off limits. Your AI sticks to this when it writes a new paragraph. That is why the twentieth text still sounds like the first.
komponenten-bauplan.md
Which block gets its data from where. A table that says for every section which entry it is built from. If you want to know what happens once you delete a service, the answer is here.
seo-strategie.md
Which search terms the template serves and which role every page plays in that: home page for the positioning including the city, service pages for the concrete enquiry, blog posts for the questions that come before. More on this in the chapter SEO and visibility.
Some templates add a little more, for instance a full project map, a list of frequent tasks or a guide to publishing. Take a look into the folder once so you know what is in there. You do not need to learn any of it by heart: it is enough that your AI reads it there.
The four texts describe the industry of the template, not yours. If you move into a neighbouring niche or address a different audience, have them rewritten. One sentence is enough: my audience is now these people, adapt zielgruppe.md and tone-of-voice.md accordingly.
The seven skills #
Under .claude/skills/ there are seven folders, each holding a guide for one kind of task. They are the reason why you do not have to memorise any manual: your AI picks up the matching playbook as soon as your sentence matches the task.
- start · walks you through a conversation in four rounds the first time
- template-aufbau · turns the template into your real website, step by step
- systemwissen · answers questions about the structure and names the file
- copywriting · writes texts in the voice of your website, not in the voice of the AI
- seo · titles, descriptions, city, services and new posts
- design-system · colours, logo, spacing and the complete handling of images
- qualitaetspruefung · checks after every change and before going live
What each skill can do exactly, when it kicks in on its own and with which sentence you call it deliberately is in the next chapter The seven skills.
The styleguide in your browser #
In the main folder sits styleguide.html. A double click is enough, no build, no server, no installation. The file shows you the design system of your website on a single page: the complete colour world in light and dark, all font sizes and the defining blocks such as buttons, cards and form fields.
The value shows on your first own change. Before you change a colour you can see here what depends on it. After the change you see the result in both modes side by side, without clicking through ten pages. When you change a value in the token block, have the styleguide follow, otherwise it will soon show something other than your website.
It is a working document, not a page of your website. In the Astro template it sits outside of public and therefore never ends up in the build. In the static template it is blocked and excluded from the upload. Leave it that way.
What does not belong on the server #
Part of your template is made for you and your AI, not for visitors. These files stay on your computer:
- All files ending in
.md, that isCLAUDE.md,START-HIER.md,README.mdand the image credits. - The folder
Wissenwith the four background texts. - The hidden folder
.claudewith the seven skills. - The file
styleguide.htmlalong with everything that exists only for the preview.
In the Astro template this takes care of itself. npm run build creates the folder dist, and only its contents go onto the server. In the static template you exclude these files when uploading. Your AI can write the list for you.
Tell me which files and folders in this project do not belong on the server, and turn that into an exclusion list for my upload. Give me the reason for every entry in one sentence.
None of this is dangerous if it does end up online once. For visitors these files are worthless, and they calmly describe how your website is built. Both are good reasons to leave them where they belong. The whole way onto the server is in the chapter Going live.
I want to change something, where do I look? #
This table is the core of the chapter. It answers the question that comes up most often at the beginning. On the left is what you want to change, in the middle the place in the Astro template, on the right the place in the template without a build step.
| What you want to change | Template with src | Template without a build step |
|---|---|---|
| Phone, email, address | src/data/site.ts, right at the top in the identity block | every index.html plus the machine readable data in the head of the home page |
| Menu items and their order | src/data/site.ts, the entry for the navigation | the header area in every HTML file |
| Text of a single page | the matching file under src/pages/ | the index.html in the folder of that page |
| Services, prices, FAQ, numbers | src/data/site.ts, one entry per section | the respective page, directly in the text |
| New blog post | a new file under src/pages/blog/ and one entry in src/data/blog.ts | a new folder under blog/, a card in the overview and one entry in sitemap.xml |
| Colours, fonts, spacing | the token block at the top of src/styles/global.css | the :root block in assets/css/style.css |
| Images | public/images/, the path then starts with a slash | assets/img/ |
| Title and description for Google | at the top of the respective file under src/pages/ | in the head of the respective HTML file |
| Imprint and privacy policy | src/pages/impressum.astro and src/pages/datenschutz.astro | impressum/index.html and datenschutz/index.html |
| Contact form and sending | the contact page under src/pages/, the sending gets connected | the form in kontakt/index.html and the files under api/ |
If your template is built differently in one place, that is written in its own CLAUDE.md. It always beats this table, because it describes your concrete template.
Ask your AI instead of searching #
You do not have to memorise any of this. For exactly these questions there is the skill systemwissen. It knows the structure of your project and answers with file and line instead of letting you search. The first sentence already pays off before you change anything.
Use the skill systemwissen and explain the structure of this project to me: which pages exist, where the texts live, where the colours are and where the images are. Name the file for every point and write it so that I understand it without prior knowledge.
And when you want to change one specific thing, ask for the map of that thing. Have the places shown to you first and decide afterwards. That way you see what will happen before it happens.
I want to change the phone number across the whole website. First show me every place it appears, with file and line, visible texts and machine readable data listed separately. Only change it once I have seen the list.
Four building blocks, two rules, one table. You do not need to know more about the structure. How to move each of these corners with a single sentence is in the chapter The seven skills.