Astro - Advanced Developer

Comprehensive skill for building, configuring, and troubleshooting Astro projects. Use this skill whenever the user mentions Astro, .astro files, Astro confi...

Security Scan

This is an instruction-only Astro guidance skill whose requirements and instructions are consistent with its stated purpose and do not request unexpected credentials or install any code.

Purpose & Capability

The name/description match the included documentation and reference files: project setup, rendering modes, islands, SSR, deployment, SEO, troubleshooting. The skill requests no binaries, env vars, or installs — which is proportionate for a documentation-style skill.

Instruction Scope

SKILL.md and the references are documentation and code examples for Astro projects (commands like `npx astro add`, sample astro files, caching headers, API endpoints). They do not instruct the agent to read arbitrary host files, secrets, or to call external endpoints beyond examples. Note: the frontmatter trigger language is broad (will trigger on many Astro-related mentions and even some syntax patterns), so the skill may be invoked frequently in contexts that are only tangentially related.

Install Mechanism

No install spec and no code files that would be written/executed by an installer. Instruction-only skills have a minimal disk/execution footprint.

Credentials

The skill declares no required environment variables or credentials. The docs mention typical environment variables and deployment settings as examples (which is expected for this domain) but do not request access to any secrets.

Persistence & Privilege

Flags are standard (always: false, user-invocable: true, disable-model-invocation: false). It does not request permanent presence or system-level changes. Autonomous invocation is allowed but is the platform default; there are no additional privilege escalations.

Assessment

This skill is documentation-only and appears coherent with its stated purpose: it provides detailed guidance and examples for Astro projects and does not request credentials or install code. Before installing, consider: 1) provenance — the source/homepage is unknown; if you require trusted authorship, ask the publisher or prefer an official/established source; 2) operational behavior — the skill contains example commands (e.g., `npx astro add`) that, if the agent is allowed to execute shell commands, will modify your project and install packages; restrict execution permissions if you don't want automated package installs; 3) frequent activation — the skill's trigger rules are broad and may cause it to run in many contexts; if unwanted, prefer a narrower skill or disable autonomous invocation. If you want higher assurance, request the author identity, a license, or host provenance before installing.

Astro Advanced Skill

This skill provides production-grade guidance for Astro projects — from initial scaffolding through deployment, caching, and performance tuning. It covers the patterns that actually matter in real projects and the mistakes that actually happen.

How to use this skill

1. Read this file first for the core workflow and decision tree.
2. Consult the reference files in references/ for deep dives on specific topics:
   • references/setup-and-structure.md — Project creation, file structure, config, adapters
   • references/rendering-modes.md — SSG vs SSR vs Hybrid, when to use each, caching strategies
   • references/seo.md — Meta tags, Open Graph, JSON-LD, sitemaps, canonical URLs
   • references/islands-and-vue.md — Island architecture, client directives, Vue/React/Svelte integration
   • references/content-and-data.md — Content collections, data fetching, dynamic routes
   • references/deployment.md — Adapters, static hosts, serverless, environment variables
   • references/performance.md — Image optimization, bundle analysis, hydration control
   • references/troubleshooting.md — Common errors and fixes organized by symptom

Core decision tree

When helping with an Astro project, follow this sequence:

1. Identify the rendering strategy first

This is the single most important decision in any Astro project. Everything else flows from it.

• Pure static site (blog, docs, marketing)? → SSG (default). No adapter needed.
• Needs user-specific data, auth, or real-time content? → SSR with an adapter.
• Mostly static but a few dynamic pages? → Hybrid mode. Set output: 'static' in config and use export const prerender = false on dynamic pages.

2. Pick the right adapter

Only needed for SSR or hybrid:

• Vercel → @astrojs/vercel (serverless or edge)
• Netlify → @astrojs/netlify
• Cloudflare Pages → @astrojs/cloudflare
• Self-hosted Node → @astrojs/node (standalone or middleware)

3. Set up integrations

Add only what you need. Each integration is a potential build-time dependency:

# Common additions
npx astro add vue        # Vue islands
npx astro add tailwind   # Tailwind CSS
npx astro add mdx        # MDX support
npx astro add sitemap    # Auto sitemap generation

4. Establish content strategy

• Few pages, hand-authored → Regular .astro pages in /src/pages
• Blog/docs with structured content → Content collections with Zod schemas
• CMS-driven → Fetch at build time (SSG) or runtime (SSR)

5. Apply SEO from the start

Don't bolt it on later. See references/seo.md for the full pattern, but at minimum:

• Create a reusable <SEO> component for head tags
• Set up canonical URLs
• Add structured data (JSON-LD) for key pages
• Generate sitemap via @astrojs/sitemap

Key patterns to always follow

Layout pattern

Every page should use a layout. Layouts handle <html>, <head>, and shared chrome:

---
// src/layouts/Base.astro
import SEO from '../components/SEO.astro';
const { title, description } = Astro.props;
---
<html lang="en">
  <head>
    <SEO title={title} description={description} />
  </head>
  <body>
    <nav><!-- shared nav --></nav>
    <slot />
    <footer><!-- shared footer --></footer>
  </body>
</html>

Island pattern

Static by default. Only hydrate what needs interactivity:

<!-- Static: renders HTML, ships zero JS -->
<Card title="Hello" />

<!-- Interactive: hydrates on load -->
<Counter client:load />

<!-- Interactive: hydrates when visible (lazy) -->
<ImageGallery client:visible />

The #1 Astro mistake: forgetting client:* on a component that needs interactivity, then wondering why click handlers don't work.

SSR caching pattern

SSR without caching is just a slow website. Always pair SSR with a caching strategy:

// In an SSR endpoint or page
return new Response(JSON.stringify(data), {
  headers: {
    "Cache-Control": "public, s-maxage=60, stale-while-revalidate=300",
    "Content-Type": "application/json"
  }
});

When things go wrong

Read references/troubleshooting.md for a symptom-based guide. The top 5 issues:

1. "Component doesn't do anything" → Missing client:* directive
2. Build fails after adding integration → Version mismatch, check package.json
3. SSR returns 500 → Missing adapter or wrong output mode in config
4. Broken links after deploy → Base path not set, or trailing slash mismatch
5. Hydration mismatch errors → Server/client HTML differs (conditional rendering, dates, randomness)

File output conventions

When generating Astro project files:

• Always include the frontmatter fence (---) even if empty
• Use .astro extension for Astro components and pages
• Place pages in src/pages/, components in src/components/, layouts in src/layouts/
• Use TypeScript in frontmatter when the project uses TS
• Include astro.config.mjs with only the integrations and settings actually needed