incomestreamsurfer/astro-builder-skill/skill
Claude Code and agent skill by incomestreamsurfer/astro-builder-skill
- community
Checking that the SKILL.md file is still in the repository.
Build complete, SEO-optimized websites using Astro with Tailwind CSS, content collections, and optional Turso database. Use this skill whenever the user wants to create a website, build a site that ranks on Google, start an Astro project, make a landing page, build a business website, create a blog, or any web project where SEO matters. Also trigger when the user mentions Astro or wants a site built with modern web tech. Even if they just say 'build me a website' or 'I need a site for my business' — this skill handles it.
Install
npx vskill@latest install incomestreamsurfer/astro-builder-skill/skillSKILL.md
The same SKILL.md was published earlier as incomestreamsurfer/astro-builder-skill/skill.
Astro SEO Website Builder
You build complete, deployment-ready websites in Astro that are engineered to rank on Google. Every site ships with proper meta tags, structured data, semantic HTML, optimized images, sitemaps, and real researched content — not placeholder text.
Every frontend you produce must be premium and non-generic. Read references/taste-skill.md before writing any UI code — it contains the design rules that prevent generic "AI slop" output.
Tech Stack
- Astro — Static-first framework, zero JS by default, perfect for SEO
- React — Interactive components via Astro islands (forms, nav, animations)
- Tailwind CSS — All styling. No shadcn defaults — customize everything per the taste-skill rules
- Astro Content Collections — Type-safe Markdown/MDX content for blog posts, services, testimonials
- Turso + Drizzle — Edge SQLite database (optional, for forms/dynamic data)
Workflow Overview
Every project follows this sequence. Don't skip steps.
Phase 1: Discovery & Research
- Ask the user about their niche, business, and goals
- Ask if they need a database (for contact forms, leads, bookings, etc.)
- Research the niche — what's ranking, what keywords matter, what content gaps exist
- Propose a site structure with page list, content strategy, and keyword targets
- Get user approval before building
Phase 2: Project Setup
- Scaffold the Astro project
- Install and configure integrations (React, Tailwind, sitemap)
- Set up the base layout, SEO components, and design system
Phase 3: Build Every Page
- Read
references/taste-skill.mdfor design rules - If user wants generated images, read
references/image-generation.mdand generate images for each page - Create each page with real, researched content
- Full SEO on every page — meta tags, OG tags, structured data, semantic HTML
- Wire up interactive components (forms, navigation, etc.)
Phase 4: Content Collections & Database
- Configure Astro content collections for blog posts, services, etc.
- If database requested: set up Turso, create schemas, build API routes
- Build admin dashboard for database data if applicable
Phase 5: Deployment Prep
- Generate sitemap, robots.txt
- Configure deployment (Vercel/Netlify)
- Final SEO audit of every page
Phase 1: Discovery & Research
Ask the User
Before writing any code, understand the project:
- What's your niche/business? — "I'm a plumber in Dublin" or "I sell handmade candles online"
- What's the site's primary goal? — Lead generation, e-commerce, portfolio, blog, SaaS landing page
- How many pages do you want? — Small (5-10 pages) or content-heavy (15-30+ pages with blog)
- Do you need a database? — For storing form submissions, bookings, user data, etc. If yes, set up Turso.
- Do you want generated images? — "I can generate custom stock images for your site using Gemini. If you'd like this, add your
GEMINI_API_KEYto the.envfile." - Do you have a domain? — Needed for sitemap/canonical URLs. Use a placeholder if not yet purchased.
- Any design preferences? — Colors, style, existing branding
Research the Niche
Use web search to find:
- What's currently ranking for the target keywords — top 5-10 results
- Content gaps — what questions aren't being answered well
- Long-tail keywords — specific phrases with less competition
- Local SEO signals if it's a local business
- Competitor site structures — what pages they have, what they're missing
Propose the Site Structure
Based on research, create a concrete proposal. Example for a plumber:
Get the user's sign-off before proceeding.
Phase 2: Project Setup
Read references/astro-setup.md for exact commands and configuration.
1. Create the Project
2. Install Integrations
3. If Database Requested
Read references/turso-setup.md for full Turso configuration.
4. Project Structure
Phase 3: Build Every Page — Design + SEO
Before writing any page, read both:
references/seo-checklist.md— SEO rules for every pagereferences/taste-skill.md— Design rules to prevent generic output
The SEOHead Component
Create src/components/SEOHead.astro — goes in <head> of every page. Handles:
- Title tag (unique per page, primary keyword, under 60 chars)
- Meta description (unique, CTA, under 160 chars)
- Canonical URL
- Open Graph tags
- Twitter Card tags
- JSON-LD structured data
See references/seo-checklist.md for the exact component code.
Content Writing Rules
- Write for humans first, search engines second.
- Every page targets a specific keyword cluster. Primary keyword in title, H1, first paragraph, meta description, URL slug.
- Proper heading hierarchy. One H1. H2s for sections. H3s for subsections. Never skip levels.
- Internal linking. Every page links to 2-3+ other pages. Descriptive anchor text.
- Image alt text. Every image gets descriptive alt text with natural keywords.
- Content length. Service pages: 800-1500 words. Blog posts: 1500-3000 words. Home: 500-1000 words.
- Schema markup. Every page gets appropriate JSON-LD.
Design Rules (from taste-skill)
These are non-negotiable for every page you build:
- Typography: Use Geist, Satoshi, Outfit, or Cabinet Grotesk. NEVER Inter. Headlines:
text-4xl md:text-6xl tracking-tighter leading-none. - Colors: Max 1 accent color, saturation < 80%. No purple/blue AI gradients. Neutral bases (Zinc/Slate).
- Layout: No centered hero when DESIGN_VARIANCE > 4. Use split-screen, asymmetric, or left-aligned layouts.
- Cards: Only when elevation communicates hierarchy. No generic 3-column card layouts.
- Spacing:
min-h-[100dvh]noth-screen. Grid not flexbox math.max-w-7xl mx-auto. - States: Every interactive component needs loading, empty, and error states.
- No AI slop: No emojis, no "John Doe", no "Acme Corp", no filler words like "seamless" or "unleash".
Astro Islands for Interactivity
- Static content (headings, text, images) —
.astrocomponents, zero JS - Interactive elements (forms, mobile nav, scroll animations) — React
.tsxwithclient:visibleorclient:load - Animations: For motion (MOTION_INTENSITY > 5), use Framer Motion in isolated React islands. Spring physics:
type: "spring", stiffness: 100, damping: 20.
Read references/tailwind-components.md for component patterns (nav, forms, FAQ, etc.)
Phase 4: Content Collections & Database
Astro Content Collections
Read references/content-collections.md for the full setup. Content collections replace a CMS — content lives as Markdown files in src/content/ with type-safe schemas.
IMPORTANT: Define schemas in src/content.config.ts (NOT src/content/config.ts — the old path throws LegacyContentConfigError in Astro v5+). Every collection must have a loader (use glob() from astro/loaders).
Define schemas in src/content.config.ts:
- Blog posts: title, description, pubDate, image, tags, author, draft
- Services: title, description, icon, order, featured
- Testimonials: name, role, quote, rating
Query collections in pages with getCollection() and getEntry().
Turso Database (If Requested)
Read references/turso-setup.md for complete setup. Turso handles dynamic data — form submissions, leads, bookings, newsletter signups.
- Create the database client in
src/lib/turso.ts - Define schemas with Drizzle ORM
- Create API routes in
src/pages/api/for form handling - Build an admin dashboard to view submitted data
Admin Dashboard (If Database)
Build at /admin using React islands with Tailwind-styled tables and cards. Uses:
- Middleware for basic auth
- API routes to fetch data from Turso
- Clean, tasteful data presentation (per taste-skill rules — no generic card grids)
Phase 5: Deployment Prep
Sitemap & Robots.txt
@astrojs/sitemap auto-generates the sitemap. Set site in astro.config.mjs.
Dynamic robots.txt at src/pages/robots.txt.ts:
Deployment Configuration
Read references/deployment.md for Vercel/Netlify configs.
For sites with API routes or Turso, add an adapter but keep the default static output. Mark individual server routes with export const prerender = false;:
In each API route or server-rendered page:
Final SEO Audit
Audit every page against references/seo-checklist.md:
- Unique title, description, canonical URL per page
- All images have alt text
- JSON-LD validates
- Internal links work
- Mobile responsive (test taste-skill mobile override rules)
- Sitemap includes all pages
- robots.txt correct
Important Notes
This is the start of the file. Read the full SKILL.md on GitHub.
Security
- Security scanPassed, 95 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskill/SKILL.md
Popularity
- Repository stars
- 75
- Repository forks
- 35
- 7-day trend score
- 22
Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/incomestreamsurfer/astro-builder-skill/skill)