Frontend · Skill

Build an Astro site

build-astro-site

Builds a content site with Astro and TypeScript - pages and layouts, Markdown or MDX content collections with a typed schema, interactive islands only where needed, Tailwind styling, images and SEO basics, then a static or server build. Use when the user wants a blog, docs, marketing or portfolio site with Astro, or asks about islands or content collections.

Works with: Any AI Not yet model-tested; testing Jan 2027

View raw SKILL.mdInstall

Paste it into ChatGPT, Claude, Gemini or any AI chat, then tell it about your project. How it works

Install in Claude Code, Cursor or Codex (optional)

Only for AI coding tools that read skill folders. Run one line in a terminal, in your project folder. It downloads this skill's text files from TheSkillVault and nothing else; you can read them first with “View raw SKILL.md”.

Claude Code (all your projects)

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/build-astro-site/raw' -o ~/'.claude/skills/build-astro-site/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/build-astro-site/files/LICENSE.txt' -o ~/'.claude/skills/build-astro-site/LICENSE.txt'

Cursor (this project)

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/build-astro-site/raw' -o '.cursor/skills/build-astro-site/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/build-astro-site/files/LICENSE.txt' -o '.cursor/skills/build-astro-site/LICENSE.txt'

Codex and other Agent Skills tools (this project)

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/build-astro-site/raw' -o '.agents/skills/build-astro-site/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/build-astro-site/files/LICENSE.txt' -o '.agents/skills/build-astro-site/LICENSE.txt'

Or connect the whole library over MCP

Add TheSkillVault to Cursor or add this to your app's MCP settings (read-only; help):

{
  "mcpServers": {
    "theskillvault": {
      "url": "https://theskillvault.ai/mcp"
    }
  }
}

Astro ships plain HTML by default and adds JavaScript only to the parts that need it. That makes content sites fast with little effort.

When to use

  • You are building a blog, docs, portfolio or marketing site.
  • Page speed and SEO matter more than app-like interactivity.
  • You want to write content in Markdown or MDX.

When not to use

  • You are building a logged-in app with lots of interactive screens. A full app framework such as Next.js or SvelteKit fits better.

Steps

  1. Create the site: npm create astro@latest, choose TypeScript (strict), then npm run dev.
  2. Add pages as .astro files in src/pages; src/pages/about.astro becomes /about.
  3. Make a shared layout in src/layouts with the <head>, title and meta description as props.
  4. Put posts in a content collection (src/content/blog) and define a typed schema with defineCollection and Zod in the content config.
  5. List and render posts with getCollection and dynamic routes such as src/pages/blog/[slug].astro.
  6. Add interactive parts as islands: a React, Svelte or Vue component with client:visible or client:load. Leave everything else static.
  7. Add Tailwind with npx astro add tailwind, and use Astro's <Image /> for optimised images.
  8. Add the sitemap integration and an RSS feed, and set the site URL in the Astro config.
  9. Build with npm run build. Static output deploys anywhere; add an adapter only if you need server rendering.
---
import { getCollection } from "astro:content";
import Layout from "../layouts/Layout.astro";
const posts = (await getCollection("blog")).sort((a, b) => +b.data.date - +a.data.date);
---
<Layout title="Blog" description="Notes and guides">
  {posts.map((p) => <a href={`/blog/${p.id}/`}>{p.data.title}</a>)}
</Layout>

Gotchas

  • Code in the --- frontmatter runs at build or on the server; it never reaches the browser. Still, keep secrets in non-public env vars, as PUBLIC_ values are exposed.
  • Forgetting a client: directive makes a component render as static HTML with no interactivity.
  • client:load everywhere throws away Astro's speed advantage. Prefer client:visible or client:idle.
  • Set the site config, or canonical URLs and the sitemap will be wrong.

Portability

Static builds deploy to Vercel, Netlify, Cloudflare Pages or GitHub Pages. If you use React, Svelte or Vue components, Astro supports all of them as islands.

Example prompt

"Build an Astro blog with TypeScript, a typed content collection for posts, Tailwind, a sitemap and an RSS feed."

Done when

  • Pages build as static HTML and only island components ship JavaScript.
  • Posts come from a typed content collection.
  • The sitemap and RSS feed list every post, and npm run build passes.

---

Based on the Astro TypeScript rules file in PatrickJS/awesome-cursorrules (CC0 1.0, public domain). See LICENSE.txt.

Bundled files

Licence

Adapted from awesome-cursorrules contributors (astro-typescript rules) (Public domain (CC0 1.0) - rules contributed to PatrickJS/awesome-cursorrules), CC0 1.0. Adapted by TheSkillVault: turned a JSON rules file into a build order with original examples; dropped commit-message and editor rules; added content collections, SEO, safety notes, gotchas, portability and done-when.

Licence: CC0 1.0. Attribution when you reuse it: Based on work by awesome-cursorrules contributors (astro-typescript rules) (Public domain (CC0 1.0) - rules contributed to PatrickJS/awesome-cursorrules, CC0 1.0), https://github.com/PatrickJS/awesome-cursorrules/blob/b044f956f021b6e8877f16781bcfc466a6a120e9/rules/astro-typescript-cursorrules-prompt-file.mdc; adapted by TheSkillVault, https://theskillvault.ai