Astro SEO

Astro SEO

Audits and improves the SEO setup of an Astro site against the full stack described in Astro SEO: the definitive guide. The skill covers nine areas — technical foundation, structured data, content, site structure, performance, sitemaps and indexing, agent discovery, redirects, and analytics — and produces drop-in code for anything missing or weak.

The opinionated spine of this skill is `@jdevalk/astro-seo-graph`. Most of the fixes route through it. If the project doesn't use it yet, installing it is the first recommendation.

Code recipes live in `AGENTS.md` — read it when you need to implement a specific fix. This file has the workflow and audit checklist.

Workflow

1. Detect the project — confirm this is an Astro site and understand its shape.
2. Audit — score nine categories and produce actionable findings.
3. Improve — generate or modify files to close the gaps. Recipes are in AGENTS.md.
4. Metadata pass — invoke metadata-check on every short string the skill generated (titles, descriptions, schema description fields, FAQ answers, frontmatter excerpts).
5. Verify — run the build, check validations pass, remind the user about non-file tasks (Search Console, Bing Webmaster Tools, IndexNow key verification).

Phase 0: Detect the project

Confirm the basics before auditing:

• astro.config.mjs / astro.config.ts exists.
• package.json has astro as a dependency.
• `site:` is set in `astro.config` — canonicals, sitemaps, and OG image URLs all derive from this. If it's missing, empty, or http://localhost, flag it as a blocking issue before anything else. This is the single most common misconfiguration.
• Content collections in src/content/ (or legacy src/pages/ markdown).
• Deployment target — read package.json, vercel.json, netlify.toml, wrangler.toml, or public/_headers to determine the host. This drives redirect and header syntax in Phase 2.
• Is `@jdevalk/astro-seo-graph` already installed? If yes, record the version and which features are wired (grep for <Seo, seoGraph(, createSchemaEndpoint, createSchemaMap, FuzzyRedirect, createIndexNowKeyRoute, createMarkdownEndpoint, createApiCatalog, gitLastmod). Check the installed version against the latest on npm with npm view @jdevalk/astro-seo-graph version. If the project is behind, recommend an upgrade in Phase 2 before auditing feature gaps — the package ships new defaults and fixes regularly, and an outdated version is a plausible cause for any audit finding. Phase 2 branches on this.
• Is the site multilingual? Check for i18n in astro.config or multiple locale directories under src/content/. If yes, hreflang matters; if no, skip it.

Ask only what you can't detect. Don't ask the user what the site is about — read astro.config.mjs and the homepage content.

Phase 1: Audit

Score each category out of 10. For each, give 2–4 specific findings that quote the actual code or config. Within each category, checks are tiered:

• Must — ship blockers. A failure here causes visible SEO regression.
• Should — standard practice. Skipping costs reach.
• Nice — forward-looking or situational. Useful but not baseline for every site.

Skip Nice checks for small personal blogs unless the user asks for the full treatment.

1. <Seo> component and head metadata (/10)

• Must — single component for all head metadata (not scattered across layouts).
• Must — site: in astro.config is set to the production origin.
• Must — canonical URLs derived from site config with tracking params stripped.
• Must — canonical omitted when noindex is true (per Google's recommendation).
• Must — fallback chain for missing SEO fields: seo.title → title → siteName; seo.description → excerpt → first paragraph. Pages with blank titles or descriptions are the most common symptom of a broken fallback.
• Should — robots meta includes max-snippet:-1, max-image-preview:large, max-video-preview:-1.
• Should — Twitter tags suppressed when they duplicate Open Graph (Twitter falls back automatically).
• Should — hreflang alternates present on multilingual sites. Skip if monolingual.
• Nice — uses @jdevalk/astro-seo-graph's <Seo> component rather than hand-rolled. (Hand-rolled that covers everything above is fine; this skill nudges toward the package because it handles the fallback chain and robots rules by default.)

2. Structured data / JSON-LD graph (/10)

• Single flat Article object, or a linked @graph with multiple entities?
• Entities wired with @id references?
• WebSite, Blog/WebPage, Person/Organization, BlogPosting/Article, BreadcrumbList, ImageObject all present where relevant?
• Trust signals: publishingPrinciples, copyrightHolder, copyrightYear, knowsAbout, SearchAction?
• Validates in Rich Results Test and ClassySchema?

3. Content collections and SEO schema (/10)

• Content collections defined with Zod schemas?
• seoSchema from @jdevalk/astro-seo-graph enforcing title (5–120) and description (15–160) lengths?
• Required fields (publishDate, title, excerpt) enforced at build time?
• Markdown-stripped articleBody exposed in schema endpoints (up to 10K chars)?

4. Open Graph images (/10)

• Every page has an OG image, or many missing?
• 1200×675 (Google Discover minimum 1200px wide, 16:9 ratio)?
• Generated at build time via satori + sharp, or manual?
• JPEG (social platforms don't reliably support WebP/AVIF)?
• Route derives OG URL from the slug automatically?
• Every <img> in rendered HTML has an alt attribute (or alt="" / role="presentation" for decorative images)? validateImageAlt on seoGraph() catches this at build time in ≥ 1.1.0.

5. Sitemaps and indexing (/10)

• Must — @astrojs/sitemap installed, sitemap index reachable.
• Must — robots.txt references the sitemap index.
• Must — RSS feed exists (@astrojs/rss), advertised via <link rel="alternate" type="application/rss+xml">, contains full post content (not truncated excerpts).
• Should — split per-collection via chunks option (sitemap-posts-0.xml, etc.) — much easier to debug indexing in GSC.
• Should — lastmod populated from git commit timestamps, not frontmatter dates or CI file timestamps. @jdevalk/astro-seo-graph ≥ 1.4.0 exports gitLastmod(filePath, { excludeCommits, depth }) for this — it returns the committer date of the most recent non-excluded commit that touched the file, or null if git is unavailable. Wire it into the sitemap serialize callback. If the codebase has a hand-rolled execSync('git log ...') helper, replace it with the package export — the export handles bulk-commit exclusion (imports, reformats) which a naïve -1 lookup can't.
• Should — IndexNow integrated and submitting on each build, with key verification route at /[key].txt. ≥ 1.0.1 excludes /404 from submissions by default. Gate submission on the production host (e.g. process.env.CF_PAGES === '1' && CF_PAGES_BRANCH === 'main', VERCEL_ENV === 'production', CONTEXT === 'production'). Unconditional submission pings the endpoint on every local npm run build and preview deploy with URLs the production host hasn't served yet, which gets the key marked invalid (403) and forces rotation.

6. Agent discovery (/10)

• Should — schema endpoints (/schema/*.json) exposing corpus-wide JSON-LD.
• Should — schema map (/schemamap.xml) listing all endpoints, with Schemamap: directive in robots.txt.