start-astro

name	start-astro
description	Scaffold a new Astro project (minimal template) with a ready-to-use Basic architecture — header navigation (Home/Work/Contact) with a logo + centered nav, light/dark theme toggle (zero deps, CSS vars + vanilla JS), and native Astro View Transitions for smooth page-to-page fades. Use when starting, creating, or bootstrapping a new Astro site/project/"proyecto astro" from scratch, or when the user wants a base/starter with theme switching and a header already wired up. Generates the project via `bun create astro@latest` with the minimal/empty template, then writes the layout, header, global theme CSS/script, and all three pages, installs, and verifies the dev build.
license	Complete terms in LICENSE.txt
metadata	{"author":"bastndev","version":"1.0.0"}

start-astro

Scaffolds a publishable Astro Basic starter: clean minimal template as the base, then a hand-written Layout + Header + 4 pages + light/dark toggle + View Transitions on top — the stuff you configure every single time you start an Astro project, done once, correctly.

When to use

The user wants to start a new Astro project: "create/scaffold/bootstrap a new astro project", "set up an astro site", "necesito un proyecto de astro listo", or they have an empty folder and want the base files with theme switching and navigation already working.

---

Why minimal, not basic

bun create astro@latest offers four templates. This skill always picks "Use minimal (empty) template", not "A basic, helpful starter project (recommended)".

Why: the "basic" template ships its own boilerplate page, default styles, and an Astro logo/welcome component that would all need to be located and deleted before our Header/Layout/theme code can go in cleanly. That's an extra, error-prone step that also drifts depending on whatever Astro bundled in that release. minimal gives an empty src/pages/index.astro and nothing else — everything this skill adds is therefore exactly what's in references/, no leftover files, no guessing what to delete.

---

Procedure

1. Gather inputs:

   • PROJECT_NAME — the user already created and named their folder before invoking this skill. Detect it automatically from the current working directory (pwd / the basename of the folder Claude is operating in) and use it as-is — never ask the user to name the project, and never request a name in chat. The folder's existing name (e.g. TEST1) is the project name, exactly as the user typed it (preserve its original casing — don't lowercase/slugify it).
   • DIR — always . (the current directory). This skill scaffolds into the folder the user is already standing in; it does not create a new sibling folder and does not rename anything.
   • PAGES — default Home, Work, Contact (the standard set this skill ships). Only deviate if the user explicitly asks for different sections.

2. Scaffold via the official CLI, into the current folder — the user already made and is standing inside their project folder (e.g. TEST1), so this always targets ., never a new named folder:

   bun create astro@latest . -- --template minimal --no-install --no-git --skip-houston
   

   • . → scaffold into the current directory; this skill never creates a new folder or renames the existing one.
   • Never create a separate, temporary, or differently-named project folder (e.g. test-project1, astro-scaffold, a /tmp copy, a sibling dir) to scaffold or "test" in and then move/delete. There is exactly one project and it is the current folder. Run every command — scaffold, install, build — directly here. (If you've seen a folder briefly appear and vanish, that's this anti-pattern; do not do it.)
   • --template minimal → the empty template (see rationale above).
   • --no-install → this skill controls the install step explicitly (next step), keeps output readable.
   • --no-git → don't assume the user wants a fresh git repo; skip unless asked.
   • --skip-houston → skip the mascot/animation prompt, keep it non-interactive.
   • If any flag is rejected by the installed create-astro version, fall back to running it without flags and answer the interactive prompts yourself: → (current folder), → minimal/empty, decline TypeScript strictness prompts with the default, decline git init, decline install.

---

Gotchas checklist (verify before declaring done)

• Project name was detected from the current folder's name — never asked the user, never invented a separate name
• Used minimal template, not basic — no boilerplate to clean up
• Theme toggle script runs on astro:page-load, not only on initial DOMContentLoaded — otherwise it breaks after the first View Transition (bundled module scripts only execute once; see references/theme-toggle.md)
• Inline "no-flash" script in <head> reads the saved theme before first paint (no light-flash on dark-mode reload) and re-applies it on astro:after-swap — without the after-swap re-apply, navigating between pages strips <html data-theme> (the incoming server HTML has none) and the site flips dark→light on every nav click
• <ClientRouter /> imported from astro:transitions and placed in Layout.astro's <head>
• All 3 pages (Home/Work/Contact) use the same Layout.astro + Header.astro
• Every page renders the shared GXB.astro (centered ASCII logo + a per-page tagline); the ASCII art lives in one file (GXB.astro), not duplicated into each page
• public/favicon.svg and public/favicon.ico are the untouched Astro defaults — the skill never overwrites the favicon with a custom logo and never deletes the .ico (the header logo only references favicon.svg read-only)
• Architecture.md written to the project root from references/architecture.md
• bun install and bun run build both pass before reporting done
• Zero runtime dependencies added for the theme toggle (CSS vars + vanilla JS only — no package installed for this)