astro-seo
starsforks
How to install astro-seo?
jdevalk/skills/astro-seo
$npx -y skills add jdevalk/skills --skill astro-seoAudits and improves SEO for Astro sites. Use when the user asks to audit, set up, or improve SEO on an Astro site, or mentions head metadata, structured data, JSON-LD, sitemaps, IndexNow, Open Graph images, schema endpoints, NLWeb, hreflang, or search engine indexing in an Astro
SKILL.md
| 1 | # Astro SEO |
| 2 | |
| 3 | Audits and improves the SEO setup of an Astro site against the full stack described in [Astro SEO: the definitive guide](https://joost.blog/astro-seo-complete-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. |
| 4 | |
| 5 | The opinionated spine of this skill is [`@jdevalk/astro-seo-graph`](https://github.com/jdevalk/seo-graph). Most of the fixes route through it. If the project doesn't use it yet, installing it is the first recommendation. |
| 6 | |
| 7 | **Code recipes live in `AGENTS.md`** — read it when you need to implement a specific fix. This file has the workflow and audit checklist. |
| 8 | |
| 9 | ## Workflow |
| 10 | |
| 11 | 1. **Detect the project** — confirm this is an Astro site and understand its shape. |
| 12 | 2. **Audit** — score nine categories and produce actionable findings. |
| 13 | 3. **Improve** — generate or modify files to close the gaps. Recipes are in `AGENTS.md`. |
| 14 | 4. **Metadata pass** — invoke `metadata-check` on every short string the skill generated (titles, descriptions, schema `description` fields, FAQ answers, frontmatter excerpts). |
| 15 | 5. **Verify** — run the build, check validations pass, remind the user about non-file tasks (Search Console, Bing Webmaster Tools, IndexNow key verification). |
| 16 | |
| 17 | --- |
| 18 | |
| 19 | ## Phase 0: Detect the project |
| 20 | |
| 21 | Confirm the basics before auditing: |
| 22 | |
| 23 | - `astro.config.mjs` / `astro.config.ts` exists. |
| 24 | - `package.json` has `astro` as a dependency. |
| 25 | - **`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. |
| 26 | - Content collections in `src/content/` (or legacy `src/pages/` markdown). |
| 27 | - **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. |
| 28 | - **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. |
| 29 | - **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. |
| 30 | |
| 31 | 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. |
| 32 | |
| 33 | --- |
| 34 | |
| 35 | ## Phase 1: Audit |
| 36 | |
| 37 | 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: |
| 38 | |
| 39 | - **Must** — ship blockers. A failure here causes visible SEO regression. |
| 40 | - **Should** — standard practice. Skipping costs reach. |
| 41 | - **Nice** — forward-looking or situational. Useful but not baseline for every site. |
| 42 | |
| 43 | Skip **Nice** checks for small personal blogs unless the user asks for the full treatment. |
| 44 | |
| 45 | ### 1. `<Seo>` component and head metadata (/10) |
| 46 | |
| 47 | - **Must** — single component for all head metadata (not scattered across layouts). |
| 48 | - **Must** — `site:` in `astro.config` is set to the production origin. |
| 49 | - **Must** — canonical URLs derived from `site` config with tracking params stripped. |
| 50 | - **Must** — canonical omitted when `noindex` is true (per Google's recommendation). |
| 51 | - **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. |
| 52 | - **Should** — `robots` meta includes `max-snippet:-1`, `max-image-preview:large`, `max-video-preview:-1`. |
| 53 | - **Should** — Twitter tags suppressed when they duplicate Open Graph (Twitter falls back automatically). |
| 54 | - **Should** — `hreflang` alternates present on multilingual sites. Skip if monolingual. |
| 55 | - **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 becaus |
People who liked this also viewed
6 picksType
- seo-auditWhen the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tagSkillsJul 2026
- copywritingWhen the user wants to write, rewrite, or improve marketing copy for any page — including homepage, landing pages, pricing pages, feature pages, about pages, or product pages. Also use when the user sSkillsJul 2026
- marketing-psychologyWhen the user wants to apply psychological principles, mental models, or behavioral science to marketing. Also use when the user mentions 'psychology,' 'mental models,' 'cognitive bias,' 'persuasion,'SkillsJul 2026
- content-strategyWhen the user wants to plan a content strategy, decide what content to create, or figure out what topics to cover. Also use when the user mentions "content strategy," "what should I write about," "conSkillsJul 2026
- programmatic-seoWhen the user wants to create SEO-driven pages at scale using templates and data. Also use when the user mentions "programmatic SEO," "template pages," "pages at scale," "directory pages," "location pSkillsJul 2026
- marketing-ideasWhen the user needs marketing ideas, inspiration, or strategies for their SaaS or software product. Also use when the user asks for 'marketing ideas,' 'growth ideas,' 'how to market,' 'marketing stratSkillsJul 2026
