antonsten-website

Structure and conventions for antonsten.com (Astro site). Use when creating new articles or blog posts, editing page content, fixing bugs, or understanding the file structure. Triggers on tasks involving MDX files, content collections, page layouts, components, or any work in this repository.

antonsten 0 Updated 3mo ago

GitHub

Install

npx skillscat add antonsten/claude

Install via the SkillsCat registry.

SKILL.md

antonsten.com Site Skill

Quick-reference for common tasks in this repo. For full technical details, see CLAUDE.md at the project root.

Creating a New Article

1. Create the file

Path: src/content/articles/YYYY-MM-DD-slug.mdx

The date prefix and slug must match the frontmatter. Example:

src/content/articles/2026-02-11-designing-for-clarity.mdx

2. Frontmatter template

---
slug: designing-for-clarity
title: Designing for clarity
description: A one-sentence summary that works as a meta description. Keep under 160 characters.
date: 2026-02-11T00:00:00.000Z
readingTime: 5
---

Required fields: slug, title, description, date, readingTime
Optional: image

Rules:

slug must match the filename slug exactly
date must use ISO format with T00:00:00.000Z
readingTime is estimated minutes (integer)
description is used for meta/OG — keep it concise and useful

3. Content conventions

Write in MDX (markdown with component support)
Articles are almost always text-only, no images
Use ## for section headers within articles, not #
Keep formatting minimal — prose over bullet points
No emojis in article content
For the rare image: use <MDXImage /> component, never raw <img> tags

4. After creating

Run npm run build to verify the article compiles
OG images can be generated with npm run generate-og-images
Meta description is auto-generated from the description frontmatter field via HtmlHead.astro

Key File Locations

Content

Articles: src/content/articles/*.mdx
Content schema: src/content/config.ts
Testimonials data: src/data/testimonials.ts

Pages (file-based routing → URLs)

Homepage: src/pages/index.astro
About: src/pages/about.astro
Work: src/pages/work.astro
Articles list: src/pages/articles/index.astro
Single article: src/pages/articles/[slug].astro
Case studies: src/pages/case/*.astro
Working together: src/pages/working-together.astro
Contact: src/pages/contact.astro
Newsletter: src/pages/newsletter.astro
Book: src/pages/books/products-people-actually-want.astro
API routes: src/pages/api/

Layouts

src/layouts/BaseLayout.astro — base HTML shell
src/layouts/BlogPost.astro — article pages
src/layouts/Layout.astro — general pages

Components

UI primitives: src/components/ui/
Navigation: src/components/Navigation.astro, LeftNavigation.astro
SEO: src/components/HtmlHead.astro (single source for all <head> metadata)
Images: src/components/OptimizedImage.astro, MDXImage.astro
Sections: src/components/CalloutSection.astro, BookCallout.astro
Forms: src/components/NewsletterForm.astro

Styling Rules

Tailwind CSS with custom theme
Fonts: "Suisse Intl" (sans), "Blanco" (serif)
Never use @apply
Never use !important
Dark mode: class-based, use the color tokens defined in CLAUDE.md
Spacing: 8px increments
Buttons: 4px rounded corners, no shadows, no icons

Common Tasks

Edit a page

Pages are in src/pages/. Find the .astro file matching the URL path. Pages use layouts from src/layouts/.

Edit an article

Find the MDX file in src/content/articles/ by date or slug. The slug in the filename matches the URL at /articles/[slug].

Add a testimonial

Edit src/data/testimonials.ts — testimonials are stored as typed data, not content collections.

Fix a component

Components are in src/components/. Check the component organization in CLAUDE.md for the full tree. All components use TypeScript props interfaces.

Debug build issues

Schema validation errors: check src/content/config.ts for required fields
Missing frontmatter: ensure all required fields are present (slug, title, description, date, readingTime)
CSS issues: check for @apply or !important usage (both forbidden)
Duplicate meta tags: all metadata must go through HtmlHead.astro only

Run dev server

npm run dev
# → http://localhost:4321

Deploy

Push to main. Netlify builds automatically.

antonsten-website

Install

antonsten.com Site Skill

Creating a New Article

1. Create the file

2. Frontmatter template

3. Content conventions

4. After creating

Key File Locations

Content

Pages (file-based routing → URLs)

Layouts

Components

Styling Rules

Common Tasks

Edit a page

Edit an article

Add a testimonial

Fix a component

Debug build issues

Run dev server

Deploy

Categories

Install

Recommended Skills