If you’ve built enough sites with Astro, you build up a mental checklist of things that just work:

  • Always use the <Image /> component from astro:assets
  • Content collections live in src/content.config.ts
  • Use the lightest client:* directive possible
  • Never link Google Fonts from a CDN

These aren’t secrets, most are in the docs. But they’re easy to miss, and repeating them in every new project gets tiring.

So I packaged all that knowledge into a single Agent Skill I can hand to Cursor, Claude, or any other AI coding assistant.

What Are Agent Skills?

Agent Skills are a simple, open format for sharing specialized knowledge with AI agents. A skill is just a folder containing a SKILL.md file with clear metadata and instructions.

Agents automatically know when to use the skill and follow the detailed guidance every time. The format works across Claude Code, Cursor, Roo Code, Goose, and many others.

What the Astro Skill Covers

Scoped specifically to static sites on Astro v5+ (no SSR or hybrid mode). It works with any UI framework Astro supports.

Core Architecture Rules

  • Prefer .astro files for presentational UI
  • Minimal hydration: client:visible over client:load whenever possible
  • Small, focused islands
  • Local fonts via Fontsource only

Content Collections

Complete guidance for the modern src/content.config.ts setup, including schemas, image validation, relations, and ready-to-use templates for blogs, services, testimonials, etc.

SEO & Metadata

This is one of the strongest parts of the skill. It includes:

  • A complete, reusable Head.astro component with Open Graph tags, Twitter Cards, canonical URLs, and proper JSON-LD structured data
  • A detailed per-page SEO checklist covering title tags, meta descriptions, heading hierarchy, content quality, internal linking strategy, and more
  • Ready-made JSON-LD templates for WebSite, LocalBusiness, BlogPosting, Service, FAQPage, BreadcrumbList, and others

The AI will consistently apply these SEO best practices on every page it builds — something that’s normally easy to get wrong or forget.

Images, Pagination & More

  • Smart <Image /> usage and optimization tricks (including the useful downscaling pattern)
  • Static pagination with getStaticPaths()
  • Sitemap generation and dynamic robots.txt

Installation

The skill is open source: github.com/ianshk/astro-skills

Quick Install (any editor)

npx skills add ianshk/astro-skills

This installs the skill into your project and works with Claude Code, Cursor, Windsurf, Roo Code, and other Agent Skills-compatible editors.

Open Source

The best skills get better with community input — PRs welcome.

The Bigger Idea

Agent Skills turn one-off knowledge into something AI agents actually use on every project. If you have deep expertise in a framework, tool, or workflow, packaging it as a skill is one of the most practical ways to share it right now.

The Agent Skills spec makes it surprisingly easy to get started.

Feedback and contributions are very welcome!